Login Register

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:

<style type="text/css">
        /* tundraGrid.css matches Dijit Tundra style.  Others forthcoming.
            Use Grid.css on the same path for a more color-neutral theme */
        @import "http://o.aolcdn.com/dojo/1.0.0/dojox/grid/_grid/tundraGrid.css";
        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>

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:

<div dojoType="dojo.data.ItemFileReadStore"
                jsId="jsonStore" url="dijits.txt">

        </div>
        <div dojoType="dojox.grid.data.DojoData" jsId="model"
                rowsPerPage="20" store="jsonStore" query="{ namespace: '*' }">

        </div>

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:

<div id="grid" dojoType="dojox.Grid" model="model" structure="layout"></div>

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:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
        <title>Test dojox.Grid Basic</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
        <style type="text/css">
        @import "http://o.aolcdn.com/dojo/1.0.0/dojox/grid/_grid/tundraGrid.css";
        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
                body {
                        font-size: 0.9em;
                        font-family: Geneva, Arial, Helvetica, sans-serif;
                }
                .heading {
                        font-weight: bold;
                        padding-bottom: 0.25em;
                }
                               
                #grid {
                        border: 1px solid #333;
                        width: 35em;
                        height: 30em;
                }
        </style>
        <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
                djConfig="isDebug:false, parseOnLoad: true">
</script>
        <script type="text/javascript">
            dojo.require("dojo.data.ItemFileReadStore");
                dojo.require("dojox.grid.Grid");
                dojo.require("dojox.grid._data.model");
                dojo.require("dojo.parser");
       
                // 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"}
                          ]
                        ]
                };
                // a grid layout is an array of views.
                var layout = [ view1 ];
</script>
</head>
<body class="tundra">
<div class="heading">Our First Grid</div>
        <div dojoType="dojo.data.ItemFileReadStore"
                jsId="jsonStore" url="dijits.txt">

        </div>
        <div dojoType="dojox.grid.data.DojoData" jsId="model"
                rowsPerPage="20" store="jsonStore" query="{ namespace: '*' }">

        </div>
        <div id="grid" dojoType="dojox.Grid" model="model" structure="layout"></div>
</body>
</html>

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:

AttachmentSize
dijits.txt20.07 KB

How to refresh the grid when underlying data changes

The grid widget is great!
I wonder if there is nice programatical way (assuming having a grid setup like decribed above) to update the grid when the data on the server side changes (like dijits.txt has changed when requerying)?
I searched the site and tried several methods form the grid object (refresh, render, update) but couldn't find anything helpful.

Yes, just use

... QueryReadStore for your data store. I think there's an example on the Sorting page of how to do it.

Some experiments with Version 1.0.2...

Grid in dialog

Just to comment, I just had a little problem showing this sample on a Dialog.. It was solved calling the .render() method of the grid.
Regards!

How to show a picture in a cell

I tried this:

var img = "<img src=\"img/img1.jpg\"/>";

var data = [
[img]
];

var vista1 = {
cells: [[
{name: 'Imagen', width: "80px", height: "65px"}
]]
};

Can I do this in other way???

(Very minor) No need to download dijits.txt for html sample code

With 1.0.2, if you save the above html into /[top dojo directory]/dijit/tests/, you can change

url="dijits.txt"

to

url="_data/dijits.json"

and everything will work fine.

Is there a way to overirde the name of the items arrays?

that is the ItemFileReadStore assumes there is an items array element holding the rows

{"timestamp":1193692111, "items":[
{"Version":"1","title":"The title","body":"This is ...","created":"2007-11-07 00:44:54"},
{"Version":"2","title":"A title once again","body":"And ...","created":"2007-11-07 00:45:15"}
]}

is it possible to send

{"timestamp":1193692111, "versions":[
{"Version":"1","title":"The title","body":"This is ...","created":"2007-11-07 00:44:54"},
{"Version":"2","title":"A title once again","body":"And ...","created":"2007-11-07 00:45:15"}
]}

and reconfig the ItemFileReadStore to identify items using the "versions" element?