list.rst 5.32 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.

22
The table is rendered through a grid widget has 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 31 32

The configuration of the list is stored in the database. It defines the mapping
between the database field and the column, the group as well as the summary
information. Any database field can be displayed in the column including the
LE GAC Renaud's avatar
LE GAC Renaud committed
33 34
virtual fields, keys of the ``history.data`` dictionary as well as the
pseudo field ``year``.
35 36 37

In order to create a ``list``:

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

43
        .. _list-form-figure:
44

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

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

51 52
       The configuration form, shown in :num:`Fig. #list-form-figure`,
       contains four tabs:
53

54 55 56 57 58 59 60 61 62 63 64 65 66 67
            ``General``
                the name of the list, the title of the report and the conditions
                to select ``history`` records.

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

            ``Column``
                the mapping between database field and column as well as how
                the values are displayed.

            ``Summary``
                the summary information compute for each group
68
                and for the whole column.
69

70
Details are given in the next subsections.
71 72 73 74

Filter conditions
-----------------

75
.. include:: conditions.txt
76 77 78 79

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

80
The group and sorters are defined in the ``Group`` tab through the form entries
81
``group field`` and ``sorters``. Both contain the address of database field,
LE GAC Renaud's avatar
LE GAC Renaud committed
82 83
virtual field, keys of the ``history.data`` dictionary or the pseudo
field ``year``.
84

85 86 87 88
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 but and
additional row is created with the group value, followed by all the rows with
the same group value.
89

90
In addition, rows of a group can be sorted according to the value of the others
91 92 93 94
columns.

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

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

101
    ``dbfield``
LE GAC Renaud's avatar
LE GAC Renaud committed
102
        the address of the database field.
103

104
    ``text``
LE GAC Renaud's avatar
LE GAC Renaud committed
105
        the label of the column.
106

LE GAC Renaud's avatar
LE GAC Renaud committed
107 108 109 110 111 112 113 114 115
    ``xtype``
        the type of data stored in the column. Possible values are
        ``booleancolumn``, ``datecolumn``, ``gridcolumn`` and ``numbercolumn``.

To add column containing the result of mathematical operation applied on
column cells, use the properties ``eval`` instead of ``dbfield``. In that case
the property ``dataIndex`` has to be specified.

Many more details are given in :ref:`Appendix C`.
116

117
The following configuration displays the list of people with their current age:
118

119
    .. code:: python
120

121 122 123 124
        [{
            "xtype": "rownumbered"
         }, {
            "dbfield": "people.last_name",
LE GAC Renaud's avatar
LE GAC Renaud committed
125 126
            "text": "name",
            "xtype": "gridcolumn"
127 128 129 130 131 132 133
         }, {
            "align": "right",
            "dbfield": "history.age",
            "format": "0",
            "text": "age",
            "xtype": "numbercolumn"
        }]
134

LE GAC Renaud's avatar
LE GAC Renaud committed
135
The first column is peculiar since it display a row number starting at one.
136 137 138

Summary
-------
139 140
The configuration of the summary per columns is defined in the
``Summary`` tab. It has a single entry which has to be filled with an
LE GAC Renaud's avatar
LE GAC Renaud committed
141
JSON_-type ``array`` of object.
142 143

For a given column, a summary can be computed over the value of a group and /
144 145
or over the values of the whole column.

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

150 151 152
Then, summaries have to be activated:

    .. code:: python
153

154 155 156 157 158 159 160
        [{
            "ftype":"groupingsummary",
            "groupHeaderTpl": "{name}",
            "startCollapsed": false
         }, {
            "ftype":"summary"
        }]
161 162

The first object activated the summary for each group and the second one for
163 164
the whole column.

165
More information on the grouping features can be found in the
166
``Ext.grid.features`` section of the ExtJS_ documentation.