Commit 53810cab authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Polish the user guide.

parent 3532c472
...@@ -5,18 +5,62 @@ ...@@ -5,18 +5,62 @@
Appendix C: Column configuration Appendix C: Column configuration
=================================== ===================================
List Lists and 1-dim Metrics display a collection of columns.
---- The configuration properties of the columns are those of the
The configuration parameter for the List column are those of the ``Ext.grid.column.Column`` class. More information can be found in the ExtJS_
``Ext.grid.column.Column`` class. The most important one are listed in the next documentation.
sections. Those marked with a (*) are mandatory.
The column is by default configured to render string. It is possible to handle
``boolean``, ``date`` and ``number`` values by changing the ``xtype`` property.
The mapping between the database field and the column types is the following:
================ =================
Database ``xtype``
================ =================
boolean ``booleancolumn``
date / datetime ``datecolumn``
integer / float ``numbercolumn``
string (default) ``gridcolumn``
================ =================
A column contains the value of the given database field. In that first case,
the mandatory properties depend on the report and are the following:
=============== ===============
List Metric1D
=============== ===============
-- ``aggregate``
``dbfield`` ``dbfield``
``text`` ``text``
=============== ===============
A column can also contains computed values obtained by applying a mathematical
expression on the cells of the other columns. In that second case, the mandatory
property are the following and do not depend on the report:
The properties and their values have to follow the JSON_ syntax: .. list-table::
* - **Computed column**
* - ``eval``
* - ``text``
The most important properties are defined in the next sections as a function of
the column type.
.. note::
.. include:: json.txt The ``Metric1D`` columns are always rendered as ``numbercolumn``.
Therefore the property ``xtype`` can be omitted.
all columns Finally, the ExtJS_ library provide a special column numbering the rows
^^^^^^^^^^^ starting at one. It has only one configuration property:
.. code:: javascript
"xtype" : "rownumberer"
All columns
-----------
``align`` ``align``
the alignment of the column. the alignment of the column.
...@@ -25,123 +69,68 @@ all columns ...@@ -25,123 +69,68 @@ all columns
``columnWidth`` or ``flex`` ``columnWidth`` or ``flex``
the column width can be specified as a number or a percentage. the column width can be specified as a number or a percentage.
``dbfield`` (*) ``dataIndex``
the index of the column used by the ``DataFrame``, the ``Ext.data.store``
and the ``Ext.grid.Panel``. By default, this internal parameter is equal
to the ``text`` property. However, when using the ``eval`` property, it
could be useful to index the column with short name like *a*, *b*, ...
``dbfield``
the address of the database field encoded as ``"tablename.fieldname"`` or the address of the database field encoded as ``"tablename.fieldname"`` or
``"tablename.fieldname.keyname"``. ``"tablename.fieldname.keyname"``.
.. warning:: .. warning::
Do not use with the ``rownumberer`` column. Do not use with the ``eval`` property.
``eval``
the string defining the mathematical operation applied between column cells,
*e.g* ``(a+b*2)/c`` where *a*, *b* and *c* are column indexes.
.. warning::
Do not use the ``dbfield`` and ``aggregate`` properties.
``hidden`` ``hidden``
the column is hidden when it is ``true``. the column is hidden when it is ``true``.
``renderer`` ``renderer``
A string pointing to the javascript function rendering the value or A string pointing to the javascript function rendering the value or
containing the function itself. containing the function itself. The possible value is ``reprDuration``.
``text`` (*) ``text``
the string containing the label of the column. the string containing the label of the column.
``xtype`` (*) ``xtype``
the string specifying the type of the column. the string specifying the type of the column.
The mapping between the type of the column and the one of the database field
is the following:
.. list-table::
* - ``booleancolumn``
- boolean
* - ``datecolumn``
- date or datetime
* - ``numbercolumn``
- integer or float
* - ``gridcolumn``
- string (default)
booleancolumn Boolean column
^^^^^^^^^^^^^ --------------
``falseText`` ``falseText``
the string return in the grid when the value is false. the string returns in the grid when the value is false.
``trueText`` ``trueText``
the string return in the grid when the value is true. the string returns in the grid when the value is true.
datecolumn Date column
^^^^^^^^^^ -----------
``format``
the format string, e.g. ``"d/m/Y"``.
numbercolumn
^^^^^^^^^^^^
``format`` ``format``
the format string, e.g. ``"0,000.00"``. the format string, *e.g.* ``"d/m/Y"``.
``summaryType`` Number column
Summary over column values are computed. -------------
Possible values are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` and
``"average"``.
Metric 1D
---------
The configuration parameters for the Metric1D column is similar to
those of the ``numbercolumn`` since the table only contains number. Therefore
it is not required to specify the column type.
all column
^^^^^^^^^^
``align`` ``aggregate``
the alignment of the column. the aggregation function uses by the 1-dim metric.
Possible values are: ``"left"``, ``"center"``, and ``"right"``. Many functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``, *etc*. In fact, all the
``columnWidth`` or ``flex`` descriptive stats methods of the DataFrame_ class.
the column width can be specified as a number or a percentage.
``format`` ``format``
the format string, e.g. ``"0,000.00"``. the format string, *e.g.* ``"0,000.00"``.
``hidden``
the column is hidden when it is ``true``.
``renderer``
the string pointing to the javascript function rendering the value or
containing the function itself.
``text`` (*)
the label of the column.
``summaryType`` ``summaryType``
the summary over column values are computed. Summary are computed over the column values.
Possible values are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` Possible functions are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` and
and ``"average"``. ``"average"``.
``dataIndex``
the index of the column used by the ``DataFrame``, the ``Ext.data.store``
and the ``Ext.grid.Panel``. By default, this internal parameter is equal
to the ``text`` property. However, when using the ``eval`` property, it
could be useful to index the column with short name like *a*, *b*, ...
database field column
^^^^^^^^^^^^^^^^^^^^^
``aggregate`` (*)
Many aggregation functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``... In fact, all the
descriptive stats methods of the DataFrame_ class.
``dbfield`` (*)
the address of the database field encoded as ``"tablename.fieldname"`` or
``"tablename.fieldname.keyname"``.
computed column
^^^^^^^^^^^^^^^
``eval`` (*)
the string defining the mathematical operation applied between column cells,
*e.g* ``(a+b*2)/c`` where *a*, *b* and *c* are column indexes.
.. warning::
Do not use the ``dbfield`` and ``aggregate`` properties.
...@@ -59,10 +59,9 @@ The basic keywords ...@@ -59,10 +59,9 @@ The basic keywords
deactivate grid (legend) when it is ``false``. deactivate grid (legend) when it is ``false``.
``colormap`` ``colormap``
set the colormap indentify by its name. set the matplotlib.colormap_ identify by its name.
Possible values in http://matplotlib.org/users/colormaps.html
``xerr`` and ``yerr``. ``xerr`` and ``yerr``
set errors bars. set errors bars.
``index``, ``x`` and ``y`` ``index``, ``x`` and ``y``
...@@ -82,7 +81,8 @@ The basic keywords ...@@ -82,7 +81,8 @@ The basic keywords
set the label along the *x* and *y*-axis respectively set the label along the *x* and *y*-axis respectively
``tranpose`` ``tranpose``
boolean value to exchange *x* and *y*-axis. boolean value to exchange *index* and *column* using the method
``DataFrame.T``.
Column addressing Column addressing
...@@ -104,10 +104,3 @@ in columns. In order to: ...@@ -104,10 +104,3 @@ in columns. In order to:
* a stacked histogram/bar with the reduced set of columns, use the list:: * a stacked histogram/bar with the reduced set of columns, use the list::
index = [column labels, or positions] index = [column labels, or positions]
.. note::
The column label is derived from the database field address by removing
the dot, *e.g* ``tablenamefieldname``.
.. note::
The column label can also be equal to column values.
\ No newline at end of file
...@@ -8,8 +8,10 @@ Appendix B: Virtual fields ...@@ -8,8 +8,10 @@ Appendix B: Virtual fields
History History
------- -------
.. tabularcolumns:: |l|l|p{9cm}|
.. list-table:: .. list-table::
:widths: 20 10 50 :widths: 30 10 60
* - * -
- -
...@@ -17,7 +19,7 @@ History ...@@ -17,7 +19,7 @@ History
* - ``history.coverage`` * - ``history.coverage``
- float - float
- the time coverage of the history record with respect - the time coverage of the history record with respect
to the period range selected by the user. It is a value between 0 and 1. to the period selected by the user. It is a value between 0 and 1.
* - ``history.duration`` * - ``history.duration``
- float - float
- the duration of the history record. The end date is ``now`` when - the duration of the history record. The end date is ``now`` when
...@@ -29,14 +31,14 @@ History ...@@ -29,14 +31,14 @@ History
person assigned to the record. It is a value between 0 and 1. person assigned to the record. It is a value between 0 and 1.
* - ``history.is_end`` * - ``history.is_end``
- boolean - boolean
- Return true is the history record ends during the period range selected - Return true is the history record ends during the period selected
by the user. by the user.
* - ``history.is_over`` * - ``history.is_over``
- boolean - boolean
- Return true is the history record is over ``now``. - Return true is the history record is over ``now``.
* - ``history.is_start`` * - ``history.is_start``
- boolean - boolean
- Return true is the history record starts during the period range - Return true is the history record starts during the period
selected by the user. selected by the user.
People People
...@@ -56,7 +58,7 @@ Time axis ...@@ -56,7 +58,7 @@ Time axis
--------- ---------
The ``time`` is not a field of the ``history`` table since a time period is The ``time`` is not a field of the ``history`` table since a time period is
associated to each event. However, mechanism has been introduce to extract the associated to each event. However, mechanism has been introduced to extract the
database information on a year basis. Therefore the pseudo field ``year`` can database information on a year basis. Therefore the pseudo field ``year`` can
be used in the reporting. be used in the reporting.
......
...@@ -5,14 +5,17 @@ The fitler conditions is defined in the ``General`` tab. ...@@ -5,14 +5,17 @@ The fitler conditions is defined in the ``General`` tab.
The ``Conditions`` are used to select a sub-sample of the history records. It 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 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 is written in the natural language, but it is limited to field of the
history table. Foreign tables fields, virtual fields or keys of the history table.
``history.data`` dictionary can not be used.
The ``changelog`` event introduced earlier has the ``id`` equal to 7. To .. warning::
select history related changelog events, enter:
Do not use foreign fields, virtual fields, keys of the
``history.data`` dictionary as well as the pseudo field year.
Example of smart query:
.. code:: .. code::
history.id_events = 7 history.id_events = 7 and id_people_categories not in 1,11,13,14
Possible operators are given :ref:`Appendix E`. Possible operators are given :ref:`Appendix E`.
...@@ -44,7 +44,8 @@ source_suffix = '.rst' ...@@ -44,7 +44,8 @@ source_suffix = '.rst'
master_doc = 'index' master_doc = 'index'
# General information about the project. # General information about the project.
project = u'track_events' app = unicode(os.getcwd().split(os.sep)[-3])
project = app
copyright = u'2015, R. Le Gac' copyright = u'2015, R. Le Gac'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
...@@ -177,7 +178,7 @@ html_static_path = ['_static'] ...@@ -177,7 +178,7 @@ html_static_path = ['_static']
#html_file_suffix = None #html_file_suffix = None
# Output file base name for HTML help builder. # Output file base name for HTML help builder.
htmlhelp_basename = 'track_eventsdoc' htmlhelp_basename = '%sdoc' % app
# -- Options for LaTeX output -------------------------------------------------- # -- Options for LaTeX output --------------------------------------------------
...@@ -196,7 +197,7 @@ latex_elements = { ...@@ -196,7 +197,7 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]). # (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'track_events.tex', u'track\\_events Documentation', ('index', '%s.tex' % app, u'%s documentation' % app.replace('_', '\\_'),
u'R. Le Gac', 'manual'), u'R. Le Gac', 'manual'),
] ]
...@@ -226,7 +227,7 @@ latex_use_parts = False ...@@ -226,7 +227,7 @@ latex_use_parts = False
# One entry per manual page. List of tuples # One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section). # (source start file, name, description, authors, manual section).
man_pages = [ man_pages = [
('index', 'track_events', u'track_events Documentation', ('index', str(app) , u'%s Documentation' % app,
[u'R. Le Gac'], 1) [u'R. Le Gac'], 1)
] ]
...@@ -240,8 +241,8 @@ man_pages = [ ...@@ -240,8 +241,8 @@ man_pages = [
# (source start file, target name, title, author, # (source start file, target name, title, author,
# dir menu entry, description, category) # dir menu entry, description, category)
texinfo_documents = [ texinfo_documents = [
('index', 'track_events', u'track_events Documentation', ('index', str(app), u'%s Documentation' % app,
u'R. Le Gac', 'track_events', 'One line description of project.', u'R. Le Gac', str(app), 'One line description of project.',
'Miscellaneous'), 'Miscellaneous'),
] ]
......
...@@ -9,21 +9,24 @@ Addressing database fields ...@@ -9,21 +9,24 @@ Addressing database fields
:align: center :align: center
:width: 90% :width: 90%
The database scheme. The database scheme. Events are stored in the history and linked tables.
The remaining tables store the configurations for the report objects.
The fields of the database and their relations are shown in the The fields of the database and their relations are shown in the
:num:`Fig. #database-figure` and summarized in the :ref:`Appendix A`. The :num:`Fig. #database-figure` and summarized in the :ref:`Appendix A`.
``history`` and
``people`` table contains also virtual fields. Their values are not stored in The ``history`` and ``people`` table contains also virtual fields. Their values
the database but computed, on-demand, for each request. Their definitions are are not stored in the database but computed, on-demand, for each request and
given in the :ref:`Appendix B`. can be used in reports. Their definitions are given in the :ref:`Appendix B`.
Basic field type Basic field type
---------------- ----------------
The basic field contains ``blob``, ``boolean``, ``date``, ``datetime``, The basic field contains ``blob``, ``boolean``, ``date``, ``datetime``,
``double``, ``float``, ``integer``, ``string``, ``text`` and ``time`` values. ``double``, ``float``, ``integer``, ``string``, ``text`` and ``time`` values.
The addressing of these field follows the usual rules:: The addressing of these field follows the usual rules:
.. code:: python
tablename.fieldname tablename.fieldname
...@@ -35,7 +38,9 @@ JSON_ serializable object. It is used to store python dictionary in the ...@@ -35,7 +38,9 @@ JSON_ serializable object. It is used to store python dictionary in the
``events.data`` and ``history.data`` fields. ``events.data`` and ``history.data`` fields.
Reports have to access to any dictionary key. In that case, the address is Reports have to access to any dictionary key. In that case, the address is
given by:: given by:
.. code:: python
tablename.fieldname.keyname tablename.fieldname.keyname
...@@ -46,6 +51,8 @@ An event spans over a period of time defined by the *history.start_date* and ...@@ -46,6 +51,8 @@ An event spans over a period of time defined by the *history.start_date* and
*history.end_date* fields. This period can cover several years. Although the *history.end_date* fields. This period can cover several years. Although the
year is not a field of the ``history`` table, a mechanism has been introduced to year is not a field of the ``history`` table, a mechanism has been introduced to
sample the database information on a year basis. It is activated via the sample the database information on a year basis. It is activated via the
address of the pseudo field:: address of the pseudo field:
.. code:: python
year year
\ No newline at end of file
...@@ -4,47 +4,44 @@ Events ...@@ -4,47 +4,44 @@ Events
======= =======
This applications record events. It can happen at a date or span during a This applications record events. It can happen at a date or span during a
period of time. An event is the relation between a person and a team / period of time.
project. When he/she arrive, left. How many time does he/she spent. It can also
be an entry in a changelog. Why and when the content of the database has been
modified. In fact, there are no limitation on the events which can be tracked.
An event is defined by a *starting date*, by an *ending date* and by a *name*. An event is defined by a *starting date*, by an *ending date* and by a *type*.
An event contains *meta-data* linking the event to: An event contains *meta-data* linking the event to:
* a person * a person
* a teams * a team
* a project * a project
* a category (the category of people in this application) * a category (the category of people in this application)
* a funding agency * a funding agency
The event are stored in the ``history`` table and the meta-data in the foreign The events are stored in the ``history`` table and the meta-data in the foreign
tables ``fundings``, ``people``, ``people_categories``, ``projects`` and tables ``fundings``, ``people``, ``people_categories``, ``projects`` and
``teams``. The organization of the table can not be changed. All the fields of ``teams``. The organization of the table can not be changed. All the fields of
these tables are standard database field. They can be used in standard SQL these tables are standard database field which can be used in SQL request or in
request or in reports. reports.
An event contains also a *user data block*. It is stored in one database field. An event contains also the *user data block*. It is stored in one database
The user data block is a python dictionary serialized as a JSON_ string. field. The user data block is a python dictionary serialized as a JSON_ string.
The structure of the dictionary, *the keys*, are defined by the user, once, for The structure of the dictionary, *the keys*, are defined by the user, once, for
each event type. The structure of the dictionary can be modified at any each event type. The structure of the dictionary can be modified at any
time by the user. Mechanisms are in placed to guaranty the consistency across time by the user. Mechanisms are in placed to guaranty the consistency across
the database. The SQL Request are limited to string operations. the database. The SQL request are limited to string operations.
Individual key of the dictionary can not be used. But, any key can be used in Individual key of the dictionary can not be used in SQL request. But, any key
reports. can be manipulated in reports.
How to define an event Define an event
---------------------- ----------------
The event definitions are stored in the ``events`` table. The event definitions are stored in the ``events`` table.
In order to create a new event definition: In order to create a new event definition:
1. open the leaf ``events > definition`` in the left panel of the 1. Open the leaf ``events > definition`` in the left panel of the
viewport. viewport.
2. right click anywhere in the right panel 2. Open the contextual menu in the right panel.
3. select the menu item ``Add`` 3. Select the menu item ``Add``.
.. figure:: figures/event-form.png .. figure:: figures/event-form.png
:align: center :align: center
...@@ -52,29 +49,29 @@ In order to create a new event definition: ...@@ -52,29 +49,29 @@ In order to create a new event definition:
The form to enter an event definition in the database. The form to enter an event definition in the database.
4. Enter the event name in the ``event`` entry.