Usage-Comparison.md

Usage Comparison Between dojox/grid and dgrid

Simple programmatic usage

Given the following programmatic example using dojox/grid...

require([
    'dojox/grid/DataGrid',
    'dojo/store/Memory',
    'dojo/data/ObjectStore',
    'dojo/domReady!'
], function (DataGrid, Memory, ObjectStore) {
    var memoryStore = new Memory({ data: [
        // data here...
    ]});
    var objectStore = new ObjectStore({ objectStore: memoryStore });

    var grid = new DataGrid({
        structure: [
            { field: 'id', name: 'ID', width: '10%' },
            { field: 'name', name: 'Name', width: '20%' },
            { field: 'description', name: 'Description', width: '70%' }
        ],
        store: objectStore
    }, 'grid');
    grid.startup();
});

A result similar to the above example could be achieved using dgrid with the following styles...

#dgrid .field-id {
    width: 10%;
}
#dgrid .field-name {
    width: 20%;
}
#dgrid .field-description {
    width: 70%;
}

...and the following JavaScript...

require([
    'dojo/_base/declare',
    'dgrid/OnDemandGrid',
    'dgrid/Keyboard',
    'dgrid/Selection',
    'dstore/Memory',
    'dojo/domReady!'
], function (declare, OnDemandGrid, Keyboard, Selection, Memory) {
    var memoryStore = new Memory({data: [
        // data here...
    ]});

    var grid = new declare([ OnDemandGrid, Keyboard, Selection ])({
        columns: {
            id: 'ID',
            name: 'Name',
            description: 'Description'
        },
        collection: memoryStore
    }, 'grid');
    // dgrid will call startup for you if the node appears to be in flow
});

There are a few key differences worth pointing out:

• Whereas dojox/grid expects styles to be specified within the column definition to be eventually applied inline to all cells in the column, dgrid lets CSS do the talking whenever possible for purposes of layout and appearance. This allows for better separation between visual and functional concerns.
• dojox/grid operates with stores implementing the earlier dojo/data APIs; in order to use it with a store instance implementing the dojo/store APIs, the store must first be wrapped using the dojo/data/ObjectStore module. On the other hand, dgrid communicates with dstore APIs out of the box. (Conversely, however, if you do need to work with a dojo/data store, you would then have to pass it through the dojo/store/DataStore and dstore/legacy/StoreAdapter wrappers in order for dgrid to work with it.)
• Note that in the dgrid version of the example, the Selection and Keyboard modules are required and mixed into the constructor to be instantiated, in order to enable those pieces of functionality which are baked-in by default in dojox/grid components.
• Also note that the dgrid example's structure is a bit more concise, taking advantage of the ability to provide simple column arrangements via an object hash instead of an array, in which case the object's keys double as the columns' field values (i.e., which store item properties the columns represent).

Programmatic usage, with sub-rows

Assuming the same context as the examples in the previous section, here is a contrived example demonstrating use of sub-rows in dojox/grid...

var grid = new DataGrid({
    structure: [
        [
            { field: 'id', name: 'ID', width: '10%' },
            { field: 'name', name: 'Name', width: '20%' }
        ],
        [
            { field: 'description', name: 'Description', width: '70%', colSpan: 2 }
        ]
    ],
    store: objectStore
}, 'grid');
grid.startup();

...and the equivalent, using dgrid... (again assuming the same context as the previous example)

var grid = new declare([ OnDemandGrid, Keyboard, Selection ])({
    subRows: [
        [
            { field: 'id', label: 'ID' },
            { field: 'name', label: 'Name' }
        ],
        [
            { field: 'description', label: 'Description', colSpan: 2 }
        ]
    ],
    collection: memoryStore
}, 'grid');

Notice that subRows is now defined instead of columns. The columns property of dgrid components is usable only for simple cases involving a single sub-row.

Also notice that each item in the top-level subRows array is itself another array, containing an object for each column. In this case, field must be specified in each column definition object, since there is no longer an object hash in order to infer field names from keys.

Using views / columnsets

The dojox/grid components implement a concept known as "views", which are represented as separate horizontal regions within a single grid. This feature is generally useful for situations where many fields are to be shown, and some should remain visible while others are able to scroll horizontally.

This capability is also available in dgrid, via the ColumnSet mixin.

For instance, continuing in the vein of the examples in the previous two sections, the following dojox/grid structure with multiple views...

var grid = new DataGrid({
    structure: [
        { // first view
            width: '10%',
            cells: [
                { field: 'id', name: 'ID', width: 'auto' }
            ]
        },
        [ // second view
            [
                { field: 'name', name: 'Name', width: '20%' },
                { field: 'description', name: 'Description', width: '80%' }
            ]
        ]
    ],
    store: objectStore
}, 'grid');
grid.startup();

...could be represented in dgrid, using the following CSS...

#dgrid .dgrid-column-set-0 {
    width: 10%;
}
#dgrid .field-name {
    width: 20%;
}
#dgrid .field-description {
    width: 80%;
}

...and the following JavaScript... (require call included, to demonstrate additional dependency)

require([
    'dojo/_base/declare',
    'dgrid/OnDemandGrid',
    'dgrid/ColumnSet',
    'dgrid/Keyboard',
    'dgrid/Selection',
    'dstore/Memory',
    'dojo/domReady!'
], function (declare, OnDemandGrid, ColumnSet, Keyboard, Selection, Memory) {
    // ... create memoryStore here ...

    var grid = new declare([ OnDemandGrid, ColumnSet, Keyboard, Selection ])({
        columnSets: [
            [ // first columnSet
                [
                    { field: 'id', label: 'ID' }
                ]
            ],
            [ // second columnSet
                [
                    { field: 'name', label: 'Name' },
                    { field: 'description', label: 'Description' }
                ]
            ]
        ],
        collection: memoryStore
    }, 'grid');
});

Specifying column layout via HTML

While programmatic creation of grids is highly encouraged, dgrid does allow for declarative specification of grid layouts via a table element, somewhat along the same lines of dojox/grid.

In the case of dgrid, this ability is not baked in by default, but is instead exposed primarily by the GridFromHtml module, which adds table-scanning capabilities atop the OnDemandGrid constructor.

Note that unlike dojox/grid, which is only capable of reading declarative layouts through the use of dojo/parser, dgrid is also capable of creating instances programmatically while referencing a table node from which to read a declarative layout. For the purposes of the examples below, use of parser will be assumed, in order to allow comparison between dojox/grid and dgrid usage.

For instance, the following declarative dojox/grid layout...

<table id="grid" data-dojo-type="dojox/grid/DataGrid"
    data-dojo-props="store: objectStore">
    <thead>
        <tr>
            <th field="id" width="10%">ID</th>
            <th field="name" width="20%">Name</th>
            <th field="description" width="70%">Description</th>
        </tr>
    </thead>
</table>

...could be achieved declaratively using dgrid as follows...

<table id="grid" data-dojo-type="dgrid/GridFromHtml"
    data-dojo-mixins="dgrid/OnDemandList, dgrid/Keyboard, dgrid/Selection"
    data-dojo-props="collection: memoryStore">
    <thead>
        <tr>
            <th data-dgrid-column="{ field: 'id' }">ID</th>
            <th data-dgrid-column="{ field: 'name' }">Name</th>
            <th data-dgrid-column="{ field: 'description' }">Description</th>
        </tr>
    </thead>
</table>

Notice that rather than specifying individual non-standard attributes inside the th elements, declarative layout specification with dgrid centers primarily around a data-attribute named data-dgrid-column. This attribute receives a string representation of a JavaScript object, which will ultimately become the basis for the column definition. (It operates much like data-dojo-props, except that the surrounding curly braces must be included.)

Note that some properties which have standard equivalents, such as colspan and rowspan, can be specified directly as HTML attributes in the element instead. Additionally, the innerHTML of the th becomes the column's label.

Note that since the modules in the dgrid package are written to be pure AMD, they do not expose globals, so module ID syntax must be used when parsing declarative dgrid instances. data-dojo-mixins can be used to incorporate the desired functionality, analogous to using declare programmatically.

Column Layout via HTML with views / columnsets

While both dojox/grid and dgrid also enable declarative creation of grids with multiple views/columnsets, in dgrid's case this is again separated to its own module, GridWithColumnSetsFromHtml. This separation exists due to the significant amount of additional code necessary to resolve columnsets from the representative markup, combined with the relative rarity of cases calling for the additional functionality.

As a quick example, here is what a simple declarative grid with two views could look like with dojox/grid...

<table id="grid" data-dojo-type="dojox/grid/DataGrid"
    data-dojo-props="store: objectStore">
    <colgroup span="1" width="10%"></colgroup>
    <colgroup span="2"></colgroup>
    <thead>
        <tr>
            <th field="id" width="auto">ID</th>
            <th field="name" width="20%">Name</th>
            <th field="description" width="80%">Description</th>
        </tr>
    </thead>
</table>

...and here is the equivalent, using dgrid... (this assumes the same styles are in play as the earlier programmatic ColumnSet example)

<table id="grid" data-dojo-type="dgrid/GridWithColumnSetsFromHtml"
    data-dojo-mixins="dgrid/OnDemandList, dgrid/Keyboard, dgrid/Selection"
    data-dojo-props="collection: memoryStore">
    <colgroup span="1"></colgroup>
    <colgroup span="2"></colgroup>
    <thead>
        <tr>
            <th data-dgrid-column="{ field: 'id' }">ID</th>
            <th data-dgrid-column="{ field: 'name' }">Name</th>
            <th data-dgrid-column="{ field: 'description' }">Description</th>
        </tr>
    </thead>
</table>

Events

dojox/grid and dgrid take significantly different approaches to handling events. dojox/grid provides a wide selection of stub methods which can be connected to in order to react to many common events on rows or cells in the header or body. The Working with Grids tutorial gives an idea of what kinds of events are supported by dojox/grid.

On the other hand, dgrid leaves it up to the developer as to which events are at all worth listening for. This results in generally far less overhead, since listeners are hooked up only for events of interest; at the same time, it still allows for the same range of event listeners as dojox/grid.

dojox/grid components generally attach any useful information directly to the event object received by the handler callback. While dgrid does this to a certain degree for custom events, the most commonly-sought information is retrievable using the row and cell methods.

See Working with Events for more information.

As a quick side-by-side comparison, here is an example logging the name property of an item whose row was clicked, using dojox/grid...

grid.connect(grid, "onRowClick", function(evt){
    var item = grid.getItem(evt.rowIndex);
    // don't forget to use store.getValue, since dojox/grid uses a dojo/data store
    console.log("Clicked item with name: " +
        grid.store.getValue(item, "name"));
});

...and using dgrid...

grid.on('.dgrid-row:click', function (event) {
    var item = grid.row(event).data;
    console.log('Clicked item with name: ' + item.name);
});