Commit f19fad95 authored by legac's avatar legac
Browse files

Fix list.

parent ccd4a235
......@@ -53,56 +53,48 @@ class DbSvc(BaseSvc):
The main methods allow to:
- ``create`` a new record in a table.
- ``read`` the content of a a table
resolving foreign key.
- ``update`` the record of a table.
- ``destroy`` the record of a table.
* ``create`` a new record in a table.
* ``read`` the content of a a table resolving foreign key.
* ``update`` the record of a table.
* ``destroy`` the record of a table.
These methods receive transaction data dictionary, ``arg``:
.. _input transaction dictionary:
These methods receive the *transaction data dictionary*, ``arg``:
- ``tableName``
the name of the table in the database
- ``dbFields``
* ``tableName`` the name of the table in the database
- ``[["table1", "field1"], ... ]``
- The list of database fields of the table.
- Include foreign keys and reference fields.
* ``dbFields`` The list of database fields of the table,
``[["table1", "field1"], ... ]`` including foreign keys
and reference fields.
- ``records`` (optional)
- ``[{"Table1Field1": val1,...}]``
- A list of dictionaries containing key, value pairs for fields
to be created or updated
* ``records`` (optional) A list of dictionaries containing key,
value pairs for fields to be created or updated,
``[{"Table1Field1": val1,...}]`` including foreign key and
reference field values. Each dictionary also contains
the ``id`` of the record to be updated.
- Includes foreign key and reference field values.
- Contains the ``id`` of the record to be updated.
- The keys are encoded as ``Table1Field1``.
The keys are encoded as ``Table1Field1``.
- The ``records`` can also be a list containing the ``id`` of the
records to be deleted.
The ``records`` can also be a list containing the ``id`` of the
records to be deleted.
Each method return a dictionary:
- ``{success: True, records:[{blabla}, ..], msg: 'blalbla'}``
.. _output transaction dictionary:
Each method return the dictionary::
{success: True, records:[{blabla}, ..], msg: 'blalbla'}
- The keyword ``success`` is always present. It is mandatory for
the ``FormPanel`` widget of the Ext JS library, but not strictly
required since failure can be propagated through HTTP errors.
- In the records dictionary database field are encoded as ``TableField``.
* The keyword ``success`` is always present. It is mandatory for
the ``FormPanel`` widget of the Ext JS library, but not strictly
required since failure can be propagated through HTTP errors.
* The keys of the ``record`` dictionary are the database fields
encoded as ``TableField``.
- If the action failed the ``DbSvcException`` is raised.
The exception can be catch to generate an HTTP error.
The ``DbSvcException`` is raised when the action failed.
It can be caught to generate an HTTP error.
"""
......@@ -111,35 +103,7 @@ class DbSvc(BaseSvc):
contains the ``keywords``.
:type arg: dict
:param arg:
transaction data
- ``tableName``
the name of the table in the database
- ``dbFields``
- ``[["table1", "field1"], ... ]``
- The list of database fields of the table.
- Include foreign keys and reference fields.
- ``records`` (optional)
- ``[{"Table1Field1": val1,...}]``
- A list of dictionaries containing key, value pairs for fields
to be created or updated
- Includes foreign key and reference field values.
- Contains the ``id`` of the record to be updated.
- The keys are encoded as ``Table1Field1``.
- The ``records`` can also be a list containing the ``id`` of the
records to be deleted.
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
:type keywords: dict
......@@ -177,10 +141,11 @@ class DbSvc(BaseSvc):
"([table1.field1] == [table2.field2]) | ([table1.field2] == [table2.field1])"
:returns:
tuple of gluon.dal.Query --:
- the first element is the full query with all conditions or an empty string.
- the second element contains only the left join conditions or an empty string.
- the third element contains only the filter conditions or an empty string.
tuple of gluon.dal.Query
* the first element is the full query with all conditions or an empty string.
* the second element contains only the left join conditions or an empty string.
* the third element contains only the filter conditions or an empty string.
:note: All elements of the list are ANDED in the web2py query
......@@ -341,46 +306,21 @@ class DbSvc(BaseSvc):
The method also validates each value.
:type arg: dict
:param arg:
transaction data
- ``tableName``
the name of the table in the database
- ``dbFields``
- ``[["table1", "field1"], ... ]``
- The list of database fields of the table.
- Include foreign keys and reference fields.
- ``records``
- ``[{"Table1Field1": val1,...}]``
- A list of dictionaries containing key, value pairs for fields
to be created or updated
- Includes foreign key and reference field values.
- Contains the ``id`` of the record to be updated.
- The keys are encoded as ``Table1Field1``.
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
gluon.storage.Storage
- ``Storage(errors=[], records=[])``
* ``Storage(errors=[], records=[])``
- One to one correspondence between the errors
* One to one correspondence between the errors
and the records lists
- ``records`` is a list of dictionaries containing key value pairs
* ``records`` is a list of dictionaries containing key value pairs
where the key corresponds to a database field.
The keys are encoded as ``Table1Field1``.
- The ``error`` is ``None`` when the ``record`` is validated.
* The ``error`` is ``None`` when the ``record`` is validated.
Otherwise the error is a dictionary
``{Table1Field1: "error message", ...}``
......@@ -430,51 +370,17 @@ class DbSvc(BaseSvc):
Several transactions of the same type are processed together.
:type arg: dict
:param arg:
transaction data
- ``tableName``
the name of the tablename in the database
- ``dbFields``
- ``[["table1", "field1"], ... ]``
- The list of database fields of the tablename.
- Include foreign keys and reference fields.
- ``records``
- ``[{"Table1Field1": val1,...}]``
- A list of dictionaries containing key, value pairs for fields
to be created.
- Includes foreign key and reference field values.
- The keys are encoded as ``Table1Field1``.
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
dict
- ``{success: True, records:[{Table1Field1: val, ... }, ... ],
msg: 'blalbla'}``
- ``records`` is a list of dictionary containing the complete
key, value pairs for the ``record`` created in the database.
- The record keys are encoded as ``Table1Field1``.
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
- ``{success: False, records:[{Table1Field1: val, ... }, ... ],
errors: 'blabla', }``
when at least a field value is not validated or when the transaction
is kill by the callback ``table._before_insert``.
The full transaction is aborted.
The errors contains the error message return by callback or
a dictionary returns by the validator. The key is the field
identifier encoded as ``Table1Field1`` while the value is
the error message.
The full transaction is aborted when at least one field value
is not validated by the database engine or when the transaction
is killed by the callback ``table._before_insert``.
In that scenario, the ``errors`` key contains either a string,
the error message return by callback, or the dictionary returns
by the validator.
"""
self.dbg("Start DbSvc.create")
......@@ -528,38 +434,22 @@ class DbSvc(BaseSvc):
:type arg: dict
:param arg:
transaction data
:ref:`input transaction dictionary <input transaction dictionary>`
- ``tableName``
the name of the tablename in the database
- ``dbFields``
- ``[["table1", "field1"], ... ]````
- The list of database fields of the tablename.
- Include foreign keys and reference fields.
- ``records`` the list of ``id`` for the records
to be deleted, ``[id1, id2, ... ]``.
The key ``records`` is the list of ``id`` to be deleted
*e.g.* ``[id1, id2, ... ]``.
:returns:
dict
:ref:`output transaction dictionary <output transaction dictionary>`
- ``{success: True, records:[{Table1Id1: id}, ...], msg: 'blalbla'}``
- ``records`` is a list of dictionary containing the ``id``
of the delete records: ``[{TableId:xx}, ..]``.
* The key``records`` is a list of dictionary containing the ``id``
of the delete records *e.g.* ``[{TableId:xx}, ..]``.
- The record key are encoded as ``Table1Field1``.
- ``{success: False, records:[{Table1Field1: id}, ... ],
errors: 'blabla', }``
when at least one record does not exist or when the delete
operation is rejected by the callback ``table._before_delete``.
The full transaction is aborted.
The errors contains the error messages return by the callback.
* The full transaction is aborted when either one record does
not exist or when the delete operation is rejected by the
callback ``table._before_delete``. The ``errors`` key
contains the error messages return by the callback.
"""
self.dbg("Start DbSvc.destroy")
......@@ -608,58 +498,35 @@ class DbSvc(BaseSvc):
:type arg: dict
:param arg:
transaction data
:ref:`input transaction dictionary <input transaction dictionary>`
- ``tableName``
the name of the table in the database
- ``dbFields``
* The *optional* key ``where`` (optional) is a list of string
to build the inner join when handling foreign key::
- ``[["table1", "field1"], ... ]``
['db.table1.field1 == db.table2.id', ... ]
- The list of database fields of the table.
- Include foreign keys and reference fields.
- ``where`` (optional)
- ``['db.table1.field1 == db.table2.id', ... ]``
- a list of string to build the inner join
when handling foreign key.
- The string syntax follows the web2py convention:
``db.table1.field1 == db.table2.id``.
- An AND is performed between the different
elements of the list.
The string syntax follows the web2py convention:
``db.table1.field1 == db.table2.id``. An AND is performed
between the different elements of the list.
- ``orderby`` (optional)
* the *optional* key ``orderby`` is a list of tuples to build
the order directive::
- ``[("table1", "field1", "dir"), ("table2", "field3", "dir"), ...]``
[("table1", "field1", "dir"), ("table2", "field3", "dir"), ...]
- a list of tuples to build the order directive.
The third argument is equal to ``"ASC"`` or ``"DESC"``.
- the third argument is equal to ``"ASC"`` or ``"DESC"``.
The transaction data can also contains parameters useful for paging.
For more detail see Ext.PagingToolbar:
- page
- start
- limit
- sort
- dir
* The transaction dictionary can also contains parameters useful
for paging. For more detail see the Ext.PagingToolbar
configuration parameters: ``page``, ``start``, ``limit``,
``sort`` and ``dir``.
:returns:
dict
:ref:`output transaction dictionary <output transaction dictionary>`
- ``{success: True, records: [{TableField: value, ...}, ...]}``
- ``records`` is a list of dictionary containing the key value
pairs for the record found in the database.
The key ``records`` is a list of dictionary containing the key value
pairs for the record found in the database.
- the record keys are encoded as ``Table1Field1``.
"""
self.dbg("Start DbSvc.read")
......@@ -736,53 +603,26 @@ class DbSvc(BaseSvc):
Several transactions of the same type are processed together.
:type arg: dict
:param arg:
transaction data
:param arg:
:ref:`input transaction dictionary <input transaction dictionary>`
- ``tableName``
the name of the tablename in the database
- ``dbFields``
- ``[["table1", "field1"], ... ]``
- The list of database fields of the tablename.
- Include foreign keys and reference fields.
- ``records``
- ``[{"Table1Field1": val1,...}]``
- A list of dictionaries containing key, value pairs for fields
to be updated
- Includes foreign key and reference field values.
- Contains the ``id`` of the record to be updated.
- The keys are encoded as ``Table1Field1``.
the key ``records`` is the list of dictionaries one per record to
be updated. Each dictionary contains key, value pairs for fields
to be updated as well as the record ``id``.
:returns:
dict
:ref:`output transaction dictionary <output transaction dictionary>`
- ``{success: True, records:[{Table1Field1: val, ... }, ... ],
msg: 'blalbla'}``
- ``records`` is a list of dictionary containing the complete
* the key ``records`` is a list of dictionary containing the complete
key, value pairs for the ``record`` updated in the database.
- The record keys are encoded as ``Table1Field1``.
- ``{success: False, records:[{Table1Field1: val, ... }, ... ],
errors: 'blabla', }``
when at least a field value is not validated or when the transaction
* The full transaction is aborted when either a field value is not
validated by the database engine or when the transaction
is kill by the callback ``table._before_update``.
The full transaction is aborted.
The errors contains the error message return by callback or
a dictionary returns by the validator. The key is the field
The *errors* key contains the error message return by callback or
a dictionary returns by the validator (the key is the field
identifier encoded as ``Table1Field1`` while the value is
the error message.
the error message).
"""
self.dbg("Start DbSvc.update.")
......
......@@ -54,13 +54,13 @@ class DirectSvc(BaseSvc):
On the client-side:
- the API definition can be retrieved using the
* the API definition can be retrieved using the
URL: ``/myapplication/plugin_dbui/call/get_api``
- the URL to send requests is
* the URL to send requests is
``/myapplication/plugin_dbui/call``
- remote functions and methods can be call in the
* remote functions and methods can be call in the
following way ``Dbui.myfunction(a, b, callback)``
and ``MyClass.mymethod(c, d, callback)`` respectively.
......@@ -84,9 +84,9 @@ class DirectSvc(BaseSvc):
:returns:
str
- the response of the function / method run
* the response of the function / method run
on the server side
- the response is encoded as a JSON string.
* the response is encoded as a JSON string.
:raise gluon.http.HTTP:
when the request has no arguments
......@@ -157,7 +157,7 @@ class DirectSvc(BaseSvc):
def route(self):
"""Route the myrequest to the appropriate function / method,
"""Route the request to the appropriate function / method,
pass the proper arguments and return the results.
:returns:
......@@ -165,9 +165,9 @@ class DirectSvc(BaseSvc):
encoded as a JSON string.
:raise gluon.http.HTTP:
- with the code 500 when
the execution of the function / method crash.
- the python trace back is stored in the web2py ticket system.
with the code 500 when the execution of the
function / method crash. The python trace back is stored
in the web2py ticket system.
"""
self.dbg('Start directSvc.route')
......
......@@ -19,25 +19,25 @@ class FieldsModifier(Modifier):
table ``tablename``.
The data structure of the fields modifier can be access
outside the class:
outside the class::
>>> p = PluginManager('dbui')
>>> modifier = p.dbui['modifier_fields'][tablename]
p = PluginManager('dbui')
modifier = p.dbui['modifier_fields'][tablename]
or internally via the attribute ``data``.
The keys of the ``data`` structure are:
- ``extjs_fields`` (dict) Ext JS configuration options
* ``extjs_fields`` (dict) Ext JS configuration options
for individual ``field``.
- ``composite_fields.main`` (list) the first field
* ``composite_fields.main`` (list) the first field
of the ``FieldContainer``.
- ``composite_fields.others`` (list of list) the others field of
* ``composite_fields.others`` (list of list) the others field of
the ``FieldContainer``.
- There is one to one correspondence between the ``composite_fields.main``
* There is one to one correspondence between the ``composite_fields.main``
and the ``composite_fields.others`` lists.
:type tablename: str
......@@ -97,10 +97,10 @@ class FieldsModifier(Modifier):
They can be super seed by the keyword arguments.
:note:
- Each ``field`` is identified by its database field name.
- ``field`` should belong to the database table defined in the constructor.
- The first ``field`` is the main field of the ``FieldContainer``.
- The keyword arguments contains the configuration options of
* Each ``field`` is identified by its database field name.
* ``field`` should belong to the database table defined in the constructor.
* The first ``field`` is the main field of the ``FieldContainer``.
* The keyword arguments contains the configuration options of
the ``Ext.form.FieldContainer`` widget.
"""
......
......@@ -53,29 +53,29 @@ class FormModifier(Modifier):
table ``tablename``.
The data structure of the form modifier can be access
outside the class:
outside the class::
>>> p = PluginManager('dbui')
>>> modifier = p.dbui['modifier_forms'][tablename]
p = PluginManager('dbui')
modifier = p.dbui['modifier_forms'][tablename]
or internally via the attribute ``data``.
The keys of the ``data`` structure are:
- ``extjs`` (dict) Ext JS configuration options for the form widget.
* ``extjs`` (dict) Ext JS configuration options for the form widget.
- ``field_sets`` (list of Storage) each ``Storage`` defined a
* ``field_sets`` (list of Storage) each ``Storage`` defined a
``FieldSets``. It has two keys ``fields`` and ``extjs``.
The former is a list of field names belonging to the table
defined in the constructor. The latter is a dictionary with
the configuration options of the ``Ext.form.FieldSet`` widget.
- ``hidden_fields`` (list) list of field names to be hidden in
the form. The fields have to belong to the table defined in
the constructor.
* ``hidden_fields`` (list) list of field names to be hidden in
the form. The fields have to belong to the table defined in
the constructor.
- ``mapper`` (None or function) reference to the function used
to organize the ``FieldSet`` in ``Tabs``, for example.
* ``mapper`` (None or function) reference to the function used
to organize the ``FieldSet`` in ``Tabs``, for example.
:type tablename: str
:param tablename: name of the database table
......@@ -93,12 +93,12 @@ class FormModifier(Modifier):
"""Link two fields in such a way that the values available for the
second one depend on the value selected for the first one.
- This first field is the master while the second one is the slave.
- Often the master and slave fields are reference fields.
- An external table contains the data defining the relation between the
* This first field is the master while the second one is the slave.
* Often the master and slave fields are reference fields.
* An external table contains the data defining the relation between the
master and the slave.
- The external table must have the master and slave fields
- Several slaves can be attached to the same master::
* The external table must have the master and slave fields
* Several slaves can be attached to the same master::
fieldsModifier = fieldsModifier('mytable')
fieldsModifier.link_comboxes(master=virtdb.mytable.myfield1,
......@@ -108,7 +108,7 @@ class FormModifier(Modifier):
slave=virtdb.mytable.myfield3,
masterHasSlaveData='anotherTable')
- This method modify deeply the field configuration transforming
* This method modify deeply the field configuration transforming
the Ext.form.comboBox into App.form.LinkedComboBox.
:type master: gluon.dal.Field
......
......@@ -57,30 +57,30 @@ class GridModifier(Modifier):
table ``tablename``.
The data structure of the grid modifier can be access
outside the class:
outside the class::
>>> p = PluginManager('dbui')
>>> modifier = p.dbui['modifier_grids'][tablename]
p = PluginManager('dbui')
modifier = p.dbui['modifier_grids'][tablename]
or internally via the attribute ``data``.
The keys of the ``data`` structure are:
- ``extjs`` (dict) Ext JS configuration options for the grid widget.
* ``extjs`` (dict) Ext JS configuration options for the grid widget.
- ``configure_columns`` (dict) the Ext JS configuration options for
* ``configure_columns`` (dict) the Ext JS configuration options for
the ``Ext.grid.Column`` widget. The column is identify by its
``fieldname``.
- ``delete_columns`` (list)
* ``delete_columns`` (list)
- ``grid_filters`` (storage)
* ``grid_filters`` (storage)