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 thetop
of your implementation if you override this method.destroy
: Call the parent method at thebottom
of your implementation if you override this method.didAddChildComponent
: Call the parent method at thetop
of your implementation if you override this method.didRemoveChildComponent
: Call the parent method at thetop
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;