Grids

A “grid” in Tailbone is just a “displayed table” essentially, but may have other goodies connected with it, e.g. a set of filters and paging info.

The main class is Grid and most of the time you’ll just use that, with no need to subclass it.

Note that within a MasterView you can get a reference to the Grid class via get_grid_factory().

Types of Grids

The Grid class is used for a few different things, as described below. Some of the features mentioned are described in the next section.

Master CRUD w/ DB Table

By far the most common type is that used by the MasterView class, to expose a given data set for searching, downloading etc. Usually the data set is just a DB table, so columns map directly between the table and grid.

This grid usually allows user to specify filters and sorting/paging info.

Master CRUD w/out DB Table

Less common than the above, some MasterView classes need to expose a grid but the data set does not map to a DB table. Examples of this are the Email Settings grid, and the Tables grid.

This grid often does not allow filtering or paging, on account of the relative difficulty to implement (read: author is lazy), but often does allow basic sorting.

Master “Rows” CRUD

Similar to the above, this grid is used by MasterView to show “child row data” when viewing a particular object record.

Like the first, this grid usually allows filter/sort/paging. The one difference in this regard, is the user is not allowed to save default settings for the grid. This is because (per current logic) each grid of this type is unique to the parent object, and settings are kept separate for each such grid. So if settings were saved, they still would not apply to other grids.

Field Data

This type of grid is used to show a small-ish table of data, within a given form field, when viewing a particular object record. For example when viewing a Role, this is how the Users field is displayed.

This grid normally does not allow filters or paging, but in some cases may allow basic sorting.

Grid Features

Here we discuss some possible features a grid may have.

Columns

Obviously a grid has columns. But a grid may also have some “invisible” columns, for sake of the data they contain. This sometimes is needed for other automation etc. in the client-side UI.

TODO: one of these days, grids should let user choose which, and in which order, columns are shown.

Sorting

This is arguably the simplest enhancement to make to a grid. Only a visible column may be sorted, but not all of them. (It depends on the nature of the data set etc.)

Paging

With sorting comes the possibility of paging the grid data. (Sorting is required for paging, so the results are deterministic.)

Filters

Many grids allow the user to apply a set of filters, to limit which data is shown in the grid.