Moobile.List

Moobile.List

622 772 ThomasEngels

Provides a list control that handles list items.

Initialization

Syntax:

var list = new Moobile.List([element], [options], [name]);

Parameters:

Name Type Description
element Optional Element The list’s element, element id or html string.
options Optional Object The list’s options, see below.
name Optional String The list’s name.

Options:

Name Type Description
className String The list’s extended CSS class name, defaults to null.
styleName String The list’s default style, defaults to null.
tagName String The list’s element tag name, defaults to ul.
selectable Boolean Whether this list’s items can be selected, defaults to true.
selectedItemIndex Number The list’s default selected item index, defaults to -1.

Generates:

<ul class="list"></div>

Note:

List item can be added to the list by adding elements with the list-item data-role attribute:

<ul data-role="list">
    <li data-role="item">Item 1</li>
    <li data-role="item">Item 2</li>
    <li data-role="item">Item 3</li>
    <li data-role="item">Item 4</li>
</ul>

Subclassing Notes:

This class overrides the following method:

  • willBuild: Call the parent method at the top of your implementation if you override this method.
  • destroy : Call the parent method at the bottom of your implementation if you override this method.
  • didAddChildComponent: Call the parent method at the top of your implementation if you override this method.
  • didRemoveChildComponent: Call the parent method at the top of your implementation if you override this method.

Defined roles:

Name Description Applies to Note
list Defines an element acting as a Moobile.List control All components Use the data-list attribute to specify a subclass instead

Examples:

Specifying an element that acts a list control using the data-role attribute:
<ul data-role="list"></ul>
Specifying an element that acts a list control subclass using the data-role attribute:
<ul data-role="list" data-list="MyList"></ul>

Events

select

Fired when a list item is selected.

Arguments

Name Type Description
item Moobile.Button The selected list item.

deselect

Fired when a list-item is deselected.

Arguments

Name Type Description
item Moobile.Button The deselected list item.

Methods

setSelectedItem(selectedItem)

Selects the specified item and deselect the currently selected item if any. You can also clear the selected item by specifying null instead of an item.

This methods fires the deselect and select events.

Parameters:

Name Type Description
selectedItem Moobile.ListItem The selected item or null to clear the selection.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list  = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.setSelectedItem(itemOne); // selects the first item

getSelectedItem()

Returns the selected item.

Returns:

  • Moobile.ListItem The selected item or null if no items are selected.

Example:

var list  = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.setSelectedItem(itemOne);
list.getSelectedItem(); // returns itemOne

setSelectedItemIndex(index)

Selects an item using a specified index, 0 being the first item in this list. Specifying an index that matches no items will clear the selection.

Parameters:

Name Type Description
index Number The selected item index.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list  = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.setSelectedItemIndex(0);

getSelectedItemIndex()

Returns the selected item index.

Returns:

  • Number The selected item index or -1 if no items are selected.

Example:

var list  = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.setSelectedItemIndex(0);
list.getSelectedItemInde(); // returns 0

clearSelectedItem()

Unselects the selected item.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list  = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.setSelectedItemIndex(0);
list.clearSelectedItem();

addItem(item, where)

Adds the specified item at the top or bottom of this list. If where is omitted, the item will be added at the bottom of this list. The item may be a string. In this case, this method will create a Moobile.ListItem instance and set the specified string as its label.

Parameters:

Name Type Description
item Mixed The item as a string or a Moobile.ListItem instance.
where Optional String The item’s location, either top or bottom, defaults to bottom.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
list.addItem(itemOne);

addItemAfter(item, after)

Adds the specified item after an item from this list. The item may be a string. In this case, this method will create a Moobile.ListItem instance and set the specified string as its label.

Parameters:

Name Type Description
button Mixed The item as a string or a Moobile.ListItem instance.
after Moobile.ListItem The item will be placed after this item.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItemAfter(itemTwo, itemOne); // itemTwo is after itemOne

addItemBefore(item, before)

Adds the specified item before an item from this list. The item may be a string. In this case, this method will create a Moobile.ListItem instance and set the specified string as its label.

Parameters:

Name Type Description
item Mixed The item as a string or a Moobile.ListItem instance.
before Moobile.ListItem The item will be placed before this item.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItemBefore(itemTwo, itemOne); // itemTwo is before itemOne

getItems()

Returns all the items in this list.

Returns:

  • Array An array of all the items in this list.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addButton(buttonOne);
list.addButton(buttonTwo);
list.getItems(); // returns [itemOne, itemTwo]

getItem(name)

Returns an item that matches the specified name.

Parameters:

Name Type Description
name String The item’s name to search for.

Returns:

  • Moobile.ListItem The item or null if no items were found with the name.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem(null, null, 'me');
list.addItem(itemOne);
list.getItem('me'); // returns itemOne

getItemAt(index)

Return an item at a specified index.

Parameters:

Name Type Description
index Number The item’s index.

Returns:

  • Moobile.ListItem The item or null if no items were found at the index.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.getItemAt(0); // returns itemOne

removeItem(item, destroy)

Removes an item.

Parameters:

Name Type Description
item Moobile.ListItem The item to remove.
destroy Optional Boolean Whether to destroy the item upon removal.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.removeItem(itemOne); // the list contains only itemTwo

removeAllItems()

Removes all items.

Name Type Description
destroy Optional Boolean Whether to destroy the item upon removal.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
var itemOne = new Moobile.ListItem();
var itemTwo = new Moobile.ListItem();
list.addItem(itemOne);
list.addItem(itemTwo);
list.removeAllItems(itemOne); // no items remains

setSelectable(selectable)

Sets whether items from this list are selectable.

Name Type Description
selectable Boolean Whether items from this list are selectable.

Returns:

  • Moobile.List This Moobile.List instance.

Example:

var list = new Moobile.List();
list.setSelectable(false);

isSelectable()

Indicates whether items from this list are selectable.

Returns:

  • Boolean Whether items from this list are selectable.

Example:

var list = new Moobile.List();
list.setSelectable(false);
list.isSelectable(); // returns false;