list.rst 5.59 KB
Newer Older
1 2
.. include:: hyperlinks.txt

LE GAC Renaud's avatar
LE GAC Renaud committed
3 4 5 6
.. _Configure the lists:

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

8
.. _list-figure:
9 10 11 12 13

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

LE GAC Renaud's avatar
LE GAC Renaud committed
14 15 16
   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.
17

18 19 20 21
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.

LE GAC Renaud's avatar
LE GAC Renaud committed
22
The table is rendered through a grid widget as shown in the
LE GAC Renaud's avatar
LE GAC Renaud committed
23 24 25 26
: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
27
for the whole table. Finally, the data of the table can be extracted in
LE GAC Renaud's avatar
LE GAC Renaud committed
28
different formats ``CSV``, ``LaTeX`` or ``PDF``.
29 30

The configuration of the list is stored in the database. It defines the mapping
LE GAC Renaud's avatar
LE GAC Renaud committed
31 32 33 34 35 36 37
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.
38 39 40

In order to create a ``list``:

LE GAC Renaud's avatar
LE GAC Renaud committed
41
    #. Open the leaf ``configure > the lists`` in the left panel of the
42
       viewport.
LE GAC Renaud's avatar
LE GAC Renaud committed
43 44
    #. Open contextual menu in the right panel.
    #. Select the menu item ``Add``.
45

46
        .. _list-form-figure:
47

48 49
        .. figure:: figures/list-form.png
           :align: center
LE GAC Renaud's avatar
LE GAC Renaud committed
50
           :width: 50%
51

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

54
       The configuration form, shown in :num:`Fig. #list-form-figure`,
LE GAC Renaud's avatar
LE GAC Renaud committed
55
       contains five tabs:
56

57
            ``General``
LE GAC Renaud's avatar
LE GAC Renaud committed
58 59 60 61 62 63 64 65 66

                * 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.
67 68

            ``Group``
LE GAC Renaud's avatar
LE GAC Renaud committed
69 70 71 72 73 74 75 76
                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.
77 78

            ``Column``
LE GAC Renaud's avatar
LE GAC Renaud committed
79 80 81 82 83

                * 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.
84 85

            ``Summary``
LE GAC Renaud's avatar
LE GAC Renaud committed
86 87
                the summary information (*count*, *sum*, *median*, *mean*,...)
                compute for each group and/or for the whole column.
88

89
Details are given in the next subsections.
90

LE GAC Renaud's avatar
LE GAC Renaud committed
91 92
Sources
-------
93

LE GAC Renaud's avatar
LE GAC Renaud committed
94
.. include:: sources.txt
95 96 97 98

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

99
The row of the grid can be *grouped* according to the value of a given column.
LE GAC Renaud's avatar
LE GAC Renaud committed
100 101
Once defined, the column containing the group values is masked, as shown in the
:num:`Fig. #list-figure`
102

103
In addition, rows of a group can be sorted according to the value of the others
LE GAC Renaud's avatar
LE GAC Renaud committed
104 105 106 107 108
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``.
109 110 111

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

LE GAC Renaud's avatar
LE GAC Renaud committed
116
The configuration of a column requires a minimum of three properties:
117

LE GAC Renaud's avatar
LE GAC Renaud committed
118 119
    ``dataindex``
        the name for the field of the source.
120

121
    ``text``
LE GAC Renaud's avatar
LE GAC Renaud committed
122
        the label of the column.
123

LE GAC Renaud's avatar
LE GAC Renaud committed
124 125 126 127
    ``xtype``
        the type of data stored in the column. Possible values are
        ``booleancolumn``, ``datecolumn``, ``gridcolumn`` and ``numbercolumn``.

128

LE GAC Renaud's avatar
LE GAC Renaud committed
129 130
The following configuration displays the list of people with
their *FTE* spend during the year:
131

132
    .. code:: python
133

134 135 136
        [{
            "xtype": "rownumbered"
         }, {
LE GAC Renaud's avatar
LE GAC Renaud committed
137 138
            "dataindex": "full_name",
            "text": "Name",
LE GAC Renaud's avatar
LE GAC Renaud committed
139
            "xtype": "gridcolumn"
140 141
         }, {
            "align": "right",
LE GAC Renaud's avatar
LE GAC Renaud committed
142 143 144 145 146 147 148 149
            "dataindex": "fte",
            "format": "0.00",
            "text": "FTE",
            "xtype": "numbercolumn"
         }, {
            "align": "right",
            "dataindex": "year",
            "text": "Year",
150 151
            "xtype": "numbercolumn"
        }]
152

LE GAC Renaud's avatar
LE GAC Renaud committed
153
The first column is peculiar since it display a row number starting at one.
154

LE GAC Renaud's avatar
LE GAC Renaud committed
155 156 157 158 159
.. 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.

160 161
Summary
-------
LE GAC Renaud's avatar
LE GAC Renaud committed
162 163
A summary can be computed for a columns, *e.g* the number of entry (sum *etc*)
per group or across the whole table.
164

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

LE GAC Renaud's avatar
LE GAC Renaud committed
169
Then, summaries have to be activated using the check-box of the ``Summary`` tab.