.. include:: hyperlinks.txt

.. _Configure the lists:

Configure the lists
====================

.. _list-figure:

.. figure:: figures/list-example.png
   :align: center
   :width: 60%

   An example of list. The list shows *changelog* events. The rows are grouped
   per year and sorted per date. The first group is collapsed while the second
   one is expanded.

A list is a table in which each column shows the values of one database
field. The table contains heterogeneous values since it merges different types
of database field.

The table is rendered through a grid widget as shown in the
:num:`Fig. #list-figure`. It  provides a lot of flexibility to manipulate
interactively the data. The rows can be grouped per value of a given column. A
group can be expanded or masked. The column can be masked or moved around.
Summary information can be computed for each group as well as
for the whole table. Finally, the data of the table can be extracted in
different formats ``CSV``, ``LaTeX`` or ``PDF``.

The configuration of the list is stored in the database. It defines the mapping
between the field of the source and the column, the group as well as the summary
A source contains a set of database fields as well as the *property* of
the *user data block*.

Dedicated sources contains the active events on a year basis. Therefore,
an event can appear several time when it is active during several years.
In that case, the field ``year`` is also available.

In order to create a ``list``:

    #. Open the leaf ``configure > the lists`` in the left panel of the
       viewport.
    #. Open contextual menu in the right panel.
    #. Select the menu item ``Add``.

        .. _list-form-figure:

        .. figure:: figures/list-form.png
           :align: center
           :width: 50%

           The form to configure a list and to store it in the database.

       The configuration form, shown in :num:`Fig. #list-form-figure`,
       contains five tabs:

            ``General``

                * the name of the list;
                * the title of the list;
                * the event used to generate the list;
                * the *source* of data containing values for database
                  fields as well as those for properties stored in the *user
                  data block* associated to the event. The fields
                  available depend on the source;
                * the definition of the list.

            ``Group``
                the field to group rows as well as the list of
                fields to sort the row of the table.

            ``Transform``

                * It is possible to create colunns from the existing fields,
                  using arithmetic expression;
                * It is possible to apply additonal filter on the source.

            ``Column``

                * the mapping between field of the source and column
                * it is possible to tune how values are displayed
                * the definition of the column is generated automatically for
                  all fields of the source when empty.

            ``Summary``
                the summary information (*count*, *sum*, *median*, *mean*,...)
                compute for each group and/or for the whole column.

Details are given in the next subsections.

Sources
-------

.. include:: sources.txt

Group and sorters
-----------------

The row of the grid can be *grouped* according to the value of a given column.
Once defined, the column containing the group values is masked, as shown in the
:num:`Fig. #list-figure`

In addition, rows of a group can be sorted according to the value of the others
columns.

The group and sorters are defined in the ``Group`` tab through the form entries
``group field`` and ``sorters``. Both contain the name of  a field defined
in the source. Descending order is obtained using the construct ``~field``.

Columns
-------
The configuration of the grid columns is defined in the
``Columns`` tab. It has a single entry which has to be filled with a
JSON_-type ``array`` of object. Each object configures a columns.

The configuration of a column requires a minimum of three properties:

    ``dataindex``
        the name for the field of the source.

    ``text``
        the label of the column.

    ``xtype``
        the type of data stored in the column. Possible values are
        ``booleancolumn``, ``datecolumn``, ``gridcolumn`` and ``numbercolumn``.


The following configuration displays the list of people with
their *FTE* spend during the year:

    .. code:: python

        [{
            "xtype": "rownumbered"
         }, {
            "dataindex": "full_name",
            "text": "Name",
            "xtype": "gridcolumn"
         }, {
            "align": "right",
            "dataindex": "fte",
            "format": "0.00",
            "text": "FTE",
            "xtype": "numbercolumn"
         }, {
            "align": "right",
            "dataindex": "year",
            "text": "Year",
            "xtype": "numbercolumn"
        }]

The first column is peculiar since it display a row number starting at one.

.. note::
    The configuration of all columns for the selected source is generated
    automatically when this field is empty. It can be edited by the user
    latter on.

Summary
-------
A summary can be computed for a columns, *e.g* the number of entry (sum *etc*)
per group or across the whole table.

A summary function has to be defined for the column, in the *column
configuration*, using the property ``summaryType``. Possible values are
``"count"``, ``"sum"``, ``"min"``, ``"max"`` and ``"average"``.

Then, summaries have to be activated using the check-box of the ``Summary`` tab.