Yaltik/flectra
2
0
Fork 0
Code Pull Requests Releases Activity
master
flectra/doc/howtos/backend.rst
Hansa 4c122b9241 User Documentation Update
2018-03-30 11:42:41 +00:00

1774 lines
58 KiB
ReStructuredText
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

:banner: banners/flectra_building_module.jpg
.. queue:: backend/series
=================
Building a Module
=================
.. warning::
This tutorial requires :ref:`having installed Flectra <setup/install>`
Start/Stop the Flectra server
=============================
Flectra uses a client/server architecture in which clients are web browsers
accessing the Flectra server via RPC.
Business logic and extension is generally performed on the server side,
although supporting client features (e.g. new data representation such as
interactive maps) can be added to the client.
In order to start the server, simply invoke the command :ref:`flectra-bin
<reference/cmdline>` in the shell, adding the full path to the file if
necessary:
.. code:: bash
flectra-bin
The server is stopped by hitting ``Ctrl-C`` twice from the terminal, or by
killing the corresponding OS process.
Build an Flectra module
=======================
Both server and client extensions are packaged as *modules* which are
optionally loaded in a *database*.
Flectra modules can either add brand new business logic to an Flectra system, or
alter and extend existing business logic: a module can be created to add your
country's accounting rules to Flectra's generic accounting support, while the
next module adds support for real-time visualisation of a bus fleet.
Everything in Flectra thus starts and ends with modules.
Composition of a module
-----------------------
An Flectra module can contain a number of elements:
Business objects
Declared as Python classes, these resources are automatically persisted
by Flectra based on their configuration
Data files
XML or CSV files declaring metadata (views or reports), configuration
data (modules parameterization), demonstration data and more
Web controllers
Handle requests from web browsers
Static web data
Images, CSS or javascript files used by the web interface or website
Module structure
----------------
Each module is a directory within a *module directory*. Module directories
are specified by using the :option:`--addons-path <flectra-bin --addons-path>`
option.
.. tip::
:class: aphorism
most command-line options can also be set using :ref:`a configuration
file <reference/cmdline/config>`
An Flectra module is declared by its :ref:`manifest <reference/module/manifest>`.
See the :ref:`manifest documentation <reference/module/manifest>` about it.
A module is also a
`Python package <http://docs.python.org/3/tutorial/modules.html#packages>`_
with a ``__init__.py`` file, containing import instructions for various Python
files in the module.
For instance, if the module has a single ``mymodule.py`` file ``__init__.py``
might contain::
from . import mymodule
Flectra provides a mechanism to help set up a new module, :ref:`flectra-bin
<reference/cmdline/server>` has a subcommand :ref:`scaffold
<reference/cmdline/scaffold>` to create an empty module:
.. code-block:: console
$ flectra-bin scaffold <module name> <where to put it>
The command creates a subdirectory for your module, and automatically creates a
bunch of standard files for a module. Most of them simply contain commented code
or XML. The usage of most of those files will be explained along this tutorial.
.. exercise:: Module creation
Use the command line above to create an empty module Open Academy, and
install it in Flectra.
.. only:: solutions
#. Invoke the command ``flectra-bin scaffold openacademy addons``.
#. Adapt the manifest file to your module.
#. Don't bother about the other files.
.. patch::
Object-Relational Mapping
-------------------------
A key component of Flectra is the :abbr:`ORM (Object-Relational Mapping)` layer.
This layer avoids having to write most :abbr:`SQL (Structured Query Language)`
by hand and provides extensibility and security services\ [#rawsql]_.
Business objects are declared as Python classes extending
:class:`~flectra.models.Model` which integrates them into the automated
persistence system.
Models can be configured by setting a number of attributes at their
definition. The most important attribute is
:attr:`~flectra.models.Model._name` which is required and defines the name for
the model in the Flectra system. Here is a minimally complete definition of a
model::
from flectra import models
class MinimalModel(models.Model):
_name = 'test.model'
Model fields
------------
Fields are used to define what the model can store and where. Fields are
defined as attributes on the model class::
from flectra import models, fields
class LessMinimalModel(models.Model):
_name = 'test.model2'
name = fields.Char()
Common Attributes
#################
Much like the model itself, its fields can be configured, by passing
configuration attributes as parameters::
name = field.Char(required=True)
Some attributes are available on all fields, here are the most common ones:
:attr:`~flectra.fields.Field.string` (``unicode``, default: field's name)
The label of the field in UI (visible by users).
:attr:`~flectra.fields.Field.required` (``bool``, default: ``False``)
If ``True``, the field can not be empty, it must either have a default
value or always be given a value when creating a record.
:attr:`~flectra.fields.Field.help` (``unicode``, default: ``''``)
Long-form, provides a help tooltip to users in the UI.
:attr:`~flectra.fields.Field.index` (``bool``, default: ``False``)
Requests that Flectra create a `database index`_ on the column.
Simple fields
#############
There are two broad categories of fields: "simple" fields which are atomic
values stored directly in the model's table and "relational" fields linking
records (of the same model or of different models).
Example of simple fields are :class:`~flectra.fields.Boolean`,
:class:`~flectra.fields.Date`, :class:`~flectra.fields.Char`.
Reserved fields
###############
Flectra creates a few fields in all models\ [#autofields]_. These fields are
managed by the system and shouldn't be written to. They can be read if
useful or necessary:
:attr:`~flectra.fields.Model.id` (:class:`~flectra.fields.Id`)
The unique identifier for a record in its model.
:attr:`~flectra.fields.Model.create_date` (:class:`~flectra.fields.Datetime`)
Creation date of the record.
:attr:`~flectra.fields.Model.create_uid` (:class:`~flectra.fields.Many2one`)
User who created the record.
:attr:`~flectra.fields.Model.write_date` (:class:`~flectra.fields.Datetime`)
Last modification date of the record.
:attr:`~flectra.fields.Model.write_uid` (:class:`~flectra.fields.Many2one`)
user who last modified the record.
Special fields
##############
By default, Flectra also requires a ``name`` field on all models for various
display and search behaviors. The field used for these purposes can be
overridden by setting :attr:`~flectra.models.Model._rec_name`.
.. exercise:: Define a model
Define a new data model *Course* in the *openacademy* module. A course
has a title and a description. Courses must have a title.
.. only:: solutions
Edit the file ``openacademy/models/models.py`` to include a *Course* class.
.. patch::
Data files
----------
Flectra is a highly data driven system. Although behavior is customized using
Python_ code part of a module's value is in the data it sets up when loaded.
.. tip:: some modules exist solely to add data into Flectra
:class: aphorism
Module data is declared via :ref:`data files <reference/data>`, XML files with
``<record>`` elements. Each ``<record>`` element creates or updates a database
record.
.. code-block:: xml
<flectra>
<record model="{model name}" id="{record identifier}">
<field name="{a field name}">{a value}</field>
</record>
</flectra>
* ``model`` is the name of the Flectra model for the record.
* ``id`` is an :term:`external identifier`, it allows referring to the record
(without having to know its in-database identifier).
* ``<field>`` elements have a ``name`` which is the name of the field in the
model (e.g. ``description``). Their body is the field's value.
Data files have to be declared in the manifest file to be loaded, they can
be declared in the ``'data'`` list (always loaded) or in the ``'demo'`` list
(only loaded in demonstration mode).
.. exercise:: Define demonstration data
Create demonstration data filling the *Courses* model with a few
demonstration courses.
.. only:: solutions
Edit the file ``openacademy/demo/demo.xml`` to include some data.
.. patch::
Actions and Menus
-----------------
Actions and menus are regular records in database, usually declared through
data files. Actions can be triggered in three ways:
#. by clicking on menu items (linked to specific actions)
#. by clicking on buttons in views (if these are connected to actions)
#. as contextual actions on object
Because menus are somewhat complex to declare there is a ``<menuitem>``
shortcut to declare an ``ir.ui.menu`` and connect it to the corresponding
action more easily.
.. code-block:: xml
<record model="ir.actions.act_window" id="action_list_ideas">
<field name="name">Ideas</field>
<field name="res_model">idea.idea</field>
<field name="view_mode">tree,form</field>
</record>
<menuitem id="menu_ideas" parent="menu_root" name="Ideas" sequence="10"
action="action_list_ideas"/>
.. danger::
:class: aphorism
The action must be declared before its corresponding menu in the XML file.
Data files are executed sequentially, the action's ``id`` must be present
in the database before the menu can be created.
.. exercise:: Define new menu entries
Define new menu entries to access courses under the
OpenAcademy menu entry. A user should be able to :
- display a list of all the courses
- create/modify courses
.. only:: solutions
#. Create ``openacademy/views/openacademy.xml`` with an action and
the menus triggering the action
#. Add it to the ``data`` list of ``openacademy/__manifest__.py``
.. patch::
Basic views
===========
Views define the way the records of a model are displayed. Each type of view
represents a mode of visualization (a list of records, a graph of their
aggregation, …). Views can either be requested generically via their type
(e.g. *a list of partners*) or specifically via their id. For generic
requests, the view with the correct type and the lowest priority will be
used (so the lowest-priority view of each type is the default view for that
type).
:ref:`View inheritance <reference/views/inheritance>` allows altering views
declared elsewhere (adding or removing content).
Generic view declaration
------------------------
A view is declared as a record of the model ``ir.ui.view``. The view type
is implied by the root element of the ``arch`` field:
.. code-block:: xml
<record model="ir.ui.view" id="view_id">
<field name="name">view.name</field>
<field name="model">object_name</field>
<field name="priority" eval="16"/>
<field name="arch" type="xml">
<!-- view content: <form>, <tree>, <graph>, ... -->
</field>
</record>
.. danger:: The view's content is XML.
:class: aphorism
The ``arch`` field must thus be declared as ``type="xml"`` to be parsed
correctly.
Tree views
----------
Tree views, also called list views, display records in a tabular form.
Their root element is ``<tree>``. The simplest form of the tree view simply
lists all the fields to display in the table (each field as a column):
.. code-block:: xml
<tree string="Idea list">
<field name="name"/>
<field name="inventor_id"/>
</tree>
Form views
----------
Forms are used to create and edit single records.
Their root element is ``<form>``. They are composed of high-level structure
elements (groups, notebooks) and interactive elements (buttons and fields):
.. code-block:: xml
<form string="Idea form">
<group colspan="4">
<group colspan="2" col="2">
<separator string="General stuff" colspan="2"/>
<field name="name"/>
<field name="inventor_id"/>
</group>
<group colspan="2" col="2">
<separator string="Dates" colspan="2"/>
<field name="active"/>
<field name="invent_date" readonly="1"/>
</group>
<notebook colspan="4">
<page string="Description">
<field name="description" nolabel="1"/>
</page>
</notebook>
<field name="state"/>
</group>
</form>
.. exercise:: Customise form view using XML
Create your own form view for the Course object. Data displayed should be:
the name and the description of the course.
.. only:: solutions
.. patch::
.. exercise:: Notebooks
In the Course form view, put the description field under a tab, such that
it will be easier to add other tabs later, containing additional
information.
.. only:: solutions
Modify the Course form view as follows:
.. patch::
Form views can also use plain HTML for more flexible layouts:
.. code-block:: xml
<form string="Idea Form">
<header>
<button string="Confirm" type="object" name="action_confirm"
states="draft" class="oe_highlight" />
<button string="Mark as done" type="object" name="action_done"
states="confirmed" class="oe_highlight"/>
<button string="Reset to draft" type="object" name="action_draft"
states="confirmed,done" />
<field name="state" widget="statusbar"/>
</header>
<sheet>
<div class="oe_title">
<label for="name" class="oe_edit_only" string="Idea Name" />
<h1><field name="name" /></h1>
</div>
<separator string="General" colspan="2" />
<group colspan="2" col="2">
<field name="description" placeholder="Idea description..." />
</group>
</sheet>
</form>
Search views
------------
Search views customize the search field associated with the list view (and
other aggregated views). Their root element is ``<search>`` and they're
composed of fields defining which fields can be searched on:
.. code-block:: xml
<search>
<field name="name"/>
<field name="inventor_id"/>
</search>
If no search view exists for the model, Flectra generates one which only allows
searching on the ``name`` field.
.. exercise:: Search courses
Allow searching for courses based on their title or their description.
.. only:: solutions
.. patch::
Relations between models
========================
A record from a model may be related to a record from another model. For
instance, a sale order record is related to a client record that contains the
client data; it is also related to its sale order line records.
.. exercise:: Create a session model
For the module Open Academy, we consider a model for *sessions*: a session
is an occurrence of a course taught at a given time for a given audience.
Create a model for *sessions*. A session has a name, a start date, a
duration and a number of seats. Add an action and a menu item to display
them. Make the new model visible via a menu item.
.. only:: solutions
#. Create the class *Session* in ``openacademy/models/models.py``.
#. Add access to the session object in ``openacademy/view/openacademy.xml``.
.. patch::
.. note:: ``digits=(6, 2)`` specifies the precision of a float number:
6 is the total number of digits, while 2 is the number of
digits after the comma. Note that it results in the number
digits before the comma is a maximum 4
Relational fields
-----------------
Relational fields link records, either of the same model (hierarchies) or
between different models.
Relational field types are:
:class:`Many2one(other_model, ondelete='set null') <flectra.fields.Many2one>`
A simple link to an other object::
print foo.other_id.name
.. seealso:: `foreign keys <http://www.postgresql.org/docs/9.3/static/tutorial-fk.html>`_
:class:`One2many(other_model, related_field) <flectra.fields.One2many>`
A virtual relationship, inverse of a :class:`~flectra.fields.Many2one`.
A :class:`~flectra.fields.One2many` behaves as a container of records,
accessing it results in a (possibly empty) set of records::
for other in foo.other_ids:
print other.name
.. danger::
Because a :class:`~flectra.fields.One2many` is a virtual relationship,
there *must* be a :class:`~flectra.fields.Many2one` field in the
:samp:`{other_model}`, and its name *must* be :samp:`{related_field}`
:class:`Many2many(other_model) <flectra.fields.Many2many>`
Bidirectional multiple relationship, any record on one side can be related
to any number of records on the other side. Behaves as a container of
records, accessing it also results in a possibly empty set of records::
for other in foo.other_ids:
print other.name
.. exercise:: Many2one relations
Using a many2one, modify the *Course* and *Session* models to reflect their
relation with other models:
- A course has a *responsible* user; the value of that field is a record of
the built-in model ``res.users``.
- A session has an *instructor*; the value of that field is a record of the
built-in model ``res.partner``.
- A session is related to a *course*; the value of that field is a record
of the model ``openacademy.course`` and is required.
- Adapt the views.
.. only:: solutions
#. Add the relevant ``Many2one`` fields to the models, and
#. add them in the views.
.. patch::
.. exercise:: Inverse one2many relations
Using the inverse relational field one2many, modify the models to reflect
the relation between courses and sessions.
.. only:: solutions
#. Modify the ``Course`` class, and
#. add the field in the course form view.
.. patch::
.. exercise:: Multiple many2many relations
Using the relational field many2many, modify the *Session* model to relate
every session to a set of *attendees*. Attendees will be represented by
partner records, so we will relate to the built-in model ``res.partner``.
Adapt the views accordingly.
.. only:: solutions
#. Modify the ``Session`` class, and
#. add the field in the form view.
.. patch::
Inheritance
===========
Model inheritance
-----------------
Flectra provides two *inheritance* mechanisms to extend an existing model in a
modular way.
The first inheritance mechanism allows a module to modify the behavior of a
model defined in another module:
- add fields to a model,
- override the definition of fields on a model,
- add constraints to a model,
- add methods to a model,
- override existing methods on a model.
The second inheritance mechanism (delegation) allows to link every record of a
model to a record in a parent model, and provides transparent access to the
fields of the parent record.
.. image:: ../images/inheritance_methods.png
:align: center
.. seealso::
* :attr:`~flectra.models.Model._inherit`
* :attr:`~flectra.models.Model._inherits`
View inheritance
----------------
Instead of modifying existing views in place (by overwriting them), Flectra
provides view inheritance where children "extension" views are applied on top of
root views, and can add or remove content from their parent.
An extension view references its parent using the ``inherit_id`` field, and
instead of a single view its ``arch`` field is composed of any number of
``xpath`` elements selecting and altering the content of their parent view:
.. code-block:: xml
<!-- improved idea categories list -->
<record id="idea_category_list2" model="ir.ui.view">
<field name="name">id.category.list2</field>
<field name="model">idea.category</field>
<field name="inherit_id" ref="id_category_list"/>
<field name="arch" type="xml">
<!-- find field description and add the field
idea_ids after it -->
<xpath expr="//field[@name='description']" position="after">
<field name="idea_ids" string="Number of ideas"/>
</xpath>
</field>
</record>
``expr``
An XPath_ expression selecting a single element in the parent view.
Raises an error if it matches no element or more than one
``position``
Operation to apply to the matched element:
``inside``
appends ``xpath``'s body at the end of the matched element
``replace``
replaces the matched element with the ``xpath``'s body, replacing any ``$0`` node occurrence
in the new body with the original element
``before``
inserts the ``xpath``'s body as a sibling before the matched element
``after``
inserts the ``xpaths``'s body as a sibling after the matched element
``attributes``
alters the attributes of the matched element using special
``attribute`` elements in the ``xpath``'s body
.. tip::
When matching a single element, the ``position`` attribute can be set directly
on the element to be found. Both inheritances below will give the same result.
.. code-block:: xml
<xpath expr="//field[@name='description']" position="after">
<field name="idea_ids" />
</xpath>
<field name="description" position="after">
<field name="idea_ids" />
</field>
.. exercise:: Alter existing content
* Using model inheritance, modify the existing *Partner* model to add an
``instructor`` boolean field, and a many2many field that corresponds to
the session-partner relation
* Using view inheritance, display this fields in the partner form view
.. only:: solutions
.. note::
This is the opportunity to introduce the developer mode to
inspect the view, find its external ID and the place to put the
new field.
#. Create a file ``openacademy/models/partner.py`` and import it in
``__init__.py``
#. Create a file ``openacademy/views/partner.xml`` and add it to
``__manifest__.py``
.. patch::
Domains
#######
In Flectra, :ref:`reference/orm/domains` are values that encode conditions on
records. A domain is a list of criteria used to select a subset of a model's
records. Each criteria is a triple with a field name, an operator and a value.
For instance, when used on the *Product* model the following domain selects
all *services* with a unit price over *1000*::
[('product_type', '=', 'service'), ('unit_price', '>', 1000)]
By default criteria are combined with an implicit AND. The logical operators
``&`` (AND), ``|`` (OR) and ``!`` (NOT) can be used to explicitly combine
criteria. They are used in prefix position (the operator is inserted before
its arguments rather than between). For instance to select products "which are
services *OR* have a unit price which is *NOT* between 1000 and 2000"::
['|',
('product_type', '=', 'service'),
'!', '&',
('unit_price', '>=', 1000),
('unit_price', '<', 2000)]
A ``domain`` parameter can be added to relational fields to limit valid
records for the relation when trying to select records in the client interface.
.. exercise:: Domains on relational fields
When selecting the instructor for a *Session*, only instructors (partners
with ``instructor`` set to ``True``) should be visible.
.. only:: solutions
.. patch::
.. note::
A domain declared as a literal list is evaluated server-side and
can't refer to dynamic values on the right-hand side, a domain
declared as a string is evaluated client-side and allows
field names on the right-hand side
.. exercise:: More complex domains
Create new partner categories *Teacher / Level 1* and *Teacher / Level 2*.
The instructor for a session can be either an instructor or a teacher
(of any level).
.. only:: solutions
#. Modify the *Session* model's domain
#. Modify ``openacademy/view/partner.xml`` to get access to
*Partner categories*:
.. patch::
Computed fields and default values
==================================
So far fields have been stored directly in and retrieved directly from the
database. Fields can also be *computed*. In that case, the field's value is not
retrieved from the database but computed on-the-fly by calling a method of the
model.
To create a computed field, create a field and set its attribute
:attr:`~flectra.fields.Field.compute` to the name of a method. The computation
method should simply set the value of the field to compute on every record in
``self``.
.. danger:: ``self`` is a collection
:class: aphorism
The object ``self`` is a *recordset*, i.e., an ordered collection of
records. It supports the standard Python operations on collections, like
``len(self)`` and ``iter(self)``, plus extra set operations like ``recs1 +
recs2``.
Iterating over ``self`` gives the records one by one, where each record is
itself a collection of size 1. You can access/assign fields on single
records by using the dot notation, like ``record.name``.
.. code-block:: python
import random
from flectra import models, fields, api
class ComputedModel(models.Model):
_name = 'test.computed'
name = fields.Char(compute='_compute_name')
@api.multi
def _compute_name(self):
for record in self:
record.name = str(random.randint(1, 1e6))
Dependencies
------------
The value of a computed field usually depends on the values of other fields on
the computed record. The ORM expects the developer to specify those dependencies
on the compute method with the decorator :func:`~flectra.api.depends`.
The given dependencies are used by the ORM to trigger the recomputation of the
field whenever some of its dependencies have been modified::
from flectra import models, fields, api
class ComputedModel(models.Model):
_name = 'test.computed'
name = fields.Char(compute='_compute_name')
value = fields.Integer()
@api.depends('value')
def _compute_name(self):
for record in self:
record.name = "Record with value %s" % record.value
.. exercise:: Computed fields
* Add the percentage of taken seats to the *Session* model
* Display that field in the tree and form views
* Display the field as a progress bar
.. only:: solutions
#. Add a computed field to *Session*
#. Show the field in the *Session* view:
.. patch::
Default values
--------------
Any field can be given a default value. In the field definition, add the option
``default=X`` where ``X`` is either a Python literal value (boolean, integer,
float, string), or a function taking a recordset and returning a value::
name = fields.Char(default="Unknown")
user_id = fields.Many2one('res.users', default=lambda self: self.env.user)
.. note::
The object ``self.env`` gives access to request parameters and other useful
things:
- ``self.env.cr`` or ``self._cr`` is the database *cursor* object; it is
used for querying the database
- ``self.env.uid`` or ``self._uid`` is the current user's database id
- ``self.env.user`` is the current user's record
- ``self.env.context`` or ``self._context`` is the context dictionary
- ``self.env.ref(xml_id)`` returns the record corresponding to an XML id
- ``self.env[model_name]`` returns an instance of the given model
.. exercise:: Active objects – Default values
* Define the start_date default value as today (see
:class:`~flectra.fields.Date`).
* Add a field ``active`` in the class Session, and set sessions as active by
default.
.. only:: solutions
.. patch::
.. note::
Flectra has built-in rules making fields with an ``active`` field set
to ``False`` invisible.
Onchange
========
The "onchange" mechanism provides a way for the client interface to update a
form whenever the user has filled in a value in a field, without saving anything
to the database.
For instance, suppose a model has three fields ``amount``, ``unit_price`` and
``price``, and you want to update the price on the form when any of the other
fields is modified. To achieve this, define a method where ``self`` represents
the record in the form view, and decorate it with :func:`~flectra.api.onchange`
to specify on which field it has to be triggered. Any change you make on
``self`` will be reflected on the form.
.. code-block:: xml
<!-- content of form view -->
<field name="amount"/>
<field name="unit_price"/>
<field name="price" readonly="1"/>
.. code-block:: python
# onchange handler
@api.onchange('amount', 'unit_price')
def _onchange_price(self):
# set auto-changing field
self.price = self.amount * self.unit_price
# Can optionally return a warning and domains
return {
'warning': {
'title': "Something bad happened",
'message': "It was very bad indeed",
}
}
For computed fields, valued ``onchange`` behavior is built-in as can be seen by
playing with the *Session* form: change the number of seats or participants, and
the ``taken_seats`` progressbar is automatically updated.
.. exercise:: Warning
Add an explicit onchange to warn about invalid values, like a negative
number of seats, or more participants than seats.
.. only:: solutions
.. patch::
Model constraints
=================
Flectra provides two ways to set up automatically verified invariants:
:func:`Python constraints <flectra.api.constrains>` and
:attr:`SQL constraints <flectra.models.Model._sql_constraints>`.
A Python constraint is defined as a method decorated with
:func:`~flectra.api.constrains`, and invoked on a recordset. The decorator
specifies which fields are involved in the constraint, so that the constraint is
automatically evaluated when one of them is modified. The method is expected to
raise an exception if its invariant is not satisfied::
from flectra.exceptions import ValidationError
@api.constrains('age')
def _check_something(self):
for record in self:
if record.age > 20:
raise ValidationError("Your record is too old: %s" % record.age)
# all records passed the test, don't return anything
.. exercise:: Add Python constraints
Add a constraint that checks that the instructor is not present in the
attendees of his/her own session.
.. only:: solutions
.. patch::
SQL constraints are defined through the model attribute
:attr:`~flectra.models.Model._sql_constraints`. The latter is assigned to a list
of triples of strings ``(name, sql_definition, message)``, where ``name`` is a
valid SQL constraint name, ``sql_definition`` is a table_constraint_ expression,
and ``message`` is the error message.
.. exercise:: Add SQL constraints
With the help of `PostgreSQL's documentation`_ , add the following
constraints:
#. CHECK that the course description and the course title are different
#. Make the Course's name UNIQUE
.. only:: solutions
.. patch::
.. exercise:: Exercise 6 - Add a duplicate option
Since we added a constraint for the Course name uniqueness, it is not
possible to use the "duplicate" function anymore (:menuselection:`Form -->
Duplicate`).
Re-implement your own "copy" method which allows to duplicate the Course
object, changing the original name into "Copy of [original name]".
.. only:: solutions
.. patch::
Advanced Views
==============
Tree views
----------
Tree views can take supplementary attributes to further customize their
behavior:
``decoration-{$name}``
allow changing the style of a row's text based on the corresponding
record's attributes.
Values are Python expressions. For each record, the expression is evaluated
with the record's attributes as context values and if ``true``, the
corresponding style is applied to the row. Other context values are
``uid`` (the id of the current user) and ``current_date`` (the current date
as a string of the form ``yyyy-MM-dd``).
``{$name}`` can be ``bf`` (``font-weight: bold``), ``it``
(``font-style: italic``), or any `bootstrap contextual color
<http://getbootstrap.com/components/#available-variations>`_ (``danger``,
``info``, ``muted``, ``primary``, ``success`` or ``warning``).
.. code-block:: xml
<tree string="Idea Categories" decoration-info="state=='draft'"
decoration-danger="state=='trashed'">
<field name="name"/>
<field name="state"/>
</tree>
``editable``
Either ``"top"`` or ``"bottom"``. Makes the tree view editable in-place
(rather than having to go through the form view), the value is the
position where new rows appear.
.. exercise:: List coloring
Modify the Session tree view in such a way that sessions lasting less than
5 days are colored blue, and the ones lasting more than 15 days are
colored red.
.. only:: solutions
Modify the session tree view:
.. patch::
Calendars
---------
Displays records as calendar events. Their root element is ``<calendar>`` and
their most common attributes are:
``color``
The name of the field used for *color segmentation*. Colors are
automatically distributed to events, but events in the same color segment
(records which have the same value for their ``@color`` field) will be
given the same color.
``date_start``
record's field holding the start date/time for the event
``date_stop`` (optional)
record's field holding the end date/time for the event
field (to define the label for each calendar event)
.. code-block:: xml
<calendar string="Ideas" date_start="invent_date" color="inventor_id">
<field name="name"/>
</calendar>
.. exercise:: Calendar view
Add a Calendar view to the *Session* model enabling the user to view the
events associated to the Open Academy.
.. only:: solutions
#. Add an ``end_date`` field computed from ``start_date`` and
``duration``
.. tip:: the inverse function makes the field writable, and allows
moving the sessions (via drag and drop) in the calendar view
#. Add a calendar view to the *Session* model
#. And add the calendar view to the *Session* model's actions
.. patch::
Search views
------------
Search view ``<field>`` elements can have a ``@filter_domain`` that overrides
the domain generated for searching on the given field. In the given domain,
``self`` represents the value entered by the user. In the example below, it is
used to search on both fields ``name`` and ``description``.
Search views can also contain ``<filter>`` elements, which act as toggles for
predefined searches. Filters must have one of the following attributes:
``domain``
add the given domain to the current search
``context``
add some context to the current search; use the key ``group_by`` to group
results on the given field name
.. code-block:: xml
<search string="Ideas">
<field name="name"/>
<field name="description" string="Name and description"
filter_domain="['|', ('name', 'ilike', self), ('description', 'ilike', self)]"/>
<field name="inventor_id"/>
<field name="country_id" widget="selection"/>
<filter name="my_ideas" string="My Ideas"
domain="[('inventor_id', '=', uid)]"/>
<group string="Group By">
<filter name="group_by_inventor" string="Inventor"
context="{'group_by': 'inventor_id'}"/>
</group>
</search>
To use a non-default search view in an action, it should be linked using the
``search_view_id`` field of the action record.
The action can also set default values for search fields through its
``context`` field: context keys of the form
:samp:`search_default_{field_name}` will initialize *field_name* with the
provided value. Search filters must have an optional ``@name`` to have a
default and behave as booleans (they can only be enabled by default).
.. exercise:: Search views
#. Add a button to filter the courses for which the current user is the
responsible in the course search view. Make it selected by default.
#. Add a button to group courses by responsible user.
.. only:: solutions
.. patch::
Gantt
-----
.. warning::
The gantt view requires the web_gantt module.
Horizontal bar charts typically used to show project planning and advancement,
their root element is ``<gantt>``.
.. code-block:: xml
<gantt string="Ideas"
date_start="invent_date"
date_stop="date_finished"
progress="progress"
default_group_by="inventor_id" />
.. exercise:: Gantt charts
Add a Gantt Chart enabling the user to view the sessions scheduling linked
to the Open Academy module. The sessions should be grouped by instructor.
.. only:: solutions
#. Create a computed field expressing the session's duration in hours
#. Add the gantt view's definition, and add the gantt view to the
*Session* model's action
.. patch::
Graph views
-----------
Graph views allow aggregated overview and analysis of models, their root
element is ``<graph>``.
.. note::
Pivot views (element ``<pivot>``) a multidimensional table, allows the
selection of filers and dimensions to get the right aggregated dataset
before moving to a more graphical overview. The pivot view shares the same
content definition as graph views.
Graph views have 4 display modes, the default mode is selected using the
``@type`` attribute.
Bar (default)
a bar chart, the first dimension is used to define groups on the
horizontal axis, other dimensions define aggregated bars within each group.
By default bars are side-by-side, they can be stacked by using
``@stacked="True"`` on the ``<graph>``
Line
2-dimensional line chart
Pie
2-dimensional pie
Graph views contain ``<field>`` with a mandatory ``@type`` attribute taking
the values:
``row`` (default)
the field should be aggregated by default
``measure``
the field should be aggregated rather than grouped on
.. code-block:: xml
<graph string="Total idea score by Inventor">
<field name="inventor_id"/>
<field name="score" type="measure"/>
</graph>
.. warning::
Graph views perform aggregations on database values, they do not work
with non-stored computed fields.
.. exercise:: Graph view
Add a Graph view in the Session object that displays, for each course, the
number of attendees under the form of a bar chart.
.. only:: solutions
#. Add the number of attendees as a stored computed field
#. Then add the relevant view
.. patch::
Kanban
------
Used to organize tasks, production processes, etc… their root element is
``<kanban>``.
A kanban view shows a set of cards possibly grouped in columns. Each card
represents a record, and each column the values of an aggregation field.
For instance, project tasks may be organized by stage (each column is a
stage), or by responsible (each column is a user), and so on.
Kanban views define the structure of each card as a mix of form elements
(including basic HTML) and :ref:`reference/qweb`.
.. exercise:: Kanban view
Add a Kanban view that displays sessions grouped by course (columns are
thus courses).
.. only:: solutions
#. Add an integer ``color`` field to the *Session* model
#. Add the kanban view and update the action
.. patch::
Security
========
Access control mechanisms must be configured to achieve a coherent security
policy.
Group-based access control mechanisms
-------------------------------------
Groups are created as normal records on the model ``res.groups``, and granted
menu access via menu definitions. However even without a menu, objects may
still be accessible indirectly, so actual object-level permissions (read,
write, create, unlink) must be defined for groups. They are usually inserted
via CSV files inside modules. It is also possible to restrict access to
specific fields on a view or object using the field's groups attribute.
Access rights
-------------
Access rights are defined as records of the model ``ir.model.access``. Each
access right is associated to a model, a group (or no group for global
access), and a set of permissions: read, write, create, unlink. Such access
rights are usually created by a CSV file named after its model:
``ir.model.access.csv``.
.. code-block:: text
id,name,model_id/id,group_id/id,perm_read,perm_write,perm_create,perm_unlink
access_idea_idea,idea.idea,model_idea_idea,base.group_user,1,1,1,0
access_idea_vote,idea.vote,model_idea_vote,base.group_user,1,1,1,0
.. exercise:: Add access control through the Flectra interface
Create a new user "John Smith". Then create a group
"OpenAcademy / Session Read" with read access to the *Session* model.
.. only:: solutions
#. Create a new user *John Smith* through
:menuselection:`Settings --> Users --> Users`
#. Create a new group ``session_read`` through
:menuselection:`Settings --> Users --> Groups`, it should have
read access on the *Session* model
#. Edit *John Smith* to make them a member of ``session_read``
#. Log in as *John Smith* to check the access rights are correct
.. exercise:: Add access control through data files in your module
Using data files,
* Create a group *OpenAcademy / Manager* with full access to all
OpenAcademy models
* Make *Session* and *Course* readable by all users
.. only:: solutions
#. Create a new file ``openacademy/security/security.xml`` to
hold the OpenAcademy Manager group
#. Edit the file ``openacademy/security/ir.model.access.csv`` with
the access rights to the models
#. Finally update ``openacademy/__manifest__.py`` to add the new data
files to it
.. patch::
Record rules
------------
A record rule restricts the access rights to a subset of records of the given
model. A rule is a record of the model ``ir.rule``, and is associated to a
model, a number of groups (many2many field), permissions to which the
restriction applies, and a domain. The domain specifies to which records the
access rights are limited.
Here is an example of a rule that prevents the deletion of leads that are not
in state ``cancel``. Notice that the value of the field ``groups`` must follow
the same convention as the method :meth:`~flectra.models.Model.write` of the ORM.
.. code-block:: xml
<record id="delete_cancelled_only" model="ir.rule">
<field name="name">Only cancelled leads may be deleted</field>
<field name="model_id" ref="crm.model_crm_lead"/>
<field name="groups" eval="[(4, ref('sales_team.group_sale_manager'))]"/>
<field name="perm_read" eval="0"/>
<field name="perm_write" eval="0"/>
<field name="perm_create" eval="0"/>
<field name="perm_unlink" eval="1" />
<field name="domain_force">[('state','=','cancel')]</field>
</record>
.. exercise:: Record rule
Add a record rule for the model Course and the group
"OpenAcademy / Manager", that restricts ``write`` and ``unlink`` accesses
to the responsible of a course. If a course has no responsible, all users
of the group must be able to modify it.
.. only:: solutions
Create a new rule in ``openacademy/security/security.xml``:
.. patch::
Wizards
=======
Wizards describe interactive sessions with the user (or dialog boxes) through
dynamic forms. A wizard is simply a model that extends the class
:class:`~flectra.models.TransientModel` instead of
:class:`~flectra.models.Model`. The class
:class:`~flectra.models.TransientModel` extends :class:`~flectra.models.Model`
and reuse all its existing mechanisms, with the following particularities:
- Wizard records are not meant to be persistent; they are automatically deleted
from the database after a certain time. This is why they are called
*transient*.
- Wizard models do not require explicit access rights: users have all
permissions on wizard records.
- Wizard records may refer to regular records or wizard records through many2one
fields, but regular records *cannot* refer to wizard records through a
many2one field.
We want to create a wizard that allow users to create attendees for a particular
session, or for a list of sessions at once.
.. exercise:: Define the wizard
Create a wizard model with a many2one relationship with the *Session*
model and a many2many relationship with the *Partner* model.
.. only:: solutions
Add a new file ``openacademy/wizard.py``:
.. patch::
Launching wizards
-----------------
Wizards are launched by ``ir.actions.act_window`` records, with the field
``target`` set to the value ``new``. The latter opens the wizard view into a
popup window. The action may be triggered by a menu item.
There is another way to launch the wizard: using an ``ir.actions.act_window``
record like above, but with an extra field ``src_model`` that specifies in the
context of which model the action is available. The wizard will appear in the
contextual actions of the model, above the main view. Because of some internal
hooks in the ORM, such an action is declared in XML with the tag ``act_window``.
.. code:: xml
<act_window id="launch_the_wizard"
name="Launch the Wizard"
src_model="context.model.name"
res_model="wizard.model.name"
view_mode="form"
target="new"
key2="client_action_multi"/>
Wizards use regular views and their buttons may use the attribute
``special="cancel"`` to close the wizard window without saving.
.. exercise:: Launch the wizard
#. Define a form view for the wizard.
#. Add the action to launch it in the context of the *Session* model.
#. Define a default value for the session field in the wizard; use the
context parameter ``self._context`` to retrieve the current session.
.. only:: solutions
.. patch::
.. exercise:: Register attendees
Add buttons to the wizard, and implement the corresponding method for adding
the attendees to the given session.
.. only:: solutions
.. patch::
.. exercise:: Register attendees to multiple sessions
Modify the wizard model so that attendees can be registered to multiple
sessions.
.. only:: solutions
.. patch::
Internationalization
====================
Each module can provide its own translations within the i18n directory, by
having files named LANG.po where LANG is the locale code for the language, or
the language and country combination when they differ (e.g. pt.po or
pt_BR.po). Translations will be loaded automatically by Flectra for all
enabled languages. Developers always use English when creating a module, then
export the module terms using Flectra's gettext POT export feature
(:menuselection:`Settings --> Translations --> Import/Export --> Export
Translation` without specifying a language), to create the module template POT
file, and then derive the translated PO files. Many IDE's have plugins or modes
for editing and merging PO/POT files.
.. tip:: The Portable Object files generated by Flectra are published on
`Transifex <https://www.transifex.com/flectra/public/>`__, making it
easy to translate the software.
.. code-block:: text
|- idea/ # The module directory
|- i18n/ # Translation files
| - idea.pot # Translation Template (exported from Flectra)
| - fr.po # French translation
| - pt_BR.po # Brazilian Portuguese translation
| (...)
.. tip::
By default Flectra's POT export only extracts labels inside XML files or
inside field definitions in Python code, but any Python string can be
translated this way by surrounding it with the function :func:`flectra._`
(e.g. ``_("Label")``)
.. exercise:: Translate a module
Choose a second language for your Flectra installation. Translate your
module using the facilities provided by Flectra.
.. only:: solutions
#. Create a directory ``openacademy/i18n/``
#. Install whichever language you want (
:menuselection:`Administration --> Translations --> Load an
Official Translation`)
#. Synchronize translatable terms (:menuselection:`Administration -->
Translations --> Application Terms --> Synchronize Translations`)
#. Create a template translation file by exporting (
:menuselection:`Administration --> Translations -> Import/Export
--> Export Translation`) without specifying a language, save in
``openacademy/i18n/``
#. Create a translation file by exporting (
:menuselection:`Administration --> Translations --> Import/Export
--> Export Translation`) and specifying a language. Save it in
``openacademy/i18n/``
#. Open the exported translation file (with a basic text editor or a
dedicated PO-file editor e.g. POEdit_ and translate the missing
terms
#. In ``models.py``, add an import statement for the function
``flectra._`` and mark missing strings as translatable
#. Repeat steps 3-6
.. patch::
.. todo:: do we never reload translations?
Reporting
=========
Printed reports
---------------
Flectra 11.0 uses a report engine based on :ref:`reference/qweb`,
`Twitter Bootstrap`_ and Wkhtmltopdf_.
A report is a combination two elements:
* an ``ir.actions.report``, for which a ``<report>`` shortcut element is
provided, it sets up various basic parameters for the report (default
type, whether the report should be saved to the database after generation,…)
.. code-block:: xml
<report
id="account_invoices"
model="account.invoice"
string="Invoices"
report_type="qweb-pdf"
name="account.report_invoice"
file="account.report_invoice"
attachment_use="True"
attachment="(object.state in ('open','paid')) and
('INV'+(object.number or '').replace('/','')+'.pdf')"
/>
* A standard :ref:`QWeb view <reference/views/qweb>` for the actual report:
.. code-block:: xml
<t t-call="web.html_container">
<t t-foreach="docs" t-as="o">
<t t-call="web.external_layout">
<div class="page">
<h2>Report title</h2>
</div>
</t>
</t>
</t>
the standard rendering context provides a number of elements, the most
important being:
``docs``
the records for which the report is printed
``user``
the user printing the report
Because reports are standard web pages, they are available through a URL and
output parameters can be manipulated through this URL, for instance the HTML
version of the *Invoice* report is available through
http://localhost:8069/report/html/account.report_invoice/1 (if ``account`` is
installed) and the PDF version through
http://localhost:8069/report/pdf/account.report_invoice/1.
.. _reference/backend/reporting/printed-reports/pdf-without-styles:
.. danger::
If it appears that your PDF report is missing the styles (i.e. the text
appears but the style/layout is different from the html version), probably
your wkhtmltopdf_ process cannot reach your web server to download them.
If you check your server logs and see that the CSS styles are not being
downloaded when generating a PDF report, most surely this is the problem.
The wkhtmltopdf_ process will use the ``web.base.url`` system parameter as
the *root path* to all linked files, but this parameter is automatically
updated each time the Administrator is logged in. If your server resides
behind some kind of proxy, that could not be reachable. You can fix this by
adding one of these system parameters:
- ``report.url``, pointing to an URL reachable from your server
(probably ``http://localhost:8069`` or something similar). It will be
used for this particular purpose only.
- ``web.base.url.freeze``, when set to ``True``, will stop the
automatic updates to ``web.base.url``.
.. exercise:: Create a report for the Session model
For each session, it should display session's name, its start and end,
and list the session's attendees.
.. only:: solutions
.. patch::
Dashboards
----------
.. exercise:: Define a Dashboard
Define a dashboard containing the graph view you created, the sessions
calendar view and a list view of the courses (switchable to a form
view). This dashboard should be available through a menuitem in the menu,
and automatically displayed in the web client when the OpenAcademy main
menu is selected.
.. only:: solutions
#. Create a file ``openacademy/views/session_board.xml``. It should contain
the board view, the actions referenced in that view, an action to
open the dashboard and a re-definition of the main menu item to add
the dashboard action
.. note:: Available dashboard styles are ``1``, ``1-1``, ``1-2``,
``2-1`` and ``1-1-1``
#. Update ``openacademy/__manifest__.py`` to reference the new data
file
.. patch::
WebServices
===========
The web-service module offer a common interface for all web-services :
- XML-RPC
- JSON-RPC
Business objects can also be accessed via the distributed object
mechanism. They can all be modified via the client interface with contextual
views.
Flectra is accessible through XML-RPC/JSON-RPC interfaces, for which libraries
exist in many languages.
XML-RPC Library
---------------
The following example is a Python 3 program that interacts with an Flectra
server with the library ``xmlrpc.client``::
import xmlrpc.client
root = 'http://%s:%d/xmlrpc/' % (HOST, PORT)
uid = xmlrpc.client.ServerProxy(root + 'common').login(DB, USER, PASS)
print("Logged in as %s (uid: %d)" % (USER, uid))
# Create a new note
sock = xmlrpc.client.ServerProxy(root + 'object')
args = {
'color' : 8,
'memo' : 'This is a note',
'create_uid': uid,
}
note_id = sock.execute(DB, uid, PASS, 'note.note', 'create', args)
.. exercise:: Add a new service to the client
Write a Python program able to send XML-RPC requests to a PC running
Flectra (yours, or your instructor's). This program should display all
the sessions, and their corresponding number of seats. It should also
create a new session for one of the courses.
.. only:: solutions
.. code-block:: python
import functools
import xmlrpc.client
HOST = 'localhost'
PORT = 8069
DB = 'openacademy'
USER = 'admin'
PASS = 'admin'
ROOT = 'http://%s:%d/xmlrpc/' % (HOST,PORT)
# 1. Login
uid = xmlrpc.client.ServerProxy(ROOT + 'common').login(DB,USER,PASS)
print("Logged in as %s (uid:%d)" % (USER,uid))
call = functools.partial(
xmlrpc.client.ServerProxy(ROOT + 'object').execute,
DB, uid, PASS)
# 2. Read the sessions
sessions = call('openacademy.session','search_read', [], ['name','seats'])
for session in sessions:
print("Session %s (%s seats)" % (session['name'], session['seats']))
# 3.create a new session
session_id = call('openacademy.session', 'create', {
'name' : 'My session',
'course_id' : 2,
})
Instead of using a hard-coded course id, the code can look up a course
by name::
# 3.create a new session for the "Functional" course
course_id = call('openacademy.course', 'search', [('name','ilike','Functional')])[0]
session_id = call('openacademy.session', 'create', {
'name' : 'My session',
'course_id' : course_id,
})
JSON-RPC Library
----------------
The following example is a Python 3 program that interacts with an Flectra server
with the standard Python libraries ``urllib.request`` and ``json``::
import json
import random
import urllib.request
def json_rpc(url, method, params):
data = {
"jsonrpc": "2.0",
"method": method,
"params": params,
"id": random.randint(0, 1000000000),
}
req = urllib.request.Request(url=url, data=json.dumps(data).encode(), headers={
"Content-Type":"application/json",
})
reply = json.load(urllib.request.urlopen(req))
if reply.get("error"):
raise Exception(reply["error"])
return reply["result"]
def call(url, service, method, *args):
return json_rpc(url, "call", {"service": service, "method": method, "args": args})
# log in the given database
url = "http://%s:%s/jsonrpc" % (HOST, PORT)
uid = call(url, "common", "login", DB, USER, PASS)
# create a new note
args = {
'color': 8,
'memo': 'This is another note',
'create_uid': uid,
}
note_id = call(url, "object", "execute", DB, uid, PASS, 'note.note', 'create', args)
Examples can be easily adapted from XML-RPC to JSON-RPC.
.. note::
There are a number of high-level APIs in various languages to access Flectra
systems without *explicitly* going through XML-RPC or JSON-RPC, such as:
* https://github.com/akretion/ooor
* https://github.com/syleam/openobject-library
* https://github.com/nicolas-van/openerp-client-lib
* http://pythonhosted.org/FlectraRPC
* https://github.com/abhishek-jaiswal/php-openerp-lib
.. [#autofields] it is possible to :attr:`disable the automatic creation of some
fields <flectra.models.Model._log_access>`
.. [#rawsql] writing raw SQL queries is possible, but requires care as it
bypasses all Flectra authentication and security mechanisms.
.. _database index:
http://use-the-index-luke.com/sql/preface
.. _POEdit: http://poedit.net
.. _PostgreSQL's documentation:
.. _table_constraint:
http://www.postgresql.org/docs/9.3/static/ddl-constraints.html
.. _python: http://python.org
.. _XPath: http://w3.org/TR/xpath
.. _twitter bootstrap: http://getbootstrap.com
.. _wkhtmltopdf: http://wkhtmltopdf.org
View Git Blame Copy Permalink