Defining Grid Structures

In the Hello dgrid tutorial, we explored
the basic single-row column structures that dgrid has to offer, and in
this tutorial we aim to demonstrate further options for arranging
columns.

For the examples in this tutorial, we will be creating a grid with
various column structures containing information on hall of fame
batters. We will start off with a simple baseline grid containing just
the batters' first and last names. We'll store our batter information in
a JSON file and use the dstore/RequestMemory module to pull it in.

Remember to call startup since we are creating this grid
programmatically.

Parts of the Grid

The structure of a grid is comprised of multiple parts. Let's look at
these parts in detail.

Header

The header contains cells which display the label of each column. It can
be disabled by setting showHeader: false in the arguments
object passed to the Grid constructor; it can also be displayed or
hidden later using set("showHeader", ...)

Content

This is the region where rows are rendered for each data item.

Column Set

The dgrid/ColumnSet mixin provides functionality which
divides a grid's column structure into multiple distinct sets, each of
which manages its columns' horizontal scrolling independently. This
makes it possible to keep certain columns in view even while others are
scrolled out of viewing range.

Usage of column sets is completely opt-in; this will be further explained
later in this tutorial.

Row

The content section contains multiple rows of data. Each row
represents a single data item.

Sub-row

Sub-rows allow for breaking up the representation of each item across
multiple rows, which can aid in readability when there are many fields
to display. Since each item's full representation is already commonly
referred to as a "row", we refer to each of these rows within each item
as "sub-rows" to distinguish between the two concepts.

Cell

The smallest element of the grid, each cell typically represents one
field of a single data item.

Defining Sub-rows

Sub-rows can be useful when there are many fields to display. To
define a sub-row, we pass an array of arrays via the subRows
property of the arguments object. Each inner array defines the columns
for a single sub-row, in order; thus, in the following example, the first
inner array defines the top sub-row and the second array defines the bottom
sub-row:

When subRows is specified, it supersedes columns.
In fact, defining subRows with a single
inner array is equivalent to defining columns as an array.

You may have noticed that due to the widths of the columns in this example,
the entire grid horizontally scrolls. This can tend to happen when there
are many fields to display. Next we'll explore an alternative solution
to situations such as this one.

Defining Column Sets

Column sets allow us to define complex grid structures involving
multiple independently-scrolling sets of columns, each containing one or
more sub-rows. Column set functionality is provided via a separate mixin,
since it is a feature that isn't necessarily used in the majority of cases.

Thus, to incorporate support for column sets into a grid, we must first
use dojo/_base/declare to create a grid constructor which
includes the functionality from the ColumnSet mixin. We can then use the
custom constructor the same way we used OnDemandGrid, and additionally
specify the columnSets property:

Like subRows, the columnSets property accepts
a nested array; however, this array contains three levels of
arrays (column sets, sub-rows, then individual columns). This can be a
confusing concept, so let's see a working example of it:

In this example, the total grid width is 700px. Since the
combined widths of the columns in the right column set exceed the total
width allotted to that column set, the content overflows and a scrollbar appears.
Unlike the previous sub-row example, however, in this case only the
content within the right column set scrolls.

As seen in the above example, the most common way to set the width of a
specific column is by using the .field-<fieldname>
CSS class.

Defining Spanned Column Headings with the CompoundColumns Extension

In addition to the standard column structures explained previously, a
more recent addition to the dgrid project is the CompoundColumns extension.
This extension adds the ability to define a column structure which includes
additional spanning header cells above the actual columns in the grid.
It is used the same way as a mixin; the only difference is it lives in the
extensions subfolder since it is a less common feature:

Conclusion

dgrid offers powerful components for efficiently presenting data.
Whether just displaying a few simple columns, or many fields in a
complex structure, dgrid has you covered. This tutorial has provided
simple examples of each of the types of structures dgrid supports. For
more information, see the respective pages of the
dgrid documentation.