Mixins

Mixins

Mixin modules can be used to add extra functionality to a list or grid. To use these, simply add the module as a mixin in a dojo.declare inheritance chain. For example, to create a grid based on OnDemandGrid with the Selection and Keyboard handling mixins, we could do the following:

define(["dojo/_base/declare", "dgrid/OnDemandGrid", "dgrid/Selection", "dgrid/Keyboard"],
function(declare, OnDemandGrid, Selection, Keyboard){
    // create a new Grid constructor including some mixins
    var MyGrid = declare([OnDemandGrid, Selection, Keyboard]);
    // instantiate it
    var grid = new MyGrid({
        store: myStore,
        ...
    }, "grid");
    ...
});

You can also perform inline mixin and instantiation:

var grid = new (declare([OnDemandGrid, Selection, Keyboard]))({
    store: myStore,
    ...
}, "grid");

A synopsis of currently available mixins follows.

ColumnSet

The ColumnSet module provides functionality which divides a grid's columns into multiple distinct sets, each of which manage their columns' horizontal scrolling independently. This makes it possible to keep certain columns in view even while others are scrolled out of viewing range.

When mixing in ColumnSet, instead of specifying columns or subRows, one specifies columnSets, which is essentially an array of subRows. For example, in pseudocode:

var grid = new (declare([Grid, ColumnSet]))({
    columnSets: [
        // left columnset
        [
            [
                { /* columnset 1, subrow 1, column 1 */ },
                { /* columnset 1, subrow 1, column 2 */ }
            ],
            [
                { /* columnset 1, subrow 2, column 1 */ },
                { /* columnset 1, subrow 2, column 2 */ }
            ]
        ],
        // right columnset
        [
            [
                { /* columnset 2, subrow 1, column 1 */ },
                { /* columnset 2, subrow 1, column 2 */ }
            ],
            [
                { /* columnset 2, subrow 2, column 1 */ },
                { /* columnset 2, subrow 2, column 2 */ }
            ]
        ]
    ],
    ...
}, "grid");

More concrete examples of ColumnSet usage can be found in the complex_column.html test page.

APIs

The ColumnSet mixin defines the following additional instance method:

• styleColumnSet(columnsetId, css): Programmatically adds styles to a columnset, 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.

Selection

Adds selection capability to a list or grid. The resulting instance(s) will include a selection property representing the selected items. This mixin will also fire batched dgrid-select and dgrid-deselect events, which will possess a rows property containing an array of Row objects (with id, data, and element). For example:

grid = declare([Grid, Selection])({
    selectionMode: "single",
...});
grid.on("dgrid-select", function(event){
    // get the rows that were just selected
    var rows = event.rows;
    // ...
    
    // iterate through all currently-selected items
    for(var id in grid.selection){
        // ...
    }
});
grid.on("dgrid-deselect", function(event){
    // get the rows that were just deselected
    var rows = event.rows;
    // ...
});

APIs

The following properties and methods are added by the Selection mixin:

• selection: The object containing the IDs of the selected objects.
• selectionMode: A string indicating the mode of selection. The following values are acceptable:
  • extended: The default setting; follows common ctrl and shift key practices for selection
  • single: Only allows one row to be selected at a time
  • multiple: Similar to extended, but normal clicks add selection without removing previous selections
  • none: Nothing can be selected by user interaction; only programmatic selection (or selection via selectors) is allowed
• deselectOnRefresh: Determines whether calls to refresh (including sorts) also clear the current selection; true by default.
• allowSelectAll: Determines whether the "select-all" action should be permitted via a checkbox selector column or the Ctrl/Cmd+A keyboard shortcut; defaults to false.
• allowSelect(row): Returns a boolean indicating whether the given row should be selectable; designed to be overridden.
• select(row[, toRow]): Programmatically selects a row or range of rows.
• deselect(row[, toRow]): Programmatically deselects a row or range of rows.
• selectAll(): Programmatically selects all rows in the component. Note that only rows that have actually been loaded will be represented in the selection object.
• clearSelection(): Programmatically deselects all rows in the component.
• isSelected(row): Returns true if the given row is selected.

The select, deselect, and isSelected methods can be passed any type of argument acceptable to List's row method.

Events

As indicated above, the Selection mixin will emit two custom events:

• dgrid-selected: Emitted when one or more rows are selected
• dgrid-deselected: Emitted when one or more rows are deselected

Note that this means that when a user interaction results in the selection being changed from one row to another, both events will be fired (with the dgrid-deselected event firing first).

Both of these events expose the following properties:

• grid: The Grid (or List) instance in which the event occurred
• rows: Array containing any rows affected by the event
• parentType: If the event was triggered by user interaction, this property indicates what type of event originally triggered the event

Note that rows is always an array, even if only one row was (de)selected.

CellSelection

The CellSelection mixin extends upon the functionality of the Selection mixin to provide selection at the cell level instead. Some key differences include:

• The selection object now stores a hash of hashes, where the outer hash is keyed by item ID and the inner hash is keyed by column ID.
• The dgrid-select and dgrid-deselect events still fire, but include a cells property containing an array of cell objects, rather than a rows property.
• Whereas Selection's select, deselect, and isSelected methods look up the passed argument via List's row method, CellSelection looks it up via Grid's cell method.
• The allowSelect method is passed a cell object instead of a row object.

Keyboard

This mixin adds keyboard handling functionality. The arrow keys can be used to navigate the focus across cells and rows, providing accessibility and ease of use. The page up and page down keys may also be used for faster navigation, traversing the number of rows specified in the pageSkip property of the instance.

When used with grids, this mixin references the cellNavigation property of the grid instance, to determine whether keyboard navigation and focus should operate at the individual cell level (true, the default) or at the row level (false).

APIs

The Keyboard mixin supports the following additional methods and properties:

• cellNavigation: Boolean indicating whether keyboard navigation should occur at the row or cell level. Defaults to true (cell-level) for grids, false (row-level) for lists.
• focus([target]): Focuses the given target cell or row (depending on the value of cellNavigation), or on the last focused target if none is provided.
• focusHeader([cell]): Focuses the header row. If cellNavigation is true, will focus on the given cell, or the last header cell to be focused if none is provided.

Events

The Keyboard mixin also emits two custom events, dgrid-cellfocusin and dgrid-cellfocusout, when keyboard navigation occurs. Both events bubble, and include the following properties:

• grid: The instance in which the event occurred
• row or cell (depending on value of cellNavigation instance property): A row or cell object representing the target of the event
• parentType: If the event was triggered by user interaction, this property indicates what type of event originally triggered the event