List

List

This provides the basic facilities for taking an array of objects and rendering as rows of HTML in a scrollable area. This will automatically include touch scrolling capabilities (via the TouchScroll module) on mobile devices.

The List can be used to render an array of data. For example:

require(["dgrid/List"], function(List){
    // attach to a DOM element indicated by its ID
    var list = new List({}, "list");
    // render some data
    list.renderArray(arrayOfData);
});

APIs

The base List class (inherited by all other classes) exposes the following methods:

• get(property): Returns the value of a given property. Supports custom getter implementations via the pattern _getProperty (which would map to get("property")).
• set(property, value): Sets the value of a given property. Supports custom setter implementations via the pattern _setProperty (which would map to set("property", ...)).
• row(target): This will look up the requested row and return a Row object. The single parameter may be a DOM event, DOM node, or in the case of store-backed components, a data object or its ID. The returned Row object has the following properties:
  • id: the data object's id
  • data: the data object represented by the row
  • element: the row's DOM element
• up(row[, steps]): Given a row object (or something that resolves to one via the row method), returns a row object representing the row located steps rows above (where steps defaults to 1)
• down(row[, steps]): Same as up(), but operating downward
• on(event, listener): Basic event listener functionality; simply delegates to the top-level DOM element of the List, using standard dojo/on behavior.
• renderArray(array, beforeNode, options): This can be called to render an array directly into the list. The beforeNode parameter can be used to render at a specific point in the list. Note that when using store-backed components, this is called automatically.
• renderRow(item, options): This method can be overridden to provide custom rendering logic for rows. (The Grid module, introduced next, actually overrides this method.) item refers to the record from the grid’s data store for the row.
• removeRow(rowElement, justCleanup): This method can be extended/aspected to perform cleanup logic when an individual row is removed.
• set("sort", property, descending): This can be called to sort the List by a given property; if the second parameter is passed true, the sort will be in descending order. Multiple sort criteria can be specified in the format expected by stores' queryOptions (an array of objects with attribute and descending properties); this is also the format get("sort") will return in. The Grid and OnDemandList modules further extend sort functionality.
• showHeader: Whether to display the header area; normally false for lists and true for grids. Can be reset later via set("showHeader", ...).
• showFooter: Whether to display the footer area; false by default, but enabled and used by some extensions (e.g. Pagination). Can be reset later via set("showFooter", ...).
• scrollTo(options): scrolls to a given point in the grid. Accepts x and y properties; if one is not given, position along that axis is not modified.
• getScrollPosition(): returns the current position that the grid is scrolled to, in the form of an object containing x and y properties.

Lists, as well as all other dgrid components, maintain the following DOM references:

• domNode: The top-level DOM node of the component (much like the domNode property of Dijit widgets).
• headerNode: The DOM node representing the header region; mainly applicable to grid components.
• bodyNode: The DOM node representing the body region (the area which will show rows for each item).
• contentNode: The DOM node immediately under the bodyNode, which may potentially be scrolled to accommodate more content than the component's height will allow to fit.
• footerNode: A DOM node appearing below the bodyNode; initially empty and not displayed by default.