-
Initializing widgets
UI widgets can now be created on elements without needing to write any code. This is done by specifying special attributes on the element using the HTML5 data attributes. Widgets each define their own behaviors - some wait for user interactions, others might immediately change the display when executed.
Usage
Each UI widget has a base attribute that identifies it, and causes the element to be passed to the widget module to be handled. All widget attributes hav
-
Description
The hovercard widget can be used to display a popup with remote content, which is attached to a trigger element.
Example
@todo
Usage
The hovercard widget is initialized by including the widget key attribute on a link:
<a href='...' data-ipsHover>Hover on me</a>
The URL that the link points to is also the URL that is called to fetch the hovercard content, by default.
Options
target
(String; optional)
If
-
Description
Infinite scrolling is a technique whereby new content is loaded into the page automatically when the user scrolls near the bottom of the page or section. It's a technique commonly associated with sites like Facebook and Twitter.
Note: Infinite scrolling can present user interface challenges if not used wisely, including not being able to reach links at the bottom of the page. Before choosing to use infinite scrolling, consider the usability impacts it may have. It may be mo
-
Description
The Lightbox widget implements a commonly-seen interface convention whereby images can be clicked to view them at a larger size inside a popup that appears on the page. In addition, related images are grouped so that they can be scrolled through inside the popup. IPS4's lightbox also supports built-in commenting.
Example
@todo
Usage
A lightbox can be initialized on a single image as simply as:
<img src='http://url/to/image' data-ipsLightb
-
Description
The menu widget adds interactivity to menu elements created with HTML & CSS. Menus present a list of options for the user to choose from as a popup 'attached' to the trigger element. Menus can optionally allow users to check one or more of the options.
Usage
The menu widget does not build the menu element itself; it should exist in the page as an HTML element with the appropriate CSS classes already added to it (a decision made so that menus can be accessibl
-
Description
The PageAction widget implements an interface that enables actions to be taken on multiple items on the page. This model is commonly used for multi-moderation actions.
Note: The PageAction widget can work in tandem with the ips.ui.autoCheck widget to provide a streamlined workflow that saves the user from having to manually click many checkboxes to perform actions.
Example
@todo
Usage
The PageAction widget requires certain elements to exist
-
Description
The Pagination widget wraps pagination HTML in order to emit events that controllers can use to provide interactivity. It also adds some basic usability to the page jump menu. It does not handle fetching pages itself. Instead, the events it emits are used by other controllers to load new content.
Note: The Pagination widget will generally be implemented by the PHP classes used to build tables, lists etc. Consult the relevant backend documentation for information on automati
-
Description
The Rating widget takes a group of radio controls with numerical values, and replaces them with clickable stars so that users can indicate a rating value.
Example
@todo
Usage
To use the rating widget, your HTML should contain the following structure:
<span data-ipsRating>
<input type="radio" name="ratingValue" id="ratingValue_1" value="1"> <label for="ratingValue_1">1</label>
<input type="radio" name="ratingValue
-
Description
The SelectTree widget allows users to select items from a tree-like structure efficiently, without the server having to generate the entire tree immediately.
Note: This widget is designed for use only with the \IPS\Helpers\Form\Node helper.
Options
placeholder
(String; optional; default 'Select')
Text to use as the placeholder when no items are selected.
multiple
(Boolean; optional; default false)
Are users allowed to select multip
-
Description
The SideMenu widget works with standard side menu markup and makes it both interactive and improves its functionality when the user is visiting on a mobile device.
Usage
In most cases, a side menu should be built using the standard CSS classes. The data attribute is then added to the wrapper element.
Making side menus responsive
When the widget is to be used in responsive mode, an additional title should be supplied within the element, with the class i
-
Description
The spoiler widget is designed to hide designated text until the user clicks to reveal it. It is typically used on content posted by users from CKEditor.
Usage
Simply add the widget key attribute to the element containing the text to be hidden:
<div data-ipsSpoiler>
This text will be hidden from users initially
</div>
Options
The Spoiler widget does not have any configuration options.
Events emitted by ips.ui.spoiler
-
Description
The alert widget is designed to replace the built-in javascript alert, providing a more pleasant user experience as well as more flexible options and built in callbacks. Several other types of alert dialogs are supported too.
Usage
Unlike most UI widgets, the alert widget is instantiated programatically, rather than using the data API - typically as a response to a user action in a controller, for example.
An alert is created as follows:
ips.ui.alert.show( {
-
Description
The stack widget is a special form control which enables users to enter multiple values for a form field. In IPB 3.x, this was achieved by entering values in a textarea with each value on a new line. This widget is designed to make that functionality more user friendly.
Note: It is expected that the \IPS\Helpers\Form class will be used to build the HTML for stackable controls. Consult the documentation for the PHP class for more information.
Options
sortabl
-
Description
The sticky element widget aids navigation, by causing elements to automatically stick to the browwer window when they would otherwise be off-screen due to scrolling. This is a UI concept that is particularly useful for toolbars.
Usage
The widget key attribute should be specified on the element that will become 'sticky'.
<div id='elWrapper'>
<div id='elStickyElement' data-ipsSticky>
...
</div>
</div>
The wrapper element represen
-
Description
The tab bar widget allows users to switch between individual panels of content. The widget can build panels either from content that already exists on the page, or by loading it from a remote source. The browser URL can additionally be updated to reflect the permalink of the individual tab being selected.
Usage
The tab bar itself should be constructed manually in the markup, with the tabs linking to a static page. This enables the page to be used even when javas
-
Description
The Tooltip widget is designed to show a small helpful message in a balloon when certain elements are focused or hovered over. They are particularly useful used in conjunction with toolbars, to provide more information on what action a toolbar button will trigger.
Tooltip text should be succinct - never more than a few words on a single line.
Example
@
-
Description
The truncate widget is used to make previews or short versions of blocks of text. It supports removing the extra text entirely, or hiding it behind a 'read more' button. It also works on blocks of rich text containing other media in HTML.
Usage
The widget attribute data-ipsTruncate should be added to an element which wraps the content to be truncated. e.g:
<div data-ipsTruncate>
<p>Many lines of rich content...</p>
</div>
-
Description
The autoCheck widget makes it simple to select checkboxes of a certain type on a page. This is useful for moderation tools, for example - simply by specifying a filter, topics that match that filter can be selected.
Note: The autoCheck widget works in conjunction with the ips.ui.menu widget. It will not work on other kinds of elements.
Example
@todo
Usage
The widget itself is initialized on the menu trigger element:
<!-- The trigger -->
<a h
-
Description
The autocomplete widget adds two groups of functionality to a text input. Firstly, it adds support for suggestions based on what the user is typing, and secondly, it adds support for tokenization, allowing the user to enter multiple distinct values into one field. This functionality is useful for entering tags, for example.
Example
@todo
Usage
The autocomplete widget should be initialized on a text input with the correct widget key attribute:
-
Description
The Captcha widget is designed to allow captcha to be used dynamically, including situations where it is initialized after the page has loaded (e.g. in popups). The necessary javascript libraries from providers are loaded on the fly. The widget presently supports reCaptcha and KeyCaptcha.
Usage
The widget is initialized as follows:
<div data-ipsCaptcha data-ipsCaptcha-service='recaptcha' data-ipsCaptcha-key='...'> </div>
Options
se
-
Description
The Chart widget takes a specially-formatted table of data, and uses Google Charts to render it as an attractive chart.
The Chart widget is designed for use soley with the output of the \IPS\Helpers\Chart class and is documented here for completeness only. Consult the documentation for the PHP class for more information.
Options
type
(String; required)
Specifies the type of chart to render, e.g. LineChart
extraOptions
(Object; optional)
-
Description
The dialog widget displays popup windows within the page, typically loading content from a remote source.
Usage
A dialog is defined simply by including the widget key as an attribute on a trigger element. It is recommended that the trigger element be a link or button, so that if the user has javascript disabled their browser can take them to a full-page version of the dialog contents.
<a href='...' data-ipsDialog data-ipsDialog-url='...'>Launch dialog&
-
Description
The flashMsg widget can be used to display a 'flash message' to the user - a short notification that appears on the screen for a few seconds, before disappearing. It is commonly used for 'success' messages when an action occurs.
Example
@todo
Usage
A flash message can be created with the data API, as follows:
<span data-ipsFlashMsg data-ipsFlashMsg-text='My message'>
The element used with this method is not important; the widget wil
-
Description
The Grid widget enhances the standard CSS grid with additional functionality, enabling dynamic resizing and equalizing heights of rows.
Usage
The grid widget should be initialized on the same element that contains the ipsGrid CSS classes:
<div class='ipsGrid ipsGrid_collapsePhone' data-ipsGrid data-ipsGrid-minItemSize='200' data-ipsGrid-maxItemSize='400'>
<div class='ipsGrid_span4'>Item</div>
<div class='ipsGrid_span4'>Item</di