Commit 5da13116 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Fill the list section of the user guide.

parent de23ceac
.. _Appendix A:
Appendix A: List of database fields
Appendix A: Database fields
===================================
Events
......
.. _Appendix B:
Appendix B: List of virtual fields
Appendix B: Virtual fields
=======================================
History
......@@ -32,8 +32,10 @@ People
Time axis
---------
The time is not a database table, but the ``year`` can be used as a database
field.
The ``time`` is not as is in the database table since at each event is
associated a time span. However, mechanism has been introduce to extact
the information on a year basis. Therefor the virtual field ``year`` can be
used in the reporting.
.. list-table::
......
.. _JSON: http://www.json.org/
.. _Appendix C:
Appendix C: Column configuration
......@@ -9,12 +11,13 @@ The configuration parameter for the List column are those of the
``Ext.grid.column.Column`` class. The most important one are listed in the next
sections. Those marked with a (*) are mandatory.
The properties and their values have to follow the `JSON
<http://www.json.org>`_ syntax:
The properties and their values have to follow the JSON_ syntax:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of ``string: value`` pair between ``{}``
* ``string`` are surrounded by the double quote, `e.g.` ``"foo"``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
......
.. _Appendix D:
Appendix D: Plot configuration
===================================
Database fields
===============
Addressing database fields
===============================
.. _Fig 1:
.. figure:: ../../database.png
:width: 90%
:align: center
:width: 90%
Overview of the database field.
Figure 1
*Overview of the database fields.*
The fields of the database and their relations are shown in the figure :ref:`Fig 1` and summarized in the :ref:`Appendix A`. The ``history`` and ``people`` table contains also virtual fields. Their values are not stored in the database but computed, on-demand, for each request. Their definitions are given in the :ref:`Appendix B`.
The fields of the database and their relations are shown in the
:ref:`Fig 1` and summarized in the :ref:`Appendix A`. The ``history`` and
``people`` table contains also virtual fields. Their values are not stored in
the database but computed, on-demand, for each request. Their definitions are
given in the :ref:`Appendix B`.
The database fields ``events.data`` and ``history.data`` are very peculiar since they contains a python dictionary encoded as a JSON string. The structure of the dictionary is defined by the user and it depends on the *event*. Reports have to access to any dictionary key. In order to illustrate the addressing of such field, we take the event *CHANGELOG*. The associated dictionary has only one key: ``log``. The address ``history.data.log`` allows to access to its content.
The database fields ``events.data`` and ``history.data`` are very peculiar
since they contains a python dictionary encoded as a JSON string. The structure
of the dictionary is defined by the user and it depends on the *event*. Reports
have to access to any dictionary key. In order to illustrate the addressing of
such field, we take the event *CHANGELOG*. The associated dictionary has only
one key: ``log``. The address ``history.data.log`` allows to access to its
content.
In summary, the addressing of the database fields are::
......
How to configure a graph
======================================
......@@ -3,19 +3,23 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
track_events's documentation
========================================
.. _contents:
Contents:
Documentation contents
======================
.. toctree::
:maxdepth: 2
dbfields
list
metric1d
metric2d
graph
appendixa
appendixb
appendixc
appendixd
Indices and tables
==================
......
How to configure a list
=======================
A list is a table in which each column contains the values of one database field. It is displayed as grid widget as shown in Fig. [fig:An-example-of-list]. The grid provides a lot of flexibility to manipulate interactively the data. For example, rows can be grouped per value of a given column. Columns can be masked and 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. More information can be found in the ExtJS documentation of the [http://docs-origin.sencha.com/extjs/4.2.1/#!/api/Ext.grid.Panel||Ext.grid.Panel] class. The configuration of the list defines the mapping between the database field and the column, the group as well as the summary information. All database fields can be displayed in the list including the virtual fields.
\ No newline at end of file
.. _ExtJS: http://docs-origin.sencha.com/extjs/4.2.1/#!/api
.. _JSON: http://www.json.org/
.. _smart_query: http://web2py.com/books/default/chapter/29/06/the-database-
abstraction-layer#smart_query--experimental
.. _Web2py: http://web2py.com/
.. _Fig 2:
.. figure:: figures/list-example.png
:align: center
:width: 60%
Figure 2
*An example of list in which rows are grouped per year and sorted
by institutes, people categories and name. The first group is expanded while
the second one is collapsed.*
A list is a table in which each column shows the values of one database
field. The table contains heterogeneous values since the type a of the
column is the one of the database field. The table is rendered through a grid
widget has shown in the :ref:`Fig 2`.
The grid 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``. More information can be found
in the ExtJS_ documentation of the ``Ext.grid.Panel``.
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
virtual fields, one key of the history.data dictionary or the ``year``.
In order to create a ``list``:
#. open the leaf ``configure > the lists`` in the left panel of the
viewport.
#. right click anywhere in the right panel
#. select the menu item ``Add``
.. _Fig 3:
.. figure:: figures/list-form.png
:align: center
:width: 50%
Figure 3
the configuration form, shown in :ref:`Fig 3`, contains four tabs:
.. list-table::
:widths: 10 70
* - ``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
and for the whole column.
Details are given in the next subsections.
Filter conditions
-----------------
The fitler conditions is defined in the ``General`` tab.
The ``Conditions`` are used to select a sub-sample of the history records. It
is based on the smart_query_ available in the Web2py_ framework. The query
is written in the natural language, but it is limited to field of the
history table. Fields of the foreign tables, virtual fields or keys of the
``history.data`` dictionary can not be used.
The ``changelog`` event introduced earlier has the ``id`` equal to 7. To
select history related changelog events, enter::
history.id_events = 7
The operator ``contain``, ``greater then``, ... as well as the logical operator
``and``, ``or`` can be used.
Group and sorters
-----------------
The group and sorters are defined in the ``Group`` tab through the form entries
``group field`` and ``sorters``. Both contain the address of database field,
virtual field or key of the ``history.data`` dictionary.
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. An example is shown in :ref:`Fig 2`.
In addition, rows of a group can be sorted according to the value of the others
columns.
Columns
-------
The configuration of the grid columns is defined in the
``Columns`` tab. It has a single entry which has to be filled with an
``array`` of object. Each object configures a columns.
The language used is JSON_ in which:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
The configuration of a column requires a minimum of two properties:
.. list-table::
:widths: 10 70
* - ``dbfield``
- the address of the database field
* - ``text``
- the label of the column
This minimal configuration will render the value as a string.
Many more properties are available. They are detailed in :ref:`Appendix C`.
The following configuration displays the list of people with their current age::
[{
"xtype": "rownumbered"
}, {
"dbfield": "people.last_name",
"text": "name"
}, {
"align": "right",
"dbfield": "history.age",
"format": "0",
"text": "age",
"xtype": "numbercolumn"
}]
The first column is peculiar since it display a row number starting at 1 as for
a spread sheet.
Summary
-------
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
``array`` of object. The language used is JSON_ in which:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
For a given column, a summary can be computed over the value of a group and /
or over the values of the whole column.
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::
[{
"ftype":"groupingsummary",
"groupHeaderTpl": "{name}",
"startCollapsed": false
}, {
"ftype":"summary"
}]
The first object activated the summary for each group and the second one for
the whole column.
More information on the grouping features can be found in the
``Ext.grid.features`` section of the ExtJS_ documentation.
How to configure a 1-dimension metric
=====================================
Filter conditions
-----------------
Group
-----
Columns
-------
How to configure a 2-dimension metric
======================================
Filter conditions
-----------------
Aggregate
---------
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment