Commit cdd56331 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Polish the documentation, mainly the event section.

parent 2110e578
......@@ -19,16 +19,28 @@ An event contains *meta-data* linking the event to:
The events are stored in the ``history`` table and the meta-data in the foreign
tables ``fundings``, ``people``, ``people_categories``, ``projects`` and
``teams``. The organization of these tables can not be modified by the user
since all their fields are standard database field.
since all their fields are standard database fields.
An event contains also the *user data block*. It is stored in one database
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
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
the database. Although it is powerful, there is limitation on that field.
The SQL request are limited to string operations. Individual key of the
dictionary can not be used. However, any key can be manipulated in reports.
An event contains also the *user data block*. It is stored in the database
field ``events.data``. The user data block is a python dictionary serialized as
a JSON_ string.
The structure of the dictionary, *the properties*, are defined by the user,
once, for 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 between
the ``events.data`` and ``history.data`` fields when properties are added,
renamed or destroyed. This is a powerful tool, however there is few
limitations:
* The properties should only contains the characters ``[A-Za-z0_9_]``.
* The SQL request are limited to string operations on the ``events.data`` and
``history.data`` fields.
* Consistency is not preserved between the *user data block* and the *report
configurations*. This operation is left to the user.
* Consistency is not preserved when the property *type* is changed. This
operation is left to the user.
Define an event
----------------
......@@ -40,16 +52,32 @@ possibly a default value. Possible types are *boolean*, *date*, *integer*,
*float*, *reference* and *string*.
.. note::
The reference type allows the user to select value within those
The *reference* type allows the user to select value within those
available for a given database field. The address of the database
field is defined in the *default* column. It is equal to
field is defined in the *value* column. It is equal to
``tablename.fieldname``.
.. note::
For sting, the user can also select the value among a predefined set.
The set is defined in the *default* column. It is equal to a
For string, the user can also select the value among a predefined set.
The set is defined in the *value* column. It is equal to the
JSON_-type array, *e.g* `["foo", "faa"]`.
Dedicated widgets are used for each type to enter value:
.. list-table::
:widths: 30 60
* - text
- string
* - combobox
- boolean, reference, string choose among predefined
set of values
* - up/down spinner
- integer, float
* - date picker drop down
- date
In order to create a new event definition:
1. Open the leaf ``events > definition`` in the left panel of the
......@@ -70,14 +98,25 @@ In order to create a new event definition:
``Modify`` or ``Delete`` using the contextual menu.
.. warning::
Modifying the definiton of the user block is a tricky operation
since consistency with existing events store in the history table
has to be preserved.
Modifying the definition of the user block is a tricky operation
since consistency between ``events.data`` and ``history.data``
has to be preserved, as well as between the ``events.data`` and
the report configurations.
Mechanisms are in place to preserve the consistency when a property
is added, deleted or renamed. However, the user has to take care of
the consistency when the property type as well as the default value
are changed.
.. warning::
Mechanisms are in place to preserve the consistency between the
``events.data`` and ``history.data`` when a property is added,
renamed or deleted.
.. warning::
The consistency is not preserved between the ``events.data`` and the
report configurations. Each configuration has to be checked when
property are destroyed or renamed.
.. warning::
The consistency is not preserved when the property type is changed.
Each entry of the history table, associated to the event, has to be
checked.
Enter an event in the history
......@@ -91,6 +130,8 @@ In order to create a new one:
2. Open the contextual menu in the right panel.
3. Select the menu item ``Add``.
.. _event-form-figure:
.. figure:: figures/history-form.png
:align: center
:width: 50%
......@@ -99,6 +140,20 @@ In order to create a new one:
4. Scan the different tabs and fill the appropriate entries.
The events form, shown in :num:`Fig. #event-form-figure`,
contains three tabs:
``Metadata``
the meta-data associated to the event: *people*, *team*, *project*,
*category*, *funding* and *percentage* allocated for the people.
``Event``
the event type, the time period and the user data block.
``Note``
single input for comments
Make report on events
----------------------
......
# -*- coding: utf-8 -*-
""" events
"""
tp_data = \
T("Define a crude model for the data block associated to each event. "
"The model contains a list of properties. "
"A type is defined to each property or a default value. "
"Valid types are boolean, date, number and string.")
"""
db.define_table("events",
Field("event", "string", length=255, notnull=True, unique=True),
Field("definition", "text"),
Field("data", "json", comment=tp_data, label="Model"),
Field("data", "json", label="Model"),
migrate="events.table")
db.events._before_delete.append(INHIBIT_CASCADE_DELETE)
......
......@@ -5,7 +5,7 @@ HEAD
0.4.1 (Feb 2015)
- Major release non-backward compatible.
- Migrate to plugin_dbui 0.6.2.2 and to python-pandas 0.15.2
- Migrate to plugin_dbui 0.6.2.4 and to python-pandas 0.15.2
- Migrate from sqlite to mariadb.
- Migrate to matplotlib 1.3.1 instead of Ext.chart.
- Add the user data block in the history / events tables
......
......@@ -9,7 +9,7 @@
<a href="/{{=request.application}}/static/docs/sphinx/index.html" target="_blank">
html
</a>,
<a href="/{{=request.application}}/static/docs/pdf/track_events.pdf" target="_blank">
<a href="/{{=request.application}}/static/docs/pdf/{{=request.application}}.pdf" target="_blank">
pdf
</a>)
</li>
......
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