103 lines
3.1 KiB
ReStructuredText
103 lines
3.1 KiB
ReStructuredText
|
|
||
|
|
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.
|