A Simple Grid

To begin working with Grid, let's start with a simple example. The Dijit class directory is kept in /dijit/tests/_data/dijits.json. We'll base on a grid on it, and add embellishments throughout the next few sections.

Our First Grid

The Basics

Every page using Grid needs to import the basic grid style sheet. When used with Dijit and Dojo, your combined style loading block should look like:

The Model

Each Grid begins with data, and two DIV tags will define our data source. Because of the same-origin security rule, you will need to place the data file on your web server. You can download this file, dijits.json, at the bottom of this page. Just place it in the same directory as the example: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

The first DIV should look familiar. It's the good ol' dojo.Data definition you use with the Dijit components ComboBox or Tree. The second is new - it's the dojox.grid.data.DojoData adapter that turns a data source into a Grid model. The model has options for which items to select. In this example, we turn the datasource jsonStore into the model named "model".

Models can also be created from JavaScript arrays, which we'll see in: Model Options.

The View

In standard spreadsheet and table terminology, a cell is the basic unit of displayed data. A row is a horizontally aligned contiguous group of cells, and a column is a vertically aligned contiguous group of cells. (Wow, that makes a simple concept sound complex!)

In grid-land, there's a distinction between rows and subrows. A subrow is what people normally think of as a row - it's exactly one cell tall. In Grid, a row may be more than one subrow - but it is selectable as a unit. So you'll notice in our demo grid that logical rows are exactly 2 subrows tall.

A View is a group of contiguous logical rows with the same inner and outer "shape". In our example above, each logical row is two subrows tall, with 2 columns on the top physical row and 1 column on the bottom physical row (the last cell spanning 2 columns). You specify this in JavaScript with an array of arrays. Each array element is an object literal. The most important property of the object is "name", which names the column. The column name always appear as the top logical row of the grid, and unlike other rows, it doesn't scroll up or down.

// a grid view is a group of columns
var view1 = {
	cells: [[
		{name: 'Namespace', field: "namespace"}, 
		{name: 'Class', width: "25em", field: "className"}
	  ],
	  [
		{name: 'Summary', colSpan:"2", field: "summary"}
	  ]
	]
};

Fields in the model are applied across each view cell in order. Property names are ignored. In our example, Namespace holds field 0, Class holds field 1, and so on.

As in good ol' HTML tables, you can specify:

• colSpan - note the capital "S" here, unlike standard HTML
• rowSpan
• width - all the usual CSS measurements are valid here

The Structure

Finally, views can be grouped together into a structure. You can think of a structure as a dijit.layout.LayoutContainer applied to views - you can place views in the top, bottom, left and/or right sides, plus one in the middle. Our simple example only has one view:

var layout = [ view1 ];

The Widget

The model and structure (which is composed of views) come together in the grid widget:

The model and structure attributes point to our JavaScript variables for the model and structure. Nice! And with no other code, the grid is:

• scrollable
• sizable in the columns - point between columns on the top and drag left or right
• row-selectable - just click anywhere on a row

So, here's the entire program:

Note that normally with CDN, you would need to wrap the view1 initialization code like in a dojo.addOnLoad. But that's not necessary here because no DOM needs to be drawn yet. We're just setting up anonymous objects. Because these are available when the widgets are drawn, we can use the structure property in the Grid tag. The design is nice and clean.

Now let's cover the model, view and structure elements in more depth:

Combining Views: Row Selection and Independent Scrolling

That's nice so far. The column header stays in place while the user scrolls down, making them easy to identify. Can we apply to that rows as well?

Yup. You can make row headers that stay in place and act as selection points.. What's more, you can split your grid into arbitrary scrollable sections that can stay in sync or scroll independently. You do this by gluing more than one view into a structure.

Selectable Rows

By default, when you click on a cell, you select that cell and the entire containing row. A special view called dojox.grid.GridRowView draws a column of empty handles. When clicked, these handles select the row without selecting a particular cell. Unlike most other views, GridRowView has no "cells" property, only a width. So adding this to the structure on our last page:

var rowbar = {
     type: 'dojox.GridRowView', width: '20px'
};
	    
// a grid layout is an array of views.
var layout = [ rowbar, view1 ];

The resulting page (downloadable below as grid1.html), yields:

As you would expect, CTRL+click selects non-contiguous rows and SHIFT+click selects contiguous ones. As it stands, the selection is only for display. In the Events section, we'll actually do something with the rows.

Linked Scrollable Views

You may have noticed that the Selection bar rows and the data rows scroll together. So it's no surprise that when you add another view, it too scrolls vertically in sync.

To see this, we'll split off the Dijit class name into its own view:

// a grid view is a group of columns
var view1 = {
	cells: [[
		{name: 'Namespace', field:0, width: "25em"}
	  ],
	  [
		{name: 'Summary', colSpan:"2", field:2}
	  ]
	]
};

var rowbar = {
   type: 'dojox.GridRowView', width: '20px'
   };

var fixedColumn = {
        cells: [[ {name: 'Class', field:1, width:"25em"} ]]
};

Since we're using fields in a different order, specifying the field numbers in each cell definition is mandatory. Now combine that into a layout like this:

var layout = [ rowbar, fixedColumn, view1 ];

And you get two grids with separate scroll bars. By default each scrollbar moves both views in sync with each other.

Admittedly, the extra scroll bar isn't very useful. But when you add fields to the right hand grid like so:

var view1 = {
	cells: [[
		{name: 'Namespace', field:0, width:"20em"}, 
		{name: 'Description', field:3, width:"20em"}
	  ],
	  [
		{name: 'Summary', field:2},
		{nane: 'Examples', field:4}
	  ]
	]
};

And run the example, you find the bottom scroll bar scrolls the views independently. We say the views are vertically dependent, but horizontally independent.

Now you turn off the scroll bar in the left hand view with the noscroll property:

var fixedColumn = {
    noscroll: true,
    cells: [[

Yields:

Sorting and Other Dojo.Data Considerations

By default, when dojo.data datasources feed a Grid, the columns are not user-sortable. That's easy to rectify. Just set clientSort="true" in the tag:

Now the user can click on any column to sort it. You may also set the sort order programmatically:

// Sort 4'th field in ascending order
myGrid.setSortIndex(3, true);

Filtering

To filter a list, you can create a new adapter with a different query then attach it to the grid.

//Construct a new model.  The store needs to be passed into the constructor, as the constructor for the
//DojoData model examines the store and configures the model to support various features of the store
//such as Write, Identity, and Notification.  Setting the store after the constructor will leave the
//model in a misconfigured state and be unable to support data writebacks in the case of Write implementing
// datastores.
var newModel = new dojox.grid.data.DojoData(null,null,{rowsPerPage: 20, store: myStore, query: {type: someOtherType}, clientSort: true});
myGrid.setModel(newModel);
// Remember to call newModel.destroy() when you're done.

A popular use of filtering is to display a grid with everything, then let the user chop the list down incrementally. In this case, you can define an initial model with a minimal query. Save it, and then you can setModel back to it for quickly resetting all the filters. But do not keep unused models lying around! They take up memory.

Cell Editing

Up until now, we've showed grid contents in view mode. Now, let's add some interactivity.

An editable cell is handled by a cell editor. To make a cell editable, you simply specify the cell editor class in the column definition. Here is a part of the view definition code in /dojoroot/dojox/grid/tests/test_edit.html.

gridLayout = [
	cells: [[
		{ name: 'Priority', styles: 'text-align: center;', 
                   editor: dojox.grid.editors.select, 
                   options: ["normal", "note", "important"]
                },
		{ name: 'Mark', width: 3, styles: 'text-align: center;', 
                   editor: dojox.grid.editors.bool 
                },
		{ field: 2, name: 'Status', styles: 'text-align: center;', 
                   editor: dojox.grid.editors.select, 
                   options: [ "new", "read", "replied" ] 
                }

In the actual grid, you double-click on a cell to begin editing. Here, we've double clicked on the status box, and a SELECT appears in place of the data:

Some of the cell editors, like dojox.grid.editors.DateTextBox are just wrappers for their Dijit form widget counterparts. All the functionality and properties are available to you. This is an example from /dojoroot/dojox/grid/tests/test_edit_dijit.html.

gridLayout = {
  cells: [[
	{ name: 'Date', width: 10, field: 7, 
           editor: dojox.grid.editors.DateTextBox, 
           formatter: formatDate, 
           constraint: {formatLength: 'long', selector: "date"}
       }
  ]]
};

Editing the Date cell brings up the familiar Dijit date box:

Now, what do you actually do with an edited cell? That's really up to you, and you hook in your desired code by connecting to an event, which we'll cover next.

Available Cell Editors

Events

As we alluded to in the last few pages, selection and cell editing is pointless without some kind of background processing. So how do you hook code into these places? Through Dojo's event model, of course!

Editing Changes

If you're using a writable dojo.data datastore, you simply hook your procedures into the dojo.data Notification API. Suppose in our running example, we make the Description field editable:

cells: [[
    {name: 'Namespace', field:0, width:"30em"}, 
    {name: 'Description', field:3, width:"30em",
        editor: dojox.grid.editors.Dijit }
  ]
],

Then, we place the hook into dojo.data.Notification's onSet extension point:

Here is the entire source code. Note how we place the layout initialization code in a dojo/method block inside the Grid tag. That's due to the editor class dojox.grid.editors.Dijit in the view definition. When you're using CDN, the dojox.grid.editors package is not available directly after the dojo.require., so we can't place the initialization code after it (as we did in our previous examples). By using a dojo/method, we can place this code close to its use (the Grid tag) and it's guaranteed to run after all dojo.require'd modules have loaded. You can also use dojo.addOnLoad to accomplish this.

You can read more on the dojo.data Notification API in Part 3 of the book, but here are the basics for your Grid needs:

• onSet: function(/* item */ item, /* attribute-name-string */ attribute, /* object | array */ oldValue, /* object | array */ newValue ) - called after any cell is edited and saved.
• onNew: function(/* item */ newItem,) - called after a row is added to the grid.
• onDelete: function(/* item */ deletedItem) - called after a row is deleted

Low-Level Events

For more granular event processing, you can hook into Grid events. Each event calls the function you provide, passing back the event object. If e is the event, the interesting stuff is in:

• e.rowIndex: the row number
• e.cell.index: the column (cell) number. Taken with e.rowIndex, effectively gives you coordinates of a cell event.
• e.keyCode: keystroke value, only applicable to keydown event.

Styles

Cell Styles

Fixed styles that apply to all cells of a column are settable in the view. The properties you need:

• classes: sets a CSS class for both header and contents
• styles: sets a CSS style for both header and contents
• headerClasses: sets a CSS class for column header. Combines with "classes".
• headerStyles: sets a CSS style for column header. Combines with "styles"
• cellClasses: sets a CSS class for the contents. Combines with "classes".
• cellClasses: sets a CSS class for the contents. Combines with "styles"

The onStyleRow Extension Point

The above properties make sweeping style changes across a column. But how do you change styles for individual cells? For example, suppose you want to color negative numbers red and positive numbers black.

The onStyleRow extension point can do this. Grid passes a Row object to your onStyleRow method. You set the properties customStyles and/or customClasses in this object, and Grid will restyle your row accordingly. The Row object has the following properties:

• selected, true if the row is selected;
• over: true of the mouse is over the row;
• odd: true if the row is odd.
• customClasses: you set this property for the CSS class
• customStyles: does the same with CSS styles

In the following example, we look at each row and color the row text red if the Dijit contains a description.

function colorDescriptions(inRow) {
   if (model.getRow(inRow.index) === undefined)
      return;
   if (model.getRow(inRow.index).description != '')
      inRow.customStyles = 'color:red';
}

You connect this function to the extension point in the Grid tag:

And behold ... red text where the row has a non-blank description

Cell Formatters

A cell formatter alters the text in the cell, not the styles. As you might guess, this is useful for formatting numbers, currency, dates, percentages, etc. The cell formatter is specified with the formatter extension point in the cell object:

{ name: 'Amount', formatter: formatCurrency, field: "moola"},

And define the formatter itself separately. (You can also use a function literal inside the cell definition).

function formatCurrency(inDatum){
	return isNaN(inDatum) ? '...' : dojo.currency.format(inDatum, { currency: 'USD' });
}

Liberal use of Dojo i18n for formatting dates and numbers is strongly encouraged!

Summary Rows

Grouping data for summarization requires a simple strategy. We will calculate a summary subrow for every row in the table, then just hide the ones not on a group boundary. So here is some (boring!) numeric data:

{ 
	identifier: 'id',
	label: 'name',
	items: [
        { id:'Q1_06', name: 'Q1 2006', year:2006, quarter:1, sales:345436 },
        { id:'Q2_06', name: 'Q2 2006', year:2006, quarter:2, sales:234525 },
        { id:'Q3_06', name: 'Q3 2006', year:2006, quarter:3, sales:129104 },
        { id:'Q4_06', name: 'Q4 2006', year:2006, quarter:4, sales:-10000 },
        { id:'Q1_07', name: 'Q1 2007', year:2007, quarter:1, sales:-178775 },
        { id:'Q2_07', name: 'Q2 2007', year:2007, quarter:2, sales:286027 },
        { id:'Q3_07', name: 'Q3 2007', year:2007, quarter:3, sales:429546 },
        { id:'Q4_07', name: 'Q4 2007', year:2007, quarter:4, sales:946375 }
    ]
}

To implement our strategy, we first build two functions which supply the total and total label for each totalling subrow.

function getYearlyLabel(inRowIndex) {
            return model.getRow(inRowIndex) ? "Total for " + model.getRow(inRowIndex).year : 'None';
        }
        function getYearlyTotal(inRowIndex) {
            return model.getRow(inRowIndex) ? (yearlyTotal += model.getRow(inRowIndex).sales) : -1;
        }

Next, we make an onAfterRow procedure to hide all the rows that are not after Q4

// inRow is an array of subRows. we hide the summary subRow except for every nth row
function onAfterRow(inDataIndex, inRow) {
    // note that header row inDataIndex == -1
    inRow[1].hidden = true;

    // Before rows 3, 7, 11 turn on display of the total
    if (inDataIndex != -1 && inDataIndex % 4 == 3) {
	yearlyTotal = 0;
        inRow[1].hidden = false;
    }
}

Then we wire it all up in the view definition:

var view1 = {
    onAfterRow: onAfterRow,
	cells: [[
		{name: 'Year/Quarter', field:'name'}, 
		{name: 'Sales', field:'sales'}
	],[
	    // The summary subrow, which will be hidden on most rows
		{name: 'Cell2', get: getYearlyLabel },
		{name: 'Yearly Sales', get:getYearlyTotal, styles:'font-weight:bold;'},
	]]
};

And the summary rows are displayed. Currently this example shows the summary row for all rows. A question is pending on the forums about this, and the example will be fixed accordingly.

Model Options

Array Models

Instead of feeding dojo.data sources to the grid, you may feed it a two-dimensional array. This approach works well for grids with fixed data, e.g. static reference tables. Here's an example culled from the unit test /dojoroot/dojox/grid/tests/test_grid.html. Note the following:

• Fields are numbered, not named, and start at 0.
• If the cells are laid out in the same order as the data elements, you may omit the field: property in the cells.
• Placing the initialization code in addOnLoad is necessary when using CDN because of the dojox.grid.data.Table reference.

Observers

You can watch for changes to cells at the model level. This is called setting an observer and it followed the familiar Observer Design Pattern. With array-fed Grids, these are your only hook-in points for sending XHR back to the server. As we saw in Events, you can use dojo.Data's notification API, or the Observer API for the same thing.

To observe a model, you first create an object literal with function properties. These functions must be named:

• modelChange: called when any cell data changes (due to editing or calling change methods on the model).
• modelInsertion: called when a row is added
• modelRemoval: called when a row is removed.
• modelAllChange: called when entire model needs to be re-rendered.
• modelRowChange: called when a row is changed
• modelDatumChange: called when cell data changes

For example, this observer watches all model changes and updates a visible row count.

var modelObservers = {
   modelChange:function(){
	dojo.byId("rowCount").innerHTML = 'Row count: ' + model.count; 
   }
}

Then you register the observer with the model:

model.observer(modelObservers);

Cell Options

Grid neatly separates the model from the view in its MVC implementation. We just covered the model. Now we'll cover the view - that is, everything used to display the model elements.

In the world of Grid, the structure is the largest unit. Structures are composed of views. Views are composed of cells (what we normally think of as a column). We'll start at this lowest level first. As we've seen a cell is defined by a JavaScript object like this:

{ name: 'Apple', field: 'apple', width: '4.5em' }

This defines a column with the heading of Apple and initial width of 4.5em, and mapped to the field 'apple' in the model. The field index can be a string, as is the case for dojo.Data-fed grids, or a number, as in array-fed Grids.

Cells themselves are not directly addressable. You usually get them by starting with a grid variable and work downwards:

// get the cell in the third view, second subrow, fourth column (all indexes are 0-based).
var thisCell = mygrid.structure[2].cells[1][3];

From here, you can access these properties and call these methods on thisCell:

View Options

Grid Tag

Grid Sizing

By default, the grid fits exactly in the parent DOM node provided for it. If all of the rows do not fit, a vertical scroll bar appears. Likewise, if all the columns don't fit, the horizontal scroll bar appears. Nothing surprising there.

The following properties resize the grid to fit all of the columns. In essence, setting either of these makes the appropriate scroll bar disappear.

• autoHeight: resize the grid height to fit all of the rows.
• autoWidth: resize the grid width to fit all the rows.

You may either set these on the Grid tag itself, or set the properties through JavaScript and call dojox.grid.Grid.update() to redraw. You can also resize the width and height of the container (dojo.contentBox is good for this) and call update().