Hello dgrid!

The dgrid project was conceived by engineers at SitePen with the goal of
creating a next-generation grid component that takes full advantage of modern
browsers and the new features in modern Dojo. It is designed to be lightweight,
modular, and easily extensible, and is released under the same licensing and
CLA as the Dojo Toolkit.

Obtaining dgrid

dgrid is one of the first new Dojo packages to be distributed
standalone instead of as a part of the DojoX namespace. This distribution model
is part of a shift toward a distributed component development model in Dojo 2,
made possible by advances in distributed code services like GitHub.

Getting started with dgrid

In order to use dgrid, we start by loading Dojo 1.8+ and the dgrid Grid module, along with dgrid's structural CSS:

If you're migrating from earlier versions of dgrid, note that you must load dgrid.css yourself
in dgrid 1.0, as the xstyle dependency has been dropped. If you don't need all of the structural styles, you can
use Stylus to import just the specific parts you need
(starting with dgrid/css/base.styl at minimum).

With this skeleton code in place, in order to actually create a useful grid, we need
to define two things: the structure of the grid, and the data we want to use.
The structure of the grid should be passed in the columns key and can be
defined in one of three ways:

3. As a hash map, where the key is used as the "field" and the value is used
as the "label":

var columns = {
first: 'First Name',
last: 'Last Name',
age: 'Age'
};

In the rest of this tutorial, we’ll use the third form for brevity.

There are often additional configuration options for columns that you’d
provide beyond just a label, such as extra CSS classes, column formatters,
and so on, which is why you’d often use one of the first two structure
definitions instead. Take a look at the “Specifying Grid Columns” section of the
Grid
documentation for more of those options.

With our grid’s column structure defined, we now need to actually provide some data
to display! While more advanced dgrid components like OnDemandGrid support data stores
directly, the most basic Grid module simply expects data to be provided as an
array of objects passed to the renderArray method:

We now have a working grid displaying data from a simple JavaScript data source!
Additional data can be appended to the grid by calling renderArray
again; to clear the existing data, call grid.refresh().

Expanding functionality with mixins and extensions

So far, the grid we’ve created is very bare-bones. dgrid is specifically
designed so that you only “pay” for the features you want to use, which means that
things like keyboard navigation, row/cell selection, cell editors, and
column resizing don’t exist by default and must be requested explicitly when you
want to use them.

To do this, simply declare a new grid class using dojo/_base/declare
that mixes in all of the desired feature extensions:

After mixing in Selection and Keyboard, we have a grid which features keyboard navigation
and selectable rows. However, we aren’t actually handling anything when users interact with it.
Adding event listeners will give us this control.

Handling Events

dgrid uses the dojo/on module introduced in Dojo 1.7 for handling events.
Listening for events on a particular grid instance is as simple as calling
grid.on, which effectively listens for events received by the grid’s
top-level DOM node. Combined with event delegation, this mechanism can be used to easily
and efficiently listen for DOM events on any component within the grid, such as individual
cells and rows.

In addition to standard DOM events, some dgrid components emit their own custom
events. For example, the Selection mixin fires dgrid-select and
dgrid-deselect events. Using these, we can begin to look at what’s happening
when a user interacts with the grid:

In order to use event delegation, you must make sure you’ve
loaded dojo/query. Making this module optional helps keep the
filesize down when you don’t want or need any event delegation.

What now?

So far, this tutorial has given just a glimpse of what dgrid offers. Future
dgrid tutorials will explore some of the additional components offered out of
the box, such as
OnDemandList,
which allows you to connect your
grid directly to a dstore store. In the meantime,
check out the
dgrid documentation and
let us know if you have any
issues!