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.