# Mojo.Widget.List

## Namespace Detail

### Overview

The List is the most common and possibly the most powerful Mojo widget. Objects are rendered into list items using provided HTML templates, and may be variable in height and/or include other widgets. Lists can be static, with the list items being provided to the widget directly as an array, or they can be dynamic, with the application providing a callback function that is invoked as additional items are needed for display. Lists can be manipulated in place, with the framework handling deletion, reordering, and addition functions for the application.

### Declaration

>     <div x-mojo-element="List" id="listId" class="listClass" name="listName"></div>

In addition, a list item template is required. This declared in a separate file, and referenced in the "listTemplate" attribute property.

>     <div class="row textfield" x-mojo-tap-highlight="momentary">
>       <div class="title">
>           #{data}
>       </div>
>     </div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Yes | "List" | Declares the widget as type "List".
id | Yes | Any string | Identifies the widget element for use when instantiating or rendering. Should be unique in the document.
class | No | Any string | Specifies a unique class to override the framework's styles.
name | No | Any string | A unique name for the list widget. Generally used in templates.

### Events

>     this.controller.listen(this.controller.get("listId"), Mojo.Event.listTap,
>       this.handleUpdate);

Event | Value | Description
--- | --- | ---
Mojo.Event.listChange | {model:this.controller.model, item:dataObj, index: index + this.renderOffset, originalEvent:event} | Button has been tapped.
Mojo.Event.listTap | event.item |
Mojo.Event.listAdd |  |
Mojo.Event.listDelete | event.item event.index |
Mojo.Event.listReorder | event.item event.toIndex event.fromIndex |

### Instantiation

>     this.controller.setupWidget("listId",
>       this.attributes = {
>           itemTemplate: "listscene/static-list-entry",
>           listTemplate: "listscene/static-list-container",
>           addItemLabel: "Add ...",
>           swipeToDelete: true,
>           reorderable: true,
>           emptyTemplate:"list/emptylist"
>       },
>       this.model = {
>           listTitle: "List Title",
>           items : [
>               {data: "Item 1"},
>               {data: "Item 2"},
>               {data: "Item 3"},
>               {data: "Item 4"},
>               {data: "Item 5"},
>               {data: "Item 6"},
>           ]
>       }
>     );

### Attribute Properties

Name | Type | Req'd | Default | Description
--- | --- | --- | --- | ---
addItemLabel | String | No | none | If defined, a special "add" item will be appended to the list and taps on this item will generate a "Mojo.Event.listAdd" event. The string is used to label the entry. If null, then it will default to "+Add".
autoconfirmDelete | Boolean | No | true | If false, delete swipes will post a "delete/undo" button pair. If true, deletes will be made immediately after swiping.
deletedProperty | String | No | "deleted" | Name of the item object property in which to store the deleted status of an item.
dividerFunction | Function | No |  | Function to create divider elements.
dividerTemplate | Function | No | list-divider | Function to format a divider.
dragDatatype | String | No | none | Used for drag&drop reordering. If specified, will allow items to be dragged from one list to another of the same data type.
emptyTemplate | String | No | default template | File path relative to the app folder for template for empty list; this is only implemented for lists loaded via the itemsCallback property.
fixedHeightItems | Boolean | No | false | If true, list widget will apply optimizations for fixed height items.
formatters | Function | No |  | Object functions to format list entries based on model properties.
hasNoWidgets | Boolean | No | false | Specify true for this if the list has no child widgets; allows for faster processing of simple lists; in versions of the List widget where this property does not exist, behavior will be as if hasNoWidgets was set to false.
initialAverageRowHeight | Integer | No |  | Initial value used for average height estimation.
itemsCallback | Function | No | none | Items will be loaded as needed by calling this function of the form: callback(widget, offset, count)
itemsProperty | String | No | items | Model property for the items list.
itemTemplate | String | Yes |  | File path relative to the app folder for the item template.
listTemplate | String | No |  | File path relative to the app folder for the container template. The container template must contain #{-listElements} or not items will be rendered.
lookahead | Integer | No | 15 | Number of items to fetch ahead when loading new items.
nullItemTemplate | String | No | default template | File path relative to app folder for template for items that are rendered before loading.
onItemRendered | Function | No | none | Called each time an item is rendered into the DOM with these arguments: (listWidget, itemModel, itemNode)
preventDeleteProperty | String | No |  | If specified, the item models will be checked for this property, and swipeToDelete will be ignored on that item if the item model's property is truthy.
renderLimit | Integer | No | 20 | Max number of items to render at once; increase this if the UI overruns the list boundaries.
reorderable | Boolean | No | false | If true, list entries can be reordered by drag and drop.
swipeToDelete | Boolean | No | false | If true, list entries can be deleted with a swipe.
uniquenessProperty | String | No | none | Name of an item model property which can be used to uniquely identify items. If specified, List will maintain a hash of swiped items instead of setting a deleted property, preventing the app from having to persist the deleted property.

### Model Properties

Name | Type | Req'd | Default | Description
--- | --- | --- | --- | ---
items | Array | No | none | A list of objects to display in the list. Required unless the itemsCallback property is set as an Attribute property.
disabled | Boolean | No | false | Model property name for disabled.
label | String | No | null | Model property name for label.

### Methods

To invoke a method on a widget, use the scene controller's `get` method for the desired widget, and append `mojo` followed by the method.

Example:

>     this.controller.get('myWidget').mojo.getValue()

Method | Arguments | Description
--- | --- | ---
focusItem | itemModel, focusSelector | Focus the item designated by the item model; optionally pass in the focusSelector to focus a specific element within the item.
getItemByNode | node | Returns the item model associated with the list item containing the given node, if any. Returns undefined if not.
getLength |  | Returns the current length of the list.
getLoadedItemRange |  | Returns a hash with offset & limit properties indicating the range of currently loaded item models (or items which have been requested). This is sometimes used on the service side to optimize subscription data.
getMaxLoadedItems |  | Returns the maximum number of loaded items the list will maintain in its local cache. Function has no affect when the list size != 0.
getNodeByIndex | index | Return top level node for the list item of the given index. Returns undefined if the item does not exist or is not currently rendered.
invalidateItems | offset, limit | Causes the given items to be reloaded (if currently loaded). If limit is unspecified, causes all items after 'offset' to be invalidated.
noticeAddedItems | offset, items (array) | Inserts the given array of items into the list at the given offset.If list items are dynamically loaded, this may cause some to be kicked out of the cache. Calling this API will not cause a property-change event to be fired.
noticeRemovedItems | offset, limit | Removes items from the list beginning at the given offset, and continuing for 'limit' items. If list items are dynamically loaded, this may cause new ones to be requested. Calling this API will not cause a property-change event to be fired.
noticeUpdatedItems | offset, items (array) | Causes the given items to be replaced and re-rendered. Items provided past the current end of the list will cause the length to grow. MUST pass an array.
revealItem | index, animate (boolean) | Attempts to scroll the scene to reveal the item with the given index. May behave poorly when working with variable height list items which are not currently loaded, since we can't accurately predict the height of the final rendered content.
setLength | length | Call to set the overall length of the list. This function will set the limit on what range of items may be requested, but will generally not invalidate any existing items or request any new ones. It MAY request new items when the currently loaded items window is either not full, or the length change causes the items window to move. The latter case can occur if the length change causes the window to be "out of bounds", or if it would ideally be positioned past the end of the list.
setLengthAndInvalidate | length | Behaves like setLength, except that all currently loaded items are invalidated. For lazily loaded lists, this API will result in a request for a whole window of items. Note that items are invalidated even when the length of the list does not actually change.
showAddItem | boolean | Shows the "add item" in the list.