iconList

IconList is a ListBox where the items (options) in the list are arranged in a grid; across then down.
All the items in the list must be the same size; height and width set with CSS.
Arrow key movement is naturally extended to two dimensions.
The number of columns depends on the width of the iconList element and the items within it.
The iconList does not handle scrolling the item contents but it can be put inside a container that does scroll.
It can be used from tableModelView to support pagination including scroll paging over a model.

The primary purpose of an itemList is to allow the user to select one or more items. It also supports
type to select, copy to clipboard, context menus, and item activation. Items are activated with double click
(single click in navigation mode) or the Enter key.
When activated the activate callback is called. This can be used to perform an action such as opening a dialog
or navigating.

The expected markup (for best accessibility) is a <ul>
(or <ol>) containing <li> elements,
however it only depends on a single parent element where all the children are the items.
The initially selected item(s) can be indicated by giving the item(s) a class of
is-selected. The contents of the item is mostly of no concern to this widget but
typically include an icon and a label. The contents should not overflow (spill outside of) the item. The item
content cannot have interactive elements such as inputs or buttons.

Navigation Mode

As an alternative to selection an iconList has a navigation mode where the list items are essentially links.
A single click on the item will activate it. This is controlled with the iconList#navigation option.
If the item is or contains an anchor the default behavior for activation is to navigate
to the href value. (only one anchor per item is allowed.) When used for
navigation the widget should be wrapped in an element with role navigation.

Selection

It is also possible to include a checkbox for multiple selection using the iconList#itemSelector option.
The item markup can include <span class="u-selector"></span>
if checkbox selection is desired. Must also set option itemSelector to true.
If the markup doesn't contain this u-selector span then it can be added for you if option
iconList#addItemSelector is true.

On a touch enabled device where the user has interacted with touch a multi select iconList will
automatically enable checkbox selection.

Like options in a select element the option items can have a value using the data-value attribute.

Context Menus

The iconList has easy integration with the menu widget to provide context menu support.
The iconList#contextMenu option is used to provide a menu widget options object.
When the contextMenu option is used the menu#event:beforeOpen event/callback ui argument has these
additional properties:

menuElement: The menu jQuery object.

iconList: This iconList jQuery object.

selection: A jQuery object with the selected items at the time the menu was opened.

Also the menu#event:afterClose event/callback will automatically focus the iconList if the menu action
didn't take the focus and the ui argument has these additional properties:

menuElement: The menu jQuery object.

iconList: This iconList jQuery object.

If using the contextMenu option the iconList#contextMenuId
option can be used to give the menu element an ID.
This is useful if other code must refer to the menu element or widget.

If for any reason you don't want to use the menu widget, the iconList#contextMenuAction option
allows you to respond to mouse or keyboard interactions that typically result in a context menu.
Specifically Right Mouse click (via contextmenu event),
Shift-F10 key (via keydown event) and the
Windows context menu key (via contextmenu event).
The original event is passed to the iconList#contextMenuAction function.
The event object can be used to position the menu. If you implement your own menu it is best if you put focus
back on the iconList using the iconList#focus method when the menu closes (unless the menu action directs focus
elsewhere).

Accessibility

For accessibility the iconList should be labeled by using the aria-labelledby
attribute to point to an element that contains the label. The widget will append text for screen readers only that
indicates the number of rows and columns. For best accessibility when used for navigation the markup should be a
<div> with anchor (<a>) children
as shown in second example in the initializer section.

For accessibility make sure that any images or icons used in the items have a text alternative if appropriate.

Keyboard End User Information

Key

Action

Up Arrow

Move focus to the item in the current column of the previous row.

Down Arrow

Move focus to the item in the current column of the next row.

Right Arrow

Move focus to the next item in the current row wrapping to the next row at the end.

Left Arrow

Move focus to the previous item in the current row wrapping to the previous row at the start.

Home

Move focus to the first item.

End

Move focus to the last item.

Space

Selects the focused item.

Enter

Activates the selected items.

printable characters

Sets focus to the next item with a label that starts with the typed character(s).

Typically when an item receives focus it is also selected. For a multiple selection iconList the Shift and Ctrl
modifier keys can be used in combination with the home, end, and arrow keys to affect the selection.
The Shift key extends the selection to include the items between the anchor item (the first single item selected)
and the current focused item. The Ctrl key moves the focus without affecting the selection.
The Space key can then be used to select the focused item or Ctrl+Space to toggle the item selection.

Options

addItemSelector :boolean

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.

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>

contextMenuAction :function

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.

contextMenuId :string

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"
} );

itemSelector :boolean

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.