List

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

The List module can be used to render an array of data as follows:

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 specific methods and maintains the various key DOM / property references.

Constructor

As seen in the example above, the List constructor (as well any derivative dgrid constructors, e.g. Grid, OnDemandGrid, etc.) can accept 2 properties: an object containing initial properties to set on the instance, and a DOM node or string referencing a DOM node's ID (the srcNodeRef). If a srcNodeRef is provided, the given DOM node will become the instance's domNode; otherwise the instance will need to be placed into the document manually.

Each dgrid instance's domNode is given a unique ID, based on one of the following criteria:

• If a srcNodeRef was provided and has an ID, this ID will be used
• If an id was specified in the arguments object, that will be used
• Otherwise, an ID will be automatically generated, in the form dgrid_<number>

It is important to note that DOM node IDs are not allowed to contain spaces; therefore, one should never include spaces in the id property.

Property Summary

Property	Description
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.
className	A class (or classes, space- or period-delimited) to be set on the instance's domNode in addition to the defaults; if an existing DOM node is being passed to the constructor, extra classes may alternatively be specified via its class attribute or className property
cleanAddedRules	Whether to clean up CSS rules added via the addCssRule method when the instance is destroyed; defaults to true.
cleanEmptyObservers	Whether to clean up observers for result sets that are or become empty; defaults to true but is set to false by the tree plugin due to special considerations.
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", ...).
sort	How to initially sort the grid; may be either a string referencing a field name, or an array of objects with attribute and descending properties. See also set("sort", ...) below.
useTouchScroll	Whether to use the TouchScroll module if touch support is available on the device, or defer to native capabilities if they exist; true by default for backwards compatibility. Setting this to false is particularly useful for devices which support both touch and mouse input.

Method Summary

Method	Description
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
on(event, listener)	Basic event listener functionality; simply delegates to the top-level DOM element of the List, using standard dojo/on behavior.
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.
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 actually overrides this method.) item refers to the record from the array or 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 true is passed for descending, 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
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.
addCssRule(selector, css)	Programmatically adds styles for a given CSS selector by injecting a rule into a stylesheet in the document. Returns a handle with aremove function, which can be called to later remove the added style rule. Styles added via this method will be removed when the instance is destroyed if cleanAddedRules is set to true.