Parameters:
Name | Type | Description |
---|---|---|
options |
Object | A map of option-value pairs to set on the widget. |
- Since:
- 5.0
Examples
Create a simple iconList for selecting multiple items.
HTML:
<h3 id="iconsLabel">My Icons</h3>
<ul id="icons1" aria-labelledby="iconsLabel">
<li data-value="b"><span class="fa fa-bus"></span><span class="label">Bus</span></li>
<li class="is-selected" data-value="c"><span class="fa fa-car"></span><span class="label">Car</span></li>
<li data-value="t"><span class="fa fa-taxi"></span><span class="label">Taxi</span></li>
...
</ul>
JavaScript:
$("#icons1").iconList({
multiple: true
});
This example creates an iconList for navigation. In this example #navList is the element that becomes the iconList widget.
HTML:
<h2 id="mainNav">Main Site Navigation</h2>
<div role="navigation">
<div id="navList" aria-labelledby="mainNav">
<a href="...">...</a>
...
</div>
</div>
JavaScript:
$("#navList").iconList({
navigation: true
});
If iconList#itemSelector option is true and the initial iconList markup does not include the markup needed to show the selector then this option should be set to true so that the markup is automatically added.
This is ignored if iconList#itemSelector is false.
The markup to show the checkbox selector is:
<span class="u-selector"></span>
The markup to show the radio button selector (used when multiple is false) is:
<span class="u-selector u-selector--single"></span>
Type:
- boolean
- Default Value:
- true
Examples
Initialize the iconList with the addItemSelector option specified.
$( ".selector" ).iconList( {
addItemSelector: false
} );
Get or set option addItemSelector after initialization.
// get
var value = $( ".selector" ).iconList( "option", "addItemSelector" );
// set
$( ".selector" ).iconList( "option", "addItemSelector", false );
If true the selection can be copied to the clipboard using the browsers copy event.
Type:
- boolean
- Default Value:
- true
Examples
Initialize the iconList with the allowCopy option specified.
$( ".selector" ).iconList( {
allowCopy: false
} );
Get or set option allowCopy after initialization.
// get
var value = $( ".selector" ).iconList( "option", "allowCopy" );
// set
$( ".selector" ).iconList( "option", "allowCopy", false );
A menu widget options object use to create the context menu.
Only specify one of contextMenu
or contextMenuId
and contextMenuAction
.
If none of contextMenu
, contextMenuId
or contextMenuAction
are specified there is no context menu.
This option cannot be set or changed after the widget is initialized.
Type:
- Object
- Default Value:
- null
Example
Initialize the iconList with the contextMenu option specified.
$( ".selector" ).iconList( {
contextMenu: {
items:[
{ type:"action", label: "Action 1", action: function() { alert("Action 1"); } },
{ type:"action", label: "Action 2", action: function() { alert("Action 2"); } }
]
}
} );
A callback function that is called when it is time to display a context menu.
function( event )
The function is responsible for showing the
context menu. It is given the event that caused this callback to be called.
In most cases it is simpler and more consistent to use the
contextMenu
option.
Only specify one of contextMenu
or contextMenuId
and
contextMenuAction
.
If none of contextMenu
, contextMenuId
or contextMenuAction
are specified there is no context menu.
Type:
- function
- Default Value:
- null
Example
Initialize the iconList with the contextMenuAction option specified.
$( ".selector" ).iconList( {
contextMenuAction: function( event ) {
// do something to display a context menu
}
} );
If option contextMenu
is given then this is the element id
to give the context menu created.
This allows other code to interact with the created context menu widget.
If option contextMenu
is not given then this is the
element id of an existing menu widget.
This option cannot be set or changed after the widget is initialized.
Type:
- string
- Default Value:
- null
Example
Initialize the iconList with the contextMenuId option specified.
$( ".selector" ).iconList( {
contextMenuId: "myContextMenu"
} );
If true a selector control is added before the item icon and label. The selector is a checkbox if multiple is true and a radio button if multiple is false. The iconList markup must include the necessary markup for the checkbox selector if iconList#addItemSelector is false. See iconList#addItemSelector for the needed markup.
Type:
- boolean
- Default Value:
- false
Examples
Initialize the iconList with the itemSelector option specified.
$( ".selector" ).iconList( {
itemSelector: true
} );
Get or set option itemSelector after initialization.
// get
var value = $( ".selector" ).iconList( "option", "itemSelector" );
// set
$( ".selector" ).iconList( "option", "itemSelector", true );
This option only applies to the type to select feature. It is a jQuery selector for finding the label text of an item or true to use the text of the item or false to disable type to search.
Type:
- boolean | string
- Default Value:
- true
Examples
Initialize the iconList with the label option specified.
$( ".selector" ).iconList( {
label: "myIconLabel"
} );
Get or set option label after initialization.
// get
var value = $( ".selector" ).iconList( "option", "label" );
// set
$( ".selector" ).iconList( "option", "label", false );
If true multiple items can be selected. If false at most one item can be selected.
Must be false when navigation option is true.
Type:
- boolean
- Default Value:
- false
Examples
Initialize the iconList with the multiple option specified.
$( ".selector" ).iconList( {
multiple: true
} );
Get or set option multiple after initialization.
// get
var value = $( ".selector" ).iconList( "option", "multiple" );
// set
$( ".selector" ).iconList( "option", "multiple", true );
When true changes the mode of widget to navigation otherwise the mode is selection. This option can't be changed after create.
Type:
- boolean
- Default Value:
- false
Examples
Initialize the iconList with the navigation option specified.
$( ".selector" ).iconList( {
navigation: true
} );
Get or set option navigation after initialization.
// get
var value = $( ".selector" ).iconList( "option", "navigation" );
// set
$( ".selector" ).iconList( "option", "navigation", true );
A jQuery selector that identifies item content that uses navigation keys or contains elements that
use navigation keys. Navigation keys are used to change the focus or selection state, they
include the arrow keys, Home, End, Space and Enter as well as keys used in the type to select feature.
When the iconList contains tabbable content (iconList#tabbableContent is a valid selector)
that can also take keyboard input, such as an
<input>
element this option is used to allow the specified elements
to use the navigation keys usually used by the iconList.
This is ignored when iconList#navigation is true.
Type:
- string
- Default Value:
- null
Examples
Initialize the iconList with the noNavKeyContent option specified.
$( ".selector" ).iconList( {
noNavKeyContent: "input"
} );
Get or set option noNavKeyContent after initialization.
// get
var value = $( ".selector" ).iconList( "option", "noNavKeyContent" );
// set
$( ".selector" ).iconList( "option", "noNavKeyContent", "input" );
A jQuery selector that identifies item content that can be a tab stop when an item has focus. This is ignored when iconList#navigation is true.
Type:
- string
- Default Value:
- null
Examples
Initialize the iconList with the tabbableContent option specified.
$( ".selector" ).iconList( {
tabbableContent: "a,button"
} );
Get or set option tabbableContent after initialization.
// get
var value = $( ".selector" ).iconList( "option", "tabbableContent" );
// set
$( ".selector" ).iconList( "option", "tabbableContent", "a,button" );
Properties:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||
data |
object | Additional data for the event.
Properties
|
Examples
Initialize the iconList with the activate
callback specified:
$( ".selector" ).iconList({
activate: function( event, data ) {}
});
Bind an event listener to the iconlistactivate
event:
$( ".selector" ).on( "iconlistactivate", function( event, data ) {} );
Properties:
Name | Type | Description |
---|---|---|
event |
Event | jQuery event object. |
Examples
Initialize the iconList with the selectionChange
callback specified:
$( ".selector" ).iconList({
selectionChange: function( event ) {}
});
Bind an event listener to the iconlistselectionchange
event:
$( ".selector" ).on( "iconlistselectionchange", function( event ) {} );
Set focus to the iconList. The item that last had focus is focused or if no item had focus the first item is focused.
Example
Focus the iconList.
$( ".selector" ).iconList( "focus" );
Returns the number of columns in the iconList.
Returns:
- Type
- number
Example
Get the number of columns currently displayed by the iconList.
var columns = $( ".selector" ).iconList( "getColumns" );
Returns the number of rows in the iconList.
Returns:
- Type
- number
Example
Get the number of rows currently displayed by the iconList.
var rows = $( ".selector" ).iconList( "getRows" );
Returns the set of selected items. If there is no selection the empty set is returned.
Returns:
- Type
- jQuery
Example
Get the currently selected items.
var selection$ = $( ".selector" ).iconList( "getSelection" );
Returns the values, from the data-value attributes, of all the selected items. If there is no selection an empty array is returned.
Returns:
- Type
- Array.<string>
Example
Get the currently selected values and convert them to a ":" separated string.
var values = $( ".selector" ).iconList( "getSelectionValues" ),
result = values.join( ":" );
Call refresh if the contents of the list changes or if the size of the container changes.
Example
Call the refresh method.
$( ".selector" ).iconList( "refresh" );
This method must be called if the size of the container changes so that the rows and columns can be recalculated.
Example
Call the resize method.
$( ".selector" ).iconList( "resize" );
Sets the iconList selection.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pItems$ |
jQuery | A jQuery object with the items to select. An empty jQuery set will clear the selection. | |
pFocus |
boolean |
<optional> |
If true the first item in pItems$ will be focused. |
pNoNotify |
boolean |
<optional> |
If true the selection change event will be suppressed. |
Example
This example selects the items with values "a", "b", and "c".
$( ".selector" ).iconList( "setSelection", $( "a:b:c".split( ":" ).map( function(v) {
return "[data-value='" + v + "']";
} ).join( "," ) ) );