List.md

List

List provides the basic facilities for taking an array of objects and rendering them as rows in a scrollable area.

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.
addUiClasses	Boolean indicating whether to add ui- classes (corresponding to jQuery UI) to nodes within the grid. The default is true.
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.
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 property and descending properties. See also set("sort", ...) below.

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", ...)).
set(object)	Alternate means of invoking set, equivalent to calling set(property, value) for each key/value pair in the provided object.
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, preserveDom, options)	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 store's sort method (an array of objects with property and descending properties); this is also the format get("sort") will return in. The Grid and OnDemandList modules further extend sort functionality.
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 the given rule string into a stylesheet in the document. Returns a handle with a remove 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.