=======
 Grids
=======

A :term:`grid` is essentially a "wrapper" around a table of data.

The :class:`~wuttaweb.grids.base.Grid` class knows how to render
itself as an HTML table with filter, sort and pagination controls.
The latter use AJAX to avoid page reloads as user navigates the data.

A grid can also have arbitrary tools attached, to allow acting on
multiple data records at once etc.

Rendering a grid can actually happen in two different ways, even
though the same class is used to represent both.

On the minimal side, a grid can be rendered as a simple ``<b-table>``
element (from Buefy).

To get the "full experience" the grid can be rendered as a custom
Vue.js component, which adds several features (filter/sort etc.)  in a
wrapper around ``<b-table>``.  Each grid (within one page) must define
a unique component, but ``<wutta-grid>`` is the name used by default
(assuming just one grid on the page).

In the typical scenario, e.g. for a grid which represents a table in
the :term:`app database`, the current sort/filter/paginate settings
are "persisted" in the user's web session.  Therefore when user
returns to the grid page after navigating away, they will see the same
(filtered, sorted) data set they had a moment ago.


Configuration
-------------

The grid can be configured in all supported ways until it is rendered.

The grid constructor accepts most configuration params, in which case
it can be sort of "pre-configured" - but there is no meaningful
difference.  Columns can be added, removed, made sortable or not etc.

Here are some common :class:`~wuttaweb.grids.base.Grid` methods used
for configuration:

* :meth:`~wuttaweb.grids.base.Grid.append()`
* :meth:`~wuttaweb.grids.base.Grid.remove()`
* :meth:`~wuttaweb.grids.base.Grid.set_centered()`
* :meth:`~wuttaweb.grids.base.Grid.set_enum()`
* :meth:`~wuttaweb.grids.base.Grid.set_hidden()`
* :meth:`~wuttaweb.grids.base.Grid.set_label()`
* :meth:`~wuttaweb.grids.base.Grid.set_link()`
* :meth:`~wuttaweb.grids.base.Grid.set_renderer()`
* :meth:`~wuttaweb.grids.base.Grid.set_searchable()`
* :meth:`~wuttaweb.grids.base.Grid.set_joiner()`
* :meth:`~wuttaweb.grids.base.Grid.set_sorter()`
* :meth:`~wuttaweb.grids.base.Grid.set_sort_defaults()`
* :meth:`~wuttaweb.grids.base.Grid.set_filter()`
* :meth:`~wuttaweb.grids.base.Grid.set_filter_defaults()`
* :meth:`~wuttaweb.grids.base.Grid.remove_joiner()`
* :meth:`~wuttaweb.grids.base.Grid.remove_sorter()`
* :meth:`~wuttaweb.grids.base.Grid.remove_filter()`
* :meth:`~wuttaweb.grids.base.Grid.add_action()`
* :meth:`~wuttaweb.grids.base.Grid.add_tool()`
* :meth:`~wuttaweb.grids.base.Grid.set_tools()`

You can also access the :attr:`~wuttaweb.grids.base.Grid.columns`
attribute directly, for more control over the column list.


As ``<b-table>`` Component
--------------------------

Rendering as a simple ``<b-table>`` can be done via the
:meth:`~wuttaweb.grids.base.Grid.render_table_element()`.

For reference, the template for this lives at:

* `wuttaweb/templates/grids/table_element.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/grids/table_element.mako>`_


As ``<wutta-grid>`` Component
-----------------------------

You may be safe to ignore most of this section, but for reference it's
worth knowing where the "main template" for this grid component lives,
so you can look it over if needed:

* `wuttaweb/templates/grids/vue_template.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/grids/vue_template.mako>`_

Rendering as a custom component is a bit different, since we must
ensure the component definition is included, as well as the "element"
within the page body.

As for the latter (e.g. ``<wutta-grid />``), this can be done via the
:meth:`~wuttaweb.grids.base.Grid.render_vue_tag()`.

To render the component definition, use
:meth:`~wuttaweb.grids.base.Grid.render_vue_template()`.

You'll also have to call
:meth:`~wuttaweb.grids.base.Grid.render_vue_finalize()` within the
template's ``make_vue_components()`` block.

All this is something you may rarely need to do in practice, but
examples can be seen in the WuttaWeb source code:

* `wuttaweb/templates/master/index.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/master/index.mako>`_
* `wuttaweb/templates/master/view.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/master/view.mako>`_