Grid

Grid

Grid extends List to provide tabular display of data items, with different fields arranged into columns.

APIs

In addition to the List methods outlined above, Grid also exposes the following:

• cell(target[, columnId]): Analogous to the row method, but at the cell level instead. The cell method can look up based on an event or DOM element, or alternatively, a data item (or ID thereof) and the ID of a column. Returns an object containing the following properties:
  • row: a Row object (as would be obtained from the row method) for the row the cell is within
  • column: the column definition object for the column the cell is within
  • element: the cell's DOM element
• left(cell[, steps]): Given a cell object (or something that resolves to one via the cell method), returns a cell object representing the cell located steps cells to the left (where steps defaults to 1), wrapping to previous rows if necessary
• right(cell[, steps]): Same as left(), but operating towards the right, wrapping to subsequent rows if necessary
• column(target): Returns the column definition object for the given column ID; typically analogous to cell(...).column
• styleColumn(columnId, css): Programmatically adds styles to a column, by injecting a rule into a stylesheet in the document. Returns a handle with a remove function, which can be called to later remove the added style rule.

Specifying grid columns

In the simplest cases, the columns of the grid are defined via the columns property. This property can be a hash (object) or array, containing column definition objects. When columns is an object, each property's key represents the id and field of the column, and each value is the column definition object. When columns is an array, the numeric indices become the column IDs; fields must be specified within each definition.

Generally, using object notation is slightly more concise and convenient. However, it's worth noting that doing so relies on the order of enumeration employed by the JavaScript runtime. Typically this isn't a problem, as it matches the order in which properties are specified, but one common exception is in the case of keys coercible to numbers.

For example, we could create a grid like so:

require(["dgrid/Grid"], function(Grid){
    var columns = {
        first: {
            label: "First Name"
        },
        last: {
            label: "Last Name"
        },
        age: {
            label: "Age",
            get: function(object){
                return (new Date() - object.birthDate) / 31536000000;
            }
        }
    };
    var grid = new Grid({ columns: columns }, "grid"); // attach to a DOM id
    grid.renderArray(arrayOfData); // render some data
    ...
});

Alternatively, the same columns as above could be defined in an array, as follows:

    var columns = [
        {
            label: "First Name",
            field: "first"
        },
        {
            label: "Last Name",
            field: "last"
        },
        {
            label: "Age",
            field: "age",
            get: function(object){
                return (new Date() - object.birthDate) / 31536000000;
            }
        }
    ];

A column definition may also be specified simply as a string, in which case the value of the string is interpreted as the label of the column. Thus, the simplest column structures can be more succinctly written:

var grid = new Grid({
    columns: {
        first: "First Name",
        last: "Last Name",
        ...
    },
    ...
}, ...);

Column Definition Properties

Each individual column definition object may have the following properties (all are optional):

• field: The property from the object in the list to display in the body of the grid (unless otherwise overridden via the get function, explained below). In cases where columns is passed an object, the key of each property represents the field name, and thus this property is normally ommitted.
• label: The label to show in the header of the grid. Defaults to the value of field.
• className: A CSS class to assign to the cells in the column. If unspecified, a default class name of the form field-<field> is used, where <field> is the value of the field property.
• id: The id of the column; normally this is determined automatically from the keys or indices in the columns object or array.
• sortable: Indicates whether or not the grid should allow sorting by values in this field, by clicking on the column's header cell. Defaults to true.
  • Note that it is always possible to programmatically sort a Grid by a given field by calling set("sort", property, descending) regardless of sortable status or even visible presence in the Grid altogether.
• get(item): An optional function that, given a data item, will return the value to render in the cell.
• set(item): An optional function that, given a data item, will return the value to set for that column on that item. If no value is returned, the originally set value will be used.
• formatter(value): An optional function that, given the value to be displayed, will return a string of HTML for rendering.
• renderCell(object, value, node, options): An optional function that will be called to render the value into the target cell. object refers to the record from the grid’s store for the row, and value refers to the specific value for the current cell (which may have been modified by the column definition’s get function). node refers to the table cell that will be placed in the grid if nothing is returned by renderCell; if renderCell returns a node, that returned node will be placed in the grid instead. (Note: if formatter is specified, renderCell is ignored.)
• renderHeaderCell(node): An optional function that will be called to render the column's header cell. Like renderCell, this may either operate on the node directly, or return a node to be placed within it.

Subrows

The Grid component also supports structures with multiple "subrows"; that is, it supports the idea of rendering multiple rows for each data item. Specification of multiple subrows is very much like specifying columns, except that one uses the subRows property instead of columns, and it receives an array of columns objects/arrays.

Both the columns and subRows properties can be later reset by using the central set method.

By default, the Grid renders a header, containing cells which display the label of each column. This can be disabled by setting showHeader: false in the arguments object to the Grid; it can also be changed later using set("showHeader", ...).