Jump to content

Using UI widgets

  1. Introduction

    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
  2. ips.ui.hovercard

    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
  3. ips.ui.infinitescroll

    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
  4. ips.ui.lightbox

    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
  5. ips.ui.menu

    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
  6. ips.ui.pageAction

    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
  7. ips.ui.pagination

    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
  8. ips.ui.rating

    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
  9. ips.ui.selectTree

    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
  10. ips.ui.sideMenu

    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
  11. ips.ui.spoiler

    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
  12. ips.ui.alert

    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( {
  13. ips.ui.stack

    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
  14. ips.ui.sticky

    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
  15. ips.ui.tabbar

    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
  16. ips.ui.tooltip

    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 @
  17. ips.ui.truncate

    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>  
  18. ips.ui.autoCheck

    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
  19. ips.ui.autoComplete

    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:
  20. ips.ui.captcha

    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
  21. ips.ui.chart

    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)
  22. ips.ui.dialog

    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&
  23. ips.ui.flashMsg

    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
  24. ips.ui.grid

    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
  • Create New...