Rikki

Description The form module provides classes for styling forms throughout the suite, with a range of options available to change the appearance and flow. Usage A form should have the base class ipsForm. In many cases this will be directly on the <form> element, but it can actually appear on any element that contains form elements. The recommended basic DOM structure for a form is as follows: <form class='ipsForm'> <ul> <li class='ipsFieldRow'> ... </li> <li class='ipsFieldRow'> ... </li> </ul> </form> In this structure, each field row within the form appears as a <li> element with the class ipsFieldRow Form layouts There are two layout options for forms: vertical or horizontal. In a vertical form, field labels are displayed above the field element. In horizontal forms, the label appears to the left of the field element. The layout can be controlled by adding the classes ipsForm_vertical or ipsForm_horizontal to the root form element, respectively. Example of both types: Vertical form Horizontal form Note: On small devices and with the responsive CSS enabled, horizontal layout forms will automatically collapse to become vertical layout so that they are easily readable. Field Rows Each field row within the form has a number of options available, depending on the type of field. The basic structure for a field row is as follows: <li class='ipsFieldRow'> <label for='example' class='ipsFieldRow_label'> Example field </label> <div class='ipsFieldRow_content'> <input type='text' id='example' value=''> </div> </li> The row receives the base class ipsFieldRow. Within this element are the label and content elements. The label receives the class ipsFieldRow_label, while the content wrapper receives the class ipsFieldRow_content. The content element can theoretically contain anything, though naturally it should be kept simple for best usability. There are several additional classes that can be applied to field rows. ipsFieldRow_primary A primary field row causes text inputs to be enlarged to convey importance ipsFieldRow_fullWidth Causes appropriate form controls (primarily text-based/select inputs) to take up all available horizontal space ipsFieldRow_noLabel If no label is needed, this class can be used to ensure spacing still works as expected. Do give thought to usability before deciding to remove a label. Required fields To add a 'required' indicator to a field, an element with the class ipsFieldRow_required can be added inside the label element, like so: <label for='elExample' class='ipsFieldRow_label'> Field title <span class='ipsFieldRow_required'>Required</span> </label> On horizontal-layout forms, the text inside the 'required' indicator element is automatically replaced with an asterisk in order to conserve space. Field descriptions Field descriptions can be added immediately following the form control, inside of the field content element, by using the class ipsFieldRow_desc. For example: <div class='ipsFieldRow_content'> <input type='text' size='30'><br> <span class='ipsFieldRow_desc'>This is a field description</span> </div> Checkboxes/Radios The markup and classes used for checkboxes or radio buttons are by necessity a little different to that described above, because typically the element will sit to the left of the label and appear inline with it. This is an example of the markup used for checkboxes or radios (note that although the class refers to 'checkbox', it can be used for both types of control): <li class='ipsFieldRow ipsFieldRow_checkbox'> <span class='ipsCustomInput'> <input type='checkbox' id='elExampleCheckbox'> <span></span> </span> <div class='ipsFieldRow_content'> <label for='elExampleCheckbox'>Remember me</label> </div> </li> There are a few differences here. Firstly, the class ipsFieldRow_checkbox has been added to the field row to denote that this row should be handled differently. Secondly, the checkbox control now sits as a direct descendant of the row element, while the label moves inside the content element. Finally, the checkbox itself is wrapped in an element with the classname ipsCustomInput, which allows us to style checkboxes and radios using CSS. Remember me Horizontally-grouped checkboxes Another common way to display checkbox/radio controls is as a horizontal list of choices. This can be done with the following markup: <li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Choose an option</span> <ul class='ipsFieldRow_content ipsList_reset'> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox1'> <span></span> </span> <label for='checkbox1'>Option 1</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox2'> <span></span> </span> <label for='checkbox2'>Option 2</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='radio' id='checkbox3'> <span></span> </span> <label for='checkbox3'>Option 3</label> </li> </ul> </li> Here we're building the field row content element as a list (we use ipsList_reset to remove margins and padding), with each list item receiving the class ipsFieldRow_inlineCheckbox to align them horizontally. The above example produces the following result: Choose an option Option 1 Option 2 Option 3 Vertically-grouped checkboxes You can also group checkboxes and radio controls in a vertical list. The markup looks like this: <li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Choose an option</span> <ul class='ipsFieldRow_content ipsField_fieldList'> <li> <span class='ipsCustomInput'> <input type='checkbox' id='option1'> <span></span> </span> <div class='ipsField_fieldList_content'> <label for='option1'>Option 1</label><br> <span class='ipsFieldRow_desc'>Option 1 description</span> </div> </li> <li> <span class='ipsCustomInput'> <input type='checkbox' id='option2'> <span></span> </span> <div class='ipsField_fieldList_content'> <label for='option1'>Option 2</label><br> <span class='ipsFieldRow_desc'>Option 2 description</span> </div> </li> </ul> </li> Which renders as: Choose an option Option 1 Option 1 description Option 2 Option 2 description Field loading state Text-based form inputs (text inputs, date fields, textareas, etc.) can be shown in a loading state by adding the class ipsField_loading (usually with Javascript). This causes the field to show a loading throbber in the field. Loading example Note: this effect is achieved using background images. If you define styles for form fields that specify a background image, the loading effect may not render correctly. Grouping field rows Adding section headers You can add a section header to a form by adding a header element of your choice with the class ipsFieldRow_section, like this: <li> <h2 class='ipsFieldRow_section'>A section header</h2> </li> Fieldsets Fields can be grouped together in related sets by using fieldsets with the class ipsForm_group. The markup for this kind of structure looks like this: <div class='ipsForm ipsForm_horizontal'> <fieldset class='ipsForm_group'> <legend class='ipsForm_groupTitle'>First group</legend> <ul class='ipsForm_groupContent'> <li class='ipsFieldRow'> <!-- Field row content --> </li> <li class='ipsFieldRow'> <!-- Field row content --> </li> </ul> </fieldset> <fieldset class='ipsForm_group'> <legend class='ipsForm_groupTitle'>Second group</legend> <ul class='ipsForm_groupContent'> <li class='ipsFieldRow'> <!-- Field row content --> </li> <li class='ipsFieldRow'> <!-- Field row content --> </li> </ul> </fieldset> </div> This produces (with field row content added): First group Field title Field title Second group Field title Field title The class ipsForm_group is added to a container element - this will typically be a fieldset. Within that element will be a title element, with the class ipsForm_groupTitle. This too can be any element, but a legend element will usually make most sense. Finally, there's an element with the class ipsForm_groupContent which wraps all of the field rows in the group. Complete form example Here is a complete example of a form, which can be toggled between vertical and horizontal layouts for demonstration purposes. The markup for this example follows after. Name Required E-mail Address Required We keep this confidential Please send me Updates Offers I agree to the terms and conditions Submit <ul class='ipsForm ipsForm_horizontal' id='form_example'> <li class='ipsFieldRow ipsFieldRow_primary ipsFieldRow_fullWidth'> <label class='ipsFieldRow_label'>Name <span class='ipsFieldRow_required'>Required</span></label> <div class='ipsFieldRow_content'> <input type='text' size='30' placeholder='First name'> </div> </li> <li class='ipsFieldRow'> <label class='ipsFieldRow_label'>E-mail Address <span class='ipsFieldRow_required'>Required</span></label> <div class='ipsFieldRow_content'> <input type='text' size='30' placeholder='example@me.com'><br> <span class='ipsFieldRow_desc'>We keep this confidential</span> </div> </li> <li class='ipsFieldRow'> <span class='ipsFieldRow_label'>Please send me</span> <ul class='ipsFieldRow_content ipsList_reset'> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <label>Updates</label> </li> <li class='ipsFieldRow_inlineCheckbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <label>Offers</label> </li> </ul> </li> <li class='ipsFieldRow ipsFieldRow_checkbox'> <span class='ipsCustomInput'> <input type='checkbox'> <span></span> </span> <div class='ipsFieldRow_content'> <label class='ipsFieldRow_label'><strong>I agree to the terms and conditions</strong></label> </div> </li> <li class='ipsFieldRow'> <div class='ipsFieldRow_content'> <button type='submit' class='ipsButton ipsButton_medium ipsButton_primary'>Submit</button> </div> </li> </ul>

Description The data list CSS module allows us to display complex lists, while rearranging the display in situations that demand it, such as on small devices. Usage A data list consists of a wrapper and individual list items, which can contain various types of data. In most cases, a data list would use one of the HTML list elements (such as ul or ol) for semantic purposes, though this isn't necessarily required. The basic markup structure is as follows: <ol class='ipsDataList' itemscope itemtype="http://schema.org/ItemList"> <meta itemprop="itemListOrder" content="Descending"> <li class='ipsDataItem ipsDataItem_unread' itemprop="itemListElement"> ... </li> <li class='ipsDataItem' itemprop="itemListElement"> ... </li> <li class='ipsDataItem' itemprop="itemListElement"> ... </li> </ol> The root element should be given the classname ipsDataList. Individual list items receive the classname ipsDataItem. To indicate unread status within a row, add the class ipsDataItem_unread to the list item. The other elements in the row may style differently in 'unread' rows to indicate that status. Within the ipsDataItem, multiple other elements can exist which (at desktop resolution) represent cells of data. On smaller devices, these elements reflow to give a more suitable layout. These elements are outlined below. An example of a data list row showing many of these options is shown here: Pre-sales questions Question before you purchase? Post here and get help from both IPS and from other clients. You can also email sales@invisionpower.com for assistance. Company Feedback General Suite Feedback 18,852 Posts BBCode’s description variable By admin Yesterday Row Spacing By default, rows are comfortably spaced. An additional class ipsDataList_reducedSpacing is available where reduced horizontal cell padding is desired. Zebra Striping By default, zebra striping (alternate background colors) are not included on data lists. To add them, add the class ipsDataList_zebra to the data list wrapper. Main content cell - ipsDataItem_main Represents the primary data in the row, typically containing the row title and some metadata. Expands to take up whatever space is left by the remaining cells in the row. Example: <div class='ipsDataItem_main'> <h4 class='ipsDataItem_title'><a href='#'>Item title</a></h4> <p class='ipsDataItem_meta'> By testadmin, yesterday, 2:21pm </p> </div> Within this cell, ipsDataItem_title defines the title element, while ipsDataItem_meta defines some non-specific metadata associated with the title. In the main cell, a sub-list can be specified for data such as sub-forums or sub-albums. This should appear after the ipsDataItem_meta element. An example of the markup: <ul class='<strong>ipsDataItem_subList</strong> ipsList_inline'> <li><a href='#'>Sub-item 1</a></li> <li class='ipsDataItem_unread'><a href='#'>Sub-item 2</a></li> </ul> Statistics cell - ipsDataItem_stats This class is applied to an element which represents statistics for this row, such as the number of replies in a topic or the number of downloads a file has. An example of its usage: <dl class='ipsDataItem_stats'> <dt class='ipsDataItem_stats_number'>18,852</dt> <dd class='ipsDataItem_stats_type'>Posts</dd> </dl> The data within this element is marked up with two additional classes: ipsDataItem_stats_number - represents the actual statistical value ipsDataItem_stats_type - represents the type of data The additional class ipsDataItem_statsLarge can be added to the element where the statistic is particularly important. This significantly increases the font size of the value to help it stand out. Last poster cell - ipsDataItem_lastPoster Used to represent the 'last poster' information, such as in a topic or other record. An example of its use: <ul class='<strong>ipsDataItem_lastPoster ipsDataItem_withPhoto</strong>'> <li><img src='images/photo.jpeg'></li> <li><a href='#'>Username</a></li> <li><time data-short='1 dy'>Time stamp</time></li> </ul> Within this element are two or three more elements. If the ipsDataItem_withPhoto class is used, the first element should contain a user photo, otherwise, the first element can be omitted. The second element typically will contain the username, while the last will contain the time information. The last element contains a time element with a data-short attribute. This attibute should contain a very short representation of the date/time, and it is used on small devices. The PHP framework generates these for you. Generic cells A number of generic cell sizes are available for custom types of data. The cell should contain the class ipsDataItem_generic and one of the following classes: ipsDataItem_size1 - 50px ipsDataItem_size2 - 75px ipsDataItem_size3 - 100px ipsDataItem_size4 - 125px ipsDataItem_size5 - 150px ipsDataItem_size6 - 175px ipsDataItem_size7 - 200px ipsDataItem_size8 - 225px ipsDataItem_size9 - 250px Other cell types In addition to the main cell types above, there are additional cell classes that can be used. ipsDataItem_icon - A column which contains a status icon for the row, such as a forum icon ipsDataItem_modCheck - A narrow column that should hold a moderator checkbox to select the row Coloring rows Four additional classes are available to optionally add a background color to the row to denote status: ipsDataItem_new - New items ipsDataItem_warning - Items showing a warning state ipsDataItem_error - Items with an error ipsDataItem_info - An informational state Putting it together Here is the code for the example shown at the top of the page: <ol class='ipsDataList'> <li class='ipsDataItem ipsClearfix ipsDataItem_unread'> <div class='ipsDataItem_main'> <h4 class='ipsDataItem_title'><a href='#'>Pre-sales questions</a></h4> <p class='ipsDataItem_meta'> Question before you purchase? Post here and get help from both IPS and from other clients. You can also email sales@invisionpower.com for assistance. </p> <ul class='ipsDataItem_subList ipsList_inline'> <li><a href='#'>Company Feedback</a></li> <li class='ipsDataItem_unread'><a href='#'>General Suite Feedback</a></li> </ul> </div> <dl class='ipsDataItem_stats ipsDataItem_statsLarge'> <dt class='ipsDataItem_stats_number'>18,852</dt> <dd class='ipsDataItem_stats_type ipsType_light'>Posts</dd> </dl> <ul class='ipsDataItem_lastPoster ipsDataItem_withPhoto'> <li><a href='#' class='ipsUserPhoto ipsUserPhoto_mini ipsPos_left'><img src='image.jpg' alt=''></a></li> <li><a href='#'>BBCode’s description variable</a></li> <li>By <a href='#'>admin</a></li> <li><time class='ipsType_light' data-short='1 dy'>Yesterday</time></li> </ul> <div class='ipsDataItem_modCheck'> <input type='checkbox' checked> </div> </li> </ol>

Description The grid module provides classes for building layouts based on a flexible 12-column grid, with automatic margins, and with additional classes to enable the layout to collapse properly on smaller devices. Usage A grid should be made up of a wrapper element with the class ipsGrid, and direct descendants with appropriate size classes applied (see below). For example: <div class='ipsGrid'> <div class='ipsGrid_span3'>Span 3</div> <div class='ipsGrid_span3'>Span 3</div> <div class='ipsGrid_span4'>Span 4</div> <div class='ipsGrid_span2'>Span 2</div> </div> This would render as: Span 3 Span 3 Span 4 Span 2 Grid classes ipsGrid_span1 through ipsGrid_span12 are available for the various column sizes. Wrapping Grid Items Elements in a grid will automatically neatly wrap to new rows, providing every item in the grid uses the same span width and height, without you needing to manually create new row structures. For example: <div class='ipsGrid'> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> </div> Span 6 Span 6 Span 6 Span 6 For grids where your items may differ in height or width, consider the ips.ui.grid widget instead. Responsiveness To cause the grid layout to collapse on smaller devices, add either ipsGrid_collapseTablet or ipsGrid_collapsePhone to the class list on the wrapper element, like so: <div class='ipsGrid ipsGrid_collapsePhone'> ... </div>

Description The column module, unlike the grids module, provides classes that enable layouts comprising both fixed and fluid columns to be easily created. This is a layout often used for fixed sidebars with fluid content areas, for example. Additional classes are available to collapse the layout on smaller devices. Usage A column layout consists of a wrapper element, with the column elements as direct descendants of the wrapper. No other layout classes should be applied directly to the column elements. An example of a column layout: <div class='ipsColumns'> <div class='ipsColumn ipsColumn_medium'>Fixed column</div> <div class='ipsColumn ipsColumn_fluid'>Fluid column</div> </div> This would render as follows (background colors and padding added for clarity): Fixed column Fluid column The wrapper receives the classname ipsColumns (note: plural), while individual columns receive the classname ipsColumn (note: singular). Column Sizing A number of different classnames are available to change the column sizing. One of these classes should be applied to each column in addition to the base ipsColumn classname. ipsColumn_veryNarrow - 50 pixels wide ipsColumn_narrow - 120 pixels wide ipsColumn_medium - 200 pixels wide ipsColumn_wide - 280 pixels wide ipsColumn_veryWide - 360 pixels wide ipsColumn_fluid - Takes up remaining space; should be used on all fluid columns Border Spacing By default, no spacing is provided between columns (see example above). Spacing can be included around columns by using one of the three following classnames on the root ipsColumns element: ipsColumns_verticalSpacing - 15 pixels vertical spacing ipsColumns_horizontalSpacing - 15 pixels horizontal spacing ipsColumns_bothSpacing - 15 pixels spacing on all sides The spacing can be halved by also including the ipsColumns_halfSpacing classname. <div class='ipsColumns ipsColumns_bothSpacing ipsColumns_halfSpacing'> <div class='ipsColumn ipsColumn_medium'>Fixed column</div> <div class='ipsColumn ipsColumn_fluid'>Fluid column</div> </div> Fixed column Fluid column Responsiveness To cause the layout to collapse on smaller devices, add the classnames ipsColumns_collapseTablet or ipsColumns_collapsePhone to the wrapper element. Columns will collapse into source-order, one after the other.

Introduction In order to properly differentiate between CSS classes and HTML elements that form part of the IPS4 framework and those that do not, and in order to create a logical structure that can be understood at a glance, naming conventions are applied as follows. Framework classes & elements The IPS4 CSS framework is split into loosely-defined 'modules'. A module groups together related styles in a single file, with the aim of making it clearer which styles will be applied to a given element, and also to make it easier to find those styles to edit in the CSS files. All framework classes and elements take the name format ipsModule, where Module is the type of style being defined. Within a module, additional classes can be defined in the format ipsModule_option. Note that the module name and module options both use lowerCamelCase notation, with the module name and option separated by an underscore. Normally, an element will receive the base module class, plus some options. There are some cases where only the option class is needed; see individual module documentation for details. In general, the framework shouldn't be used with element IDs, since this restricts their use to one per page. The exception to this is aspects of the layout module, where page structure will naturally only exist once. Example of framework names: .ipsMenu .ipsTabs_item #ipsLayout_mainArea .ipsComment_hasChildren Writing CSS for custom themes As a rule, you shouldn't edit the framework CSS files directly. Doing so is prone to breaking future updates, or at least making it harder to upgrade your site between versions. Instead, all of your changes should live in the custom.css file at /core/front/custom/. You can create other CSS files within the custom directory if you wish and these will also be included. CSS files in the custom directory are not modified by the IPS4 upgrader, meaning your changes will safely persist across versions. Determining which elements use which CSS classes When editing your theme, we recommend you make use of the developer tools available in your browser to inspect the page and find out which CSS classes are applied to elements. Consult the documentation for your choice of browser to find out how to do this. This is an example of Chrome's Web Inspector: Writing CSS for custom applications CSS for your custom applications belongs in the <app>/dev/css/front/ directory. Consult the PHP framework documentation for information on using CSS files you create here.

Description The URL utility makes it easier to work with URLs by returning comprehenive information about a URL you supply, including query parameters, protocol, domain and more. The URL utility is a wrapper around the parseUri library by Steven Levithan. Example ips.utils.url.getParam('page', 'http://www.test.com/index.php?section=example&page=about'); // -> about Methods string getParam( string param, string url ) Returns the value of the parameter param in the provided url. param The parameter name to fetch url The URL used to locate the parameter object getURIObject( string url ) Returns an object of data about the provided URL. Consult the parseUri documentation for information on what this object includes. url The URL to parse

Description The time utility provides methods for working with timestamps. Methods string readable( number timestamp ) Returns the time as an approximate relative string, e.g. 8 hours ago, 2 days ago, Just now. timestamp UNIX timestamp to use to generate the time string boolean isDST() Determines whether the user is currently in daylight savings (DST). boolean isValidDateObj( mixed date ) Determines whether the provided date is a valid javascript Date object. date The object to check number timestamp() Returns the current UNIX timestamp string localeDateString( Date date, object options ) Returns a locale-aware string representing the provided date object. The options parameter can be used to adjust the formatting on browsers that support it. See MDN. date A Date object used as the source options Options object passed into javascript's toLocaleDateString function. See MDN for supported values. boolean supportsHTMLDate() Determines whether the HTML5 type='date' input is supported in the current browser.

Description Dealing with element positioning - getting current positions, working out new positions, and so on - is a common task in a web application such as IPS4. This utility aims to make that easier by providing some methods to do the calculations for you. Methods object getElemPosition( mixed elem ) Returns various positioning information for the provided element. elem DOM element or jQuery object containing the element to work with Returned object: absPos left Absolute left position right Absolute right position (i.e. left + width) top Absolute top position bottom Absolute bottom position (i.e. top + height) viewportOffset left Viewport left offset (i.e. left offset - left scroll postion) top Viewport top offset (i.e. top offset - top scroll position) offsetParent Reference to the element's offsetParent. That is, the closest element that has a non-static position. fixed true if the element has any ancestors which have fixed positioning or have one of the table display values. object positionElem( object options ) Returns positioning values, allowing the calling method to appropriate position the element with a best-fit on the screen. This method does not apply the positioning values to the element itself. options trigger The trigger element for this popup; that is, the element that the popup should be 'attached' to target The element to be positioned targetContainer The element that contains the element to be positioned. Assumed to be body if not provided. center (boolean) Specifies whether the method should attempt to position the target centered relative to the trigger. above (boolean) Specifies whether the method should attempt to position the target above the trigger. By default, a best fit is attempted. Returned object: top Ideal top position, in pixels left Ideal left position, in pixels fixed Whether the element should have fixed positioning applied (because an ancestor does) location horizontal Best horizontal location for the element; either center, left or right vertical Best vertical location for the element; either bottom or top boolean hasFixedParents( mixed elem ) Returns true if any of the element's descendants have fixed positioning or have one of the table display classes (e.g. table-row). elem The element whose ancestors are being checked for fixed positioning. Either a DOM node or a jQuery object. object getElemDims( mixed elem ) Returns current dimension information for the element. elem The element whose dimensions are being returned. Either a DOM node or a jQuery object. Returned object: width Current width in pixels height Current height in pixels outerWidth Current outer width of the element; that is, the width plus border and padding outerHeight Current outer height of the element; that is, the width plus border and padding number nautralWidth( mixed elem ) Returns the natural width of the provided element (which should be an img element). The natural width is the original width of the image not accounting for any resizing done by CSS or HTML attributes. elem The element whose natural width is being returned. Either a DOM node or a jQuery object. number nautralHeight( mixed elem ) Returns the natural height of the provided element (which should be an img element). The natural height is the original height of the image not accounting for any resizing done by CSS or HTML attributes. elem The element whose natural height is being returned. Either a DOM node or a jQuery object. number lineHeight( mixed elem ) Attempts to return the computed line-height, in pixels, of the provided element. There are edge cases where this result won't be reliable, such as CSS styling <span> tags inside the element differently to the element itself. Test your use case. elem The element whose line-height is being returned. Either a DOM node or a jQuery object.

Description Modern browsers provide a mechanism for storing persistent data directly on a user's computer, called localStorage. This utility exposes some methods for working with localStorage in IPS4. Example ips.utils.db.set( 'myCategory', 'myKey', 'Hello world' ); ips.utils.db.get( 'myCategory', 'myKey' ); // -> Hello world ips.utils.db.isEnabled(); // -> true ips.utils.db.removeByType( 'myCategory' ); // -> 1 Methods void set( string type, string key, mixed value ) Sets a new value, or overwrites an existing balue with the same type and key. type Name of category in which to store this value. Categories are used for later retrieving sets of related values. key The unique key for this value value The value to be stored. void get( string type [, string key ] ) Retrieves a previously set value. If no key is provided, all values in the type are returned. type The category containing the key to fetch. key The key of the value to fetch. void remove( string type [, string key] ) Removes a previously set value. If no key is provided, all values in the type are removed. type The category containing the key to remove. key The key of the value to remove. object getByType( string type ) Returns an object of all values in the category with the provided name. type The category name number removeByType( string type ) Removes all values from the category with the provided name, returning a count of the number of removed items. type The category name boolean isEnabled() Returns a boolean indicating whether the localStorage utility is enabled in this user's browser.

Description This utility provides methods for working with cookies in IPS4. It deals with cookie prefixes and other setting behind the scenes so that you can interact with cookies without having to handle those aspects manually. Example ips.utils.cookie.set( 'myKey', 'Hello world', true ); // Sets a sticky cookie ips.utils.cookie.get( 'myKey' ); // -> Hello world ips.utils.cookie.unset( 'myKey' ); ips.utils.cookie.get( 'myKey' ); // -> undefined Methods void set( string key, string value, mixed sticky ) Sets a new cookie, or overwrites an existing cookie with the same key. key The key to store this value under, used for later retrieval. value The value of this cookie. sticky The cookie's expiration. If true, the cookie is set to be (effectively) permanent. If -1, the cookie will expire when the page reloads. Alternatively, an explict expiration date can be set by using the correct format, e.g. Mon, 16-Dec-2013 18:00:00 GMT string get( string key ) Retrieves a previously set cookie. If the cookie doesn't exist, undefined is returned. key The key to fetch. void unset( string key ) Removes a previously set cookie. key The cookie key to remove

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 javascript is enabled. This is the basic markup for a tab bar: <!-- The tab bar --> <div class='ipsTabs ipsClearfix' id='elTabBar' data-ipsTabBar data-ipsTabBar-contentArea='#elTabContent'> <a href='#elTabBar' data-action='expandTabs'><i class='icon-caret-down'></i></a> <ul role='tablist'> <li role='presentation'> <a href='...' role='tab' id='elTabOne' class='ipsTabs_item' aria-selected="true"> Tab One </a> </li> <li role='presentation'> <a href='...' id='elTabTwo' role='tab' class='ipsTabs_item'> Tab Two </a> </li> </ul> </div> <!-- The tab panel wrapper --> <section id='elTabContent'></section> The key details here are: The widget key attributes belong on the tab bar wrapper element. The first child of the tab bar should be an element with the attribute data-action='expandTabs'. This is used when the tab bar is displayed on a small device. For accessibility, it should be an anchor link to the tab bar element. Each tab links to a static page - this is the same URL that is called to fetch content remotely, too. If your tab panels (see next section) are static content that already exists on the page, you can use an anchor that points to that element instead. A panel wrapper is present, which will receive the panels when the tab widget creates them. This example is also marked up with ARIA properties for accessibility, such as role='tab' and aria-selected='true'. If content exists inside the panel wrapper element at the time the tab widget is initialized, the widget will take this content, create a panel from it, and treat it as the content for the default selected tab. This mechanism means developers can include the default content into the page very easily, without it needing to be fetched with another AJAX request. Panels can be created manually, rather than having them load via AJAX. To do so, a panel element should exist inside the panel wrapper element and have the correct ID. The ID takes this format: <panelPrefix>_<barID>_<tabID>_panel Where the values are: panelPrefix is the prefix set in the options (see below); ipsTabs by default barID is the ID set on the tab bar element tabID is the ID set on the individual tab element that this panel relates to Options contentArea (Selector; required) A CSS selector which will locate the panel container element into which panels will be created. For example, #elTabContent. updateURL (Boolean; optional; default true) Determines whether the browser address bar will be updated with the URL to individual tabs when the user selects them. This allows individual tabs to be navigated to and appear in the browser's history. itemSelector (Selector; optional; default '.ipsTab_item') A CSS selector which will locate the tab elements within the tab bar. activeClass (String; optional; default 'ipsTabs_activeItem') A classname which will be applied to the currently-active tab element. loadingClass (String; optional; default 'ipsLoading ipsTabs_loadingContent') A classname which will be applied to the panel container element when new tab content is being loaded. panelClass (String; optional; default 'ipsTabs_panel') A classname which will be applied to individual panels as they are created. panelPrefix (String; optional; default 'ipsTabs') A prefix which will be used when generating a panel ID. This helps to prevent potential naming conflicts with other elements. The default value should be fine in most situations. defaultTab (Selector; optional) If provided, this option is used to set the default tab when the tab bar first loads. If not provided, the first tab with the class specified by activeClass is looked for; finally, if all else fails, the first tab in the bar is selected. Additionally, it is worth noting that if you would like for the tab bar to stretch across the entire area of the container it is contained within, you can add the CSS class .ipsTabs_stretch to the tab bar element. Events emitted by ips.ui.tabbar tabChanged Triggered when the selected tab changes. This event is triggered as soon as the user clicks a tab. Event data: barID ID of the tab bar wrapper tabID ID of the selected tab tab Reference to the newly-selected tab element panel Reference to the panel element for this tab tabShown Triggered when the selected tab is shown. This event is triggered after the fade-in animation has finished, unlike the tabChanged event above. Event data: barID ID of the tab bar wrapper tabID ID of the selected tab tab Reference to the newly-selected tab element panel Reference to the panel element for this tab

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 multiple items at once? selected (Mixed; optional; default false) Defines the pre-selected items as a JSON object, or false if no items are selected yet. url (String; required) The URL used to fetch child items via AJAX. Events emitted by ips.ui.selectTree nodeItemSelected Triggered when the user selects an item in the menu. Emitted on all items in the menu. Event data: title The text of the element within the selected item, that has the attribute data-role="nodeTitle" id The ID of this item as specified by the data-id attribute on the item. Note: this is not the HTML id attribute. nodeSelectedChanged Triggered when the selection in the menu changes (i.e. items are either selected or unselected). Emitted on all items in the menu. Event data: selectedItems Array containing the data-id attribute values of all currently-selected items. nodeSelectionClosed Triggered when the drop-down menu is closed. Emitted on the root data-ipsSelectTree element.

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> Options type (String; optional; default 'remove') Specifies how the truncating is done. remove removes the excess text entirely. hide leaves the excess text on the page, hiding it behind a 'read more' button. size (Mixed; optional; default 100) Specifies the height the element should be; the excess text is truncated. Three types of value are accepted: Selector, e.g. #someElementID When a selector is provided, the height of the widget element will be set to the outerHeight of the first element that matches the selector. Lines value, e.g. 3 lines Text can be truncated to a certain number of lines of text, taking into account current formatting applied to the text (Note: lines is always plural). Number e.g. 100 A simple number value can be provided, which will truncate the text to that number of pixels. expandText (String; optional; default 'Read more') If type is hide, this option can be used to change the text shown on the button which will show the hidden content. Events emitted by ips.ui.truncate Events are emitted on the element on which the data-ipsTruncate attribute is assigned. contentTruncated Emitted when the content in the element has been truncated. Event data: type The type of truncating used, either remove or hide. contentExpanded Emitted when the user expands the text in a widget where type is hide.

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 @todo Usage Generally, you only need to add the data-ipsTooltip attribute to an element to display a tooltip. By default it will use the title or aria-label attributes for the tooltip contents: <a href='#' title='This is a tooltip' data-ipsTooltip>Hover on this link</a> Options label (String; optional) If for some reason you do not want to use the default title attribute for the tooltip contents, the contents can be specified using this option. safe (Boolean; optional; default false) Specifies whether the tooltip contents are safe, i.e. whether they do not contain any user input. Important: If the tooltip contents contains any text entered by a user at some stage, this option should be false. Passing unsafe text to the tooltip opens the possibility of an XSS attack. Only set to true if you have a genuine need to and you determine the contents explicitly. Events emitted by ips.ui.tooltip Events are emitted by the element on which the data-ipsTooltip attribute is assigned. tooltipShown Emitted when the tooltip is displayed.

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 represents the element that will visually contain the sticky element. The widget by default simply uses the sticky element's parent. The widget attempts to position and size the element when it is 'sticky' correctly, but depending on the situation in which it is used, manual tweaking via CSS may be required. Options stickyClass (String; optional; default 'ipsSticky') Classname that will be applied to the element when it is in sticky mode. Useful for applying special styling which indicates it is 'floating'. relativeTo (Selector; optional) The element which visually appears as the parent of the sticky element. The sticky element's parent is assumed if not specified. This option keeps the sticky element within the container specified by relativeTo. As an example, assume you have a sticky element within a sidebar on your page, and the relativeTo option is set to the sidebar. As the user scrolls down the page, the sticky element will remain visible, 'stuck' to the top of the browser window. However, if the amount of sidebar shown on the page isn't enough to contain all of the sticky element, the widget will unsticky it. This behavior allows sticky elements to intelligently behave as children of other elements that aren't themselves sticky. spacing (Number; optional; default 0) Number in pixels. When the sticky element is the specified distance from the edge of the browser window, it will be switched into it's sticky positioning. stickTo (String; optional; default 'top') Either top or bottom; determines which edge of the screen the sticky element will stick to. width (Mixed; optional) Allows you to specify the width of the sticky element when it is in sticky mode. This option can be a Number, in which case it will be set to that number of pixels. It can also be a selector, in which case it will be set to the same width of the first element located by the selector. disableIn (String; optional) Sticky behavior is often not desired on mobile devices. This option allows you to disable sticky behavior when responsiveness is enabled and the device is currently using one of the viewport keys specified in this option, e.g. phone or tablet. Events emitted by ips.ui.sticky Events are emitted on the element on which the data-ipsWidget attribute is specified. stickyInit Emitted after the widget has been initialized. Event data: id ID of the root sticky element status The current status of the sticky element, either normal or fixed

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 sortable (Boolean; optional; default true) Specifies whether the values in the stack control can be reordered with drag and drop. maxItems (Number; optional) If provided, specifies the maximum number of values this stack control will accept. itemTemplate (Template key; optional; default 'core.forms.stack') If provided, specifies the template which will be used to dynamically build new rows in the stack control. Events emitted by ips.ui.stack Events are emitted on the root stack element. stackInitialized Triggered when the stack has been built and is initialized. Event data: count Count of the current number of values in the stack control stackRowAdded Triggered when the user adds a new row to the stack control (either by pressing Enter in an existing row, or pressing the 'Add Another' button). Event data: count Count of the current number of values in the stack control

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 The Spoiler widget does not emit any events.

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 ipsSideMenu_mainTitle; a link inside of that title should have the attribute data-action='openSideMenu': <div class='ipsSideMenu' data-ipsSideMenu> <h3 class="ipsSideMenu_mainTitle ipsAreaBackground_light ipsType_medium"> <a href="#modcp_menu" class="ipsPad_double" data-action="openSideMenu"> <i class="fa fa-bars"></i> &nbsp;Menu Title&nbsp;<i class="fa fa-caret-down"></i> </a> </h3> <!-- Menu content belongs here --> </div> Using sidemenus as selectable menus Sidemenus can be used as a way of allowing users to select one or more options on the fly, either as a radio (i.e only one selected at a time) or as a checkbox (i.e. multiple selected). This is achieved by setting the data-ipsSideMenu-type attribute on the menu and specifying data-ipsMenuValue attributes on the list items: <ul class="ipsSideMenu_list ipsSideMenu_withRadios" data-ipsSideMenu data-ipsSideMenu-type="radio"> <li> <a href='#' class='ipsSideMenu_item ipsSideMenu_itemActive' data-ipsMenuValue='one'> <input type="radio" name="type" value="one" checked> <label>One</label> </a> </li> <li> <a href='#' class='ipsSideMenu_item' data-ipsMenuValue='two'> <input type="radio" name="type" value="two"> <label>Two</label> </a> </li> </ul> Note: Radio and checkbox inputs can be inserted inside the menu items as shown above. They will be hidden with CSS, and automatically selected as the user selects menu items. This enables the side menu to submit values as part of a form. Options responsive (Boolean; optional; default true) Specifies whether the side menu will add responsive behavior. It does this by hiding the menu, and showing a link to manually open it on-demand. type (String; optional; default 'radio') Determines the type of selectable behavior the menu uses. By default, only one menu item can be selected; others will be deselected when a new one is clicked. This is radio behavior. In contrast, check will allow multiple items to be selected at once. group (String; optional) Determines whether the above setting applies to the whole menu (when this option is false), or whether each group within the menu is treated as an individual menu for the purposes of the radio selection. Events emitted by ips.ui.sidemenu Events are emitted by the root menu element (i.e. the one on which the data-ipsSideMenu attribute is applied). itemClicked.sideMenu Triggered when the user selects an item in the menu. Event data: id The ID of the menu triggering the event menuElem Reference to the menu element selectedElem Reference to the selected element that caused this event selectedItemID The data-ipsMenuValue value on the item that has been selected selectedItems An array of all of the currently-selected values in the menu

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</div> <div class='ipsGrid_span4'>Item</div> </div> Your grid items can use any suitable span class by default; the Grid widget will dynamically update the used class depending on the space available. Note that when using this widget with grids, grid items become greedy. That is, they take up as much space as they are allowed. Therefore, you will need to specify a maxItemSize value (see below) in order to properly size the items. Options minItemSize (Number; required) The minimum number of pixels wide each grid item can be; when grid items are smaller than this value, the grid spans will be adjusted to the next suitable size to ensure they are larger than this value. maxItemSize (Number; required) The maximum number of pixels wide each grid item can be; when grid items are larger than this value, the grid spans will be adjusted to the next suitable size to ensure they are smaller than this value. equalHeights (String; optional) If set to row, the Grid widget will ensure each item in each row is as tall as the tallest item in that row. If set to all, the Grid widget will ensure all items in the grid are as tall as the tallest item. Events to which ips.ui.grid responds newItem When fired on the wrapper element, this event will cause the grid to redraw, recalculating spans and heights as necessary. Event data: element (required) A DOM or jQuery reference to the new item in the grid

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" id="ratingValue_2" value="2"> <label for="ratingValue_2">2</label> <input type="radio" name="ratingValue" id="ratingValue_3" value="3"> <label for="ratingValue_3">3</label> <input type="radio" name="ratingValue" id="ratingValue_4" value="4"> <label for="ratingValue_4">4</label> <input type="radio" name="ratingValue" id="ratingValue_5" value="5"> <label for="ratingValue_5">5</label> </span> The field name attributes, IDs and labels are not fixed; they can be anything. The radio values, however, should be numeric and in ascending order. Any number of stars is supported - simply include the correct number of radio controls with the relevant values. Options url (String; optional) If a URL is provided, it will be called via AJAX when the user clicks a star to choose a rating. The rating parameter will contain the selected value. changeRate (Boolean; optional; default true) Specifies whether the user can choose a new rating, if they have already rated the item. canRate (Boolean; optional; default true) Determines whether the user can select a rating in the widget. size (Boolean; optional) If specified, applies an additional ipsRating_ size class to the rating stars to control their size. Supported values: small, large, veryLarge. Events emitted by ips.ui.rating Events are emitted on the rating wrapper. ratingSaved Triggered when the user selects a rating. If the url option is used, this will be triggered after the URL is successfully pinged. It will not be triggered if the URL fails. Event data: value Numeric value of the chosen rating ratingFailed Triggered when the url option is used and pinging the provided URL fails. Event data: value Numeric value of the chosen rating

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 automatically supporting pagination in those classes. Options ajaxEnabled (Boolean; optional; default true) Determines whether events are triggered by the pagination when the user clicks a page number. This option can be changed on the fly by changing the value of the data-ipsPagination-ajaxEnabled attribute. pages (Number; required) Specifies the highest possible page number for this set of results. Used to display an error to the user if they try and jump to a page number that does not exist. perPage (Number; optional; default 25) Specifies the number of results that are shown on each page. pageParam (String; optional; default 'page') Specifies the parameter to be used to represent the page number to load. Passed in emitted events for use by controllers. Events paginationClicked Triggered when the user clicks a page number or uses the page jump menu. Event data: href URL of the page that was clicked hrefTitle title attribute of the page link that was clicked paginationElem Reference to the pagination wrapper element pageElem Reference to the page link element that was clicked perPage The perPage value specified in the widget options pageParam The key of the parameter used to represent the page number to load, as specified in the pageParam option. pageNo The page number that was clicked, as specified in the data-page attribute on the page link originalEvent The original event object from the click event. Can be used to preventDefault on the event to stop the browser from following the link. lastPage Boolean indicating whether the page being navigated to is the last available page. paginationJump Triggered when the user jumps to a new page using the pagination jump menu Event data: href The value of the data-baseurl attribute on the closest parent with the attribute (e.g. a table controller), or # if none exists. paginationElem Reference to the pagination wrapper element pageElem Reference to the page link element that was clicked perPage The perPage value specified in the widget options pageNo The page number that was clicked, as specified in the data-page attribute on the page link originalEvent The original event object from the click event. Can be used to preventDefault on the event to stop the browser from following the link. lastPage Boolean indicating whether the page being navigated to is the last available page.

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 on the page in order to operate. The widget attribute itself should appear on the form element, or some wrapper around it. Your table content should appear inside of the form. <form method='get' action='...' data-ipsPageAction> <!-- content rows --> </form> Adding actions To add actions to the widget, within the form tag you should have a div with the attribute data-role='pageActionOptions'. Within this div should be a select box control containing your actions, and a submit button (for accessibility when javascript is disabled) Actions are specified by the options you add to the select box. Actions can either be single items, or grouped items inside an optgroup. A single action is simply an option element that will display as a button on the PageAction toolbar. You should specify the icon that the button will use by adding a data-icon attribute to the option element, and this should be one of the FontAwesome icons without the preceding fa-. Multiple actions are those which have more than one related state, e.g. feature and unfeature. These display as a single button in the widget, with a menu to select the state. They are created by adding option elements to an optgroup. The optgroup should contain the data-icon attribute, and a data-action attribute which will be sent as the parameter name when the form is submitted. Therefore, our actions HTML might look like this: <div data-role='pageActionOptions'> <select name='...' data-role='moderationAction'> <option value='approve' data-icon='check-circle'>Approve</option> <option value='move' data-icon='arrow-right'>Move</option> <optgroup label='feature' data-icon='star' data-action='feature'> <option value='feature'>Feature</option> <option value='unfeature'>Unfeature</option> </optgroup> </select> </div> Triggering the pageActions toolbar With the actions set up, you next need to add the triggers to the checkboxes in your form. This is done by adding a special data-actions attribute to the checkbox which contains a space-separated list of actions available for that checkbox. For example: <input type='checkbox' data-actions='approve feature'> When this checkbox is checked, the PageAction toolbar will display with the appropriate actions available. When multiple checkboxes are selected, all actions that match those checkboxes will be displayed. Options The ips.ui.pageAction widget does not support any options. Events The PageAction widget does not emit any events. When toolbar buttons are selected, the widget changes the value of the select control behind the scenes, so observe that control for value changes.

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 accessible even without javascript enabled). The attributes to initialize the menu should be added to the trigger element - that is, the element a user will click to show the menu. Typically this would be a link or button. The menu element should have the same ID as the trigger element, but suffixed with _menu; e.g. if the trigger has the ID 'trigger', the ID on the menu element should be 'trigger_menu'. With these conditions met, initializing the menu simply consists of adding the widget attribute to the trigger. <!-- The trigger --> <a href='#elMyMenu_menu' id='elMyMenu' data-ipsMenu>Open Menu</a> <!-- The menu --> <ul id='elMyMenu_menu' class='ipsMenu'> ... </ul> Pinging URLs from menu items The menu widget provides a mechanism for pinging the menu item URL via AJAX instead of following the link directly. To use this behavior, provide the data-action data attribute on the menu list item: <li class='ipsMenu_item' data-action='ipsMenu_ping'><a href='...'>Menu item</a></li> Providing menu values By including the attribute data-ipsMenuValue on your menu item, you can provide a value which will be passed by events, and can be used by event handlers to identify the menu item: <li class='ipsMenu_item' data-ipsMenuValue='itemID'><a href='...'>Menu item</a></li> Options className (String; optional; default 'ipsMenu') Provides the base menu classname that the widget will use. By default this is the standard ipsMenu class, but by passing a different classname, alternative menu styles can be built. closeOnClick (Boolean; optional; default true) Determines whether the menu element will close when an item is clicked. closeOnBlur (Boolean; optional; default true) Determines whether the menu element will close when somewhere other than the menu is clicked or focused (e.g. the document). appendTo (Selector; optional) By default, the menu element is moved and appended to the global container element (body, usually). By using this option, you can control which element the menu will be inserted into - useful when a menu is being created inside a popup for example. activeClass (String; optional) Specifies a classname that will be applied to the trigger element when the menu is opened. selectable (Mixed; optional; default false) Specifies whether the menu will have 'selectable' functionality, allowing items to be checked and unchecked. If the value passed is radio, only one item will be selectable at once. If value passed is checkbox, multiple items can be selected. Note that the menu must have the correct CSS classes already for selectable functionality to work. withStem (Boolean; optional; default true) Determines whether the menu will have a stem to indicate its relationship to the trigger. stemOffset (Number; optional; default 15) A value that indicates the offset of the stem, i.e. the distance from the edge to the center point of the stem. Should rarely need to be set unless the CSS classes are changed significantly. stopLinks (Boolean; optional; default false) Stops menu item links from being followed by the browser by calling preventDefault on the event. above (Boolean; optional; default false) By default, menus will prefer to open below the trigger. Setting this option to true will cause this menu to prefer being above the trigger instead. Events emitted by ips.ui.menu Events are emitted on the trigger element. menuOpened Triggered when the user opens a menu by clicking on the trigger Event data: elemID The ID of the trigger element this menu belongs to originalEvent The original event object from the click (useful for calling originalEvent.preventDefault() to prevent the default browser action) menu Reference to the menu element menuClosed Triggered when the menu closes Event data: elemID The ID of the trigger element this menu belongs to menuPingSuccessful Triggered when the menu closes No event data. menuItemSelected Triggered when the user selects an item within the menu Event data: triggerElem Reference to the trigger element triggerID ID of the trigger element menuElem Reference to the menu element originalEvent The raw javascript event object from the click selectedItemID String containing the value of the selected menu item, if it provided a data-ipsMenuValue attribute. selectedItems Object containing references to checked items, when menu is selectable Events to which ips.ui.menu responds closeMenu Can be fired on the menu or trigger element elements to close the menu.

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-ipsLightbox> However, it's likely additional functionality would be desired. A common practice is to link to a large image but display a small thumb image on the page. In this situation, the lightbox is initialized on the link: <a href='http://url/to/image' data-ipsLightbox><img src='http://url/to/thumb'></a> In both of the above example, a single image will be displayed in the lightbox. It's also possible to group images together - such as in a photo album, or a group of images for a single content item. In this case, you should initialize a lightbox on all of the items, and include the group option which should be consistent between them: <a href='http://url/to/image1' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb1'></a> <a href='http://url/to/image2' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb2'></a> <a href='http://url/to/image3' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb3'></a> Options group (String; optional) If provided, the widget will display other images from the same group in the lightbox. fullURL (String; optional) By default, the full size image will be loaded from the href attribute on the a tag. If this option is provided, the full size image will instead be loaded from this URL. className (String; optional; default ipsLightbox) Allows you to provide a classname prefix which will be used when the lightbox UI is built, enabling a custom UI to be shown. preload (Boolean; optional; default true) Determines whether images in the lightbox should be preloaded when the lightbox is opened, designed to reduce wait time for the user as they scroll through images. Events emitted by ips.ui.lightbox lightboxImageShown Triggered when the lightbox shows a new image. Event data: image elem Reference to this image's widget element (may different from <em>imageElem</em> if a link launches the lightbox) imageElem Reference to the actual image element largeImage URL to the fullsize image originalImage URL to the image that already existed on the page (e.g. a thumbnail) meta The meta information for the image, if any triggerElem Reference to the widget element that originally opened the lightbox, which may or may not be the image being viewed.

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 more appropriate to display a button at the bottom of your content inviting a user to load more content manually. In order to progressively enhance the page, and ensure users with javascript disabled can still access content, infinite scrolling in IPS4 works with the standard pagination markup. Usage The infinite scroll widget works by having the content inside of a scroll scope element. The element has a fixed height, and hides its overflow so that it scrolls. The content is placed inside a container element and is an arbitrary length, and as the user scrolls and the end of the container approaches the bottom of the scroll scope, the widget will load more content to display. A standard pagination control should exist inside the scroll scope element; it can be hidden from javascript-enabled browsers by placing it inside a noscript tag. Options scrollScope (Selector; optional; default 'body') A selector that idenfities the element which will be the scroll scope; that is, the element that has a fixed height and which the user will scroll to show more content. container (Selector; required) A selector identifying the container element inside which your content should exist. distance (Mixed; optional; default 50) A value that determines how close to the bottom of the scrollScope the container must be to trigger the loading of new content. The value can either be a number (e.g. 50) or a percentage (e.g. 10%) which represents a percentage height of the scrollScope element. url (String; required) The URL that is called to retrieve more content from the server. pageParam (String; optional; default 'page') The parameter used to pass the page value when retrieving more content from the server. loadingTpl (Template key; optional; default 'core.infScroll.loading') The template used to render the 'loading' text when the widget is currently loading new content. pageBreakTpl (Template key; optional; default 'core.infScroll.pageBreak') The template used to render the breaks between each 'page' of content as it is inserted into the container to aid the user experience. disableIn (String; optional; default 'phone') Specifies which responsive views, if any, the infinite scroll behavior is disable in. Value should be one or more registered breakpoint keys (phone, tablet or desktop), comma delimited. Events emitted by ips.ui.infScroll infScrollPageLoaded Triggered when a new page of content has been loaded. Event data: page The number of the most current page (i.e. the one just loaded).