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 :class:`~tailbone:tailbone.grids.core.Grid` and most
of the time you'll just use that, with no need to subclass it.

Note that within a :class:`~tailbone:tailbone.views.master.MasterView`
you can get a reference to the ``Grid`` class via
:meth:`~tailbone:tailbone.views.master.MasterView.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.