1 .. queue:: backend/series
7 Start/Stop the Odoo server
8 ==========================
10 Odoo uses a client/server architecture in which clients are web browsers
11 accessing the odoo server via RPC.
13 Business logic and extension is generally performed on the server side,
14 although supporting client features (e.g. new data representation such as
15 interactive maps) can be added to the client.
17 In order to start the server, simply invoke the command :ref:`odoo.py
18 <reference/cmdline>` in the shell, adding the full path to the file if
25 The server is stopped by hitting ``Ctrl-C`` twice from the terminal, or by
26 killing the corresponding OS process.
31 Both server and client extensions are packaged as *modules* which are
32 optionally loaded in a *database*.
34 Odoo modules can either add brand new business logic to an Odoo system, or
35 alter and extend existing business logic: a module can be created to add your
36 country's accounting rules to Odoo's generic accounting support, while the
37 next module adds support for real-time visualisation of a bus fleet.
39 Everything in Odoo thus starts and ends with modules.
41 Composition of a module
42 -----------------------
44 An Odoo module can contain a number of elements:
47 declared as Python classes, these resources are automatically persisted
48 by Odoo based on their configuration
51 XML or CSV files declaring metadata (views or workflows), configuration
52 data (modules parameterization), demonstration data and more
55 Handle requests from web browsers
58 Images, CSS or javascript files used by the web interface or website
63 Each module is a directory within a *module directory*. Module directories
64 are specified by using the :option:`--addons-path <odoo.py --addons-path>`
70 most command-line options can also be set using :ref:`a configuration
71 file <reference/cmdline/config>`
73 An Odoo module is declared by its :ref:`manifest <reference/module/manifest>`. It
74 is mandatory and contains a single python dictionary declaring various
75 metadata for the module: the module's name and description, list of Odoo
76 modules required for this one to work properly, references to data files, …
78 The manifest's general structure is::
84 'author': "Author Name",
85 'category': 'Category',
89 # data files always loaded at installation
93 # data files containing optionally loaded demonstration data
100 `Python package <http://docs.python.org/2/tutorial/modules.html#packages>`_
101 with a ``__init__.py`` file, containing import instructions for various Python
104 For instance, if the module has a single ``mymodule.py`` file ``__init__.py``
109 Fortunately, there is a mechanism to help you set up an module. The command
110 ``odoo.py`` has a subcommand :ref:`scaffold <reference/cmdline/scaffold>` to
111 create an empty module:
115 odoo.py scaffold <module name> <where to put it>
117 The command creates a subdirectory for your module, and automatically creates a
118 bunch of standard files for a module. Most of them simply contain commented code
119 or XML. The usage of most of those files will be explained along this tutorial.
121 .. exercise:: Module creation
123 Use the command line above to create an empty module Open Academy, and
128 #. Invoke the command ``odoo.py scaffold openacademy addons``.
129 #. Adapt the manifest file to your module.
130 #. Don't bother about the other files.
134 Object-Relational Mapping
135 -------------------------
137 A key component of Odoo is the :abbr:`ORM (Object-Relational Mapping)` layer.
138 This layer avoids having to write most :abbr:`SQL (Structured Query Language)`
139 by hand and provides extensibility and security services\ [#rawsql]_.
141 Business objects are declared as Python classes extending
142 :class:`~openerp.models.Model` which integrates them into the automated
145 Models can be configured by setting a number of attributes at their
146 definition. The most important attribute is
147 :attr:`~openerp.models.Model._name` which is required and defines the name for
148 the model in the Odoo system. Here is a minimally complete definition of a
151 from openerp import models
152 class MinimalModel(models.Model):
158 Fields are used to define what the model can store and where. Fields are
159 defined as attributes on the model class::
161 from openerp import models, fields
163 class LessMinimalModel(models.Model):
164 _name = 'test.model2'
171 Much like the model itself, its fields can be configured, by passing
172 configuration attributes as parameters::
174 name = field.Char(required=True)
176 Some attributes are available on all fields, here are the most common ones:
178 :attr:`~openerp.fields.Field.string` (``unicode``, default: field's name)
179 The label of the field in UI (visible by users).
180 :attr:`~openerp.fields.Field.required` (``bool``, default: ``False``)
181 If ``True``, the field can not be empty, it must either have a default
182 value or always be given a value when creating a record.
183 :attr:`~openerp.fields.Field.help` (``unicode``, default: ``''``)
184 Long-formm, provides a help tooltip to users in the UI.
185 :attr:`~openerp.fields.Field.index` (``bool``, default: ``False``)
186 Requests that Odoo create a `database index`_ on the column
191 There are two broad categories of fields: "simple" fields which are atomic
192 values stored directly in the model's table and "relational" fields linking
193 records (of the same model or of different models).
195 Example of simple fields are :class:`~openerp.fields.Boolean`,
196 :class:`~openerp.fields.Date`, :class:`~openerp.fields.Char`.
201 Odoo creates a few fields in all models\ [#autofields]_. These fields are
202 managed by the system and shouldn't be written to. They can be read if
205 :attr:`~openerp.fields.Model.id` (:class:`~openerp.fields.Id`)
206 the unique identifier for a record in its model
207 :attr:`~openerp.fields.Model.create_date` (:class:`~openerp.fields.Datetime`)
208 creation date of the record
209 :attr:`~openerp.fields.Model.create_uid` (:class:`~openerp.fields.Many2one`)
210 user who created the record
211 :attr:`~openerp.fields.Model.write_date` (:class:`~openerp.fields.Datetime`)
212 last modification date of the record
213 :attr:`~openerp.fields.Model.write_uid` (:class:`~openerp.fields.Many2one`)
214 user who last modified the record
219 By default, Odoo also requires a ``name`` field on all models for various
220 display and search behaviors. The field used for these purposes can be
221 overridden by setting :attr:`~openerp.models.Model._rec_name`.
223 .. exercise:: Define a model
225 Define a new data model *Course* in the *openacademy* module. A course
226 has a title and a description. Courses must have a title.
230 Edit the file ``openacademy/models.py`` to include a *Course* class.
237 Odoo is a highly data driven system. Although behavior is customized using
238 Python_ code part of a module's value is in the data it sets up when loaded.
240 .. tip:: some modules exist solely to add data into Odoo
243 Module data is declared via :ref:`data files <reference/data>`, XML files with
244 ``<record>`` elements. Each ``<record>`` element creates or updates a database
251 <record model="{model name}" id="{record identifier}">
252 <field name="{a field name}">{a value}</field>
257 * ``model`` is the name of the Odoo model for the record
258 * ``id`` is an :term:`external identifier`, it allows referring to the record
259 (without having to know its in-database identifier)
260 * ``<field>`` elements have a ``name`` which is the name of the field in the
261 model (e.g. ``description``). Their body is the field's value.
263 Data files have to be declared in the manifest file to be loaded, they can
264 be declared in the ``'data'`` list (always loaded) or in the ``'demo'`` list
265 (only loaded in demonstration mode).
267 .. exercise:: Define demonstration data
269 Create demonstration data filling the *Courses* model with a few
270 demonstration courses.
274 Edit the file ``openacademy/demo.xml`` to include some data.
281 Actions and menus are regular records in database, usually declared through
282 data files. Actions can be triggered in three ways:
284 #. by clicking on menu items (linked to specific actions)
285 #. by clicking on buttons in views (if these are connected to actions)
286 #. as contextual actions on object
288 Because menus are somewhat complex to declare there is a ``<menuitem>``
289 shortcut to declare an ``ir.ui.menu`` and connect it to the corresponding
294 <record model="ir.actions.act_window" id="action_list_ideas">
295 <field name="name">Ideas</field>
296 <field name="res_model">idea.idea</field>
297 <field name="view_mode">tree,form</field>
299 <menuitem id="menu_ideas" parent="menu_root" name="Ideas" sequence="10"
300 action="action_list_ideas"/>
305 The action must be declared before its corresponding menu in the XML file.
307 Data files are executed sequentially, the action's ``id`` must be present
308 in the database before the menu can be created.
310 .. exercise:: Define new menu entries
312 Define new menu entries to access courses and sessions under the
313 OpenAcademy menu entry. A user should be able to
315 - display a list of all the courses
316 - create/modify courses
320 #. Create ``openacademy/views/openacademy.xml`` with an action and
321 the menus triggering the action
322 #. Add it to the ``data`` list of ``openacademy/__openerp__.py``
329 Views define the way the records of a model are displayed. Each type of view
330 represents a mode of visualization (a list of records, a graph of their
331 aggregation, …). Views can either be requested generically via their type
332 (e.g. *a list of partners*) or specifically via their id. For generic
333 requests, the view with the correct type and the lowest priority will be
334 used (so the lowest-priority view of each type is the default view for that
337 :ref:`View inheritance <reference/views/inheritance>` allows altering views
338 declared elsewhere (adding or removing content).
340 Generic view declaration
341 ------------------------
343 A view is declared as a record of the model ``ir.ui.view``. The view type
344 is implied by the root element of the ``arch`` field:
348 <record model="ir.ui.view" id="view_id">
349 <field name="name">view.name</field>
350 <field name="model">object_name</field>
351 <field name="priority" eval="16"/>
352 <field name="arch" type="xml">
353 <!-- view content: <form>, <tree>, <graph>, ... -->
357 .. danger:: The view's content is XML.
360 The ``arch`` field must thus be declared as ``type="xml"`` to be parsed
366 Tree views, also called list views, display records in a tabular form.
368 Their root element is ``<tree>``. The simplest form of the tree view simply
369 lists all the fields to display in the table (each field as a column):
373 <tree string="Idea list">
375 <field name="inventor_id"/>
381 Forms are used to create and edit single records.
384 Their root element is ``<form>``. They composed of high-level structure
385 elements (groups, notebooks) and interactive elements (buttons and fields):
389 <form string="Idea form">
391 <group colspan="2" col="2">
392 <separator string="General stuff" colspan="2"/>
394 <field name="inventor_id"/>
397 <group colspan="2" col="2">
398 <separator string="Dates" colspan="2"/>
399 <field name="active"/>
400 <field name="invent_date" readonly="1"/>
403 <notebook colspan="4">
404 <page string="Description">
405 <field name="description" nolabel="1"/>
409 <field name="state"/>
413 .. exercise:: Customise form view using XML
415 Create your own form view for the Course object. Data displayed should be:
416 the name and the description of the course.
422 .. exercise:: Notebooks
424 In the Course form view, put the description field under a tab, such that
425 it will be easier to add other tabs later, containing additional
430 Modify the Course form view as follows:
434 Form views can also use plain HTML for more flexible layouts:
438 <form string="Idea Form">
440 <button string="Confirm" type="object" name="action_confirm"
441 states="draft" class="oe_highlight" />
442 <button string="Mark as done" type="object" name="action_done"
443 states="confirmed" class="oe_highlight"/>
444 <button string="Reset to draft" type="object" name="action_draft"
445 states="confirmed,done" />
446 <field name="state" widget="statusbar"/>
449 <div class="oe_title">
450 <label for="name" class="oe_edit_only" string="Idea Name" />
451 <h1><field name="name" /></h1>
453 <separator string="General" colspan="2" />
454 <group colspan="2" col="2">
455 <field name="description" placeholder="Idea description..." />
463 Search views customize the search field associated with the list view (and
464 other aggregated views). Their root element is ``<search>`` and they're
465 composed of fields defining which fields can be searched on:
471 <field name="inventor_id"/>
474 If no search view exists for the model, Odoo generates one which only allows
475 searching on the ``name`` field.
477 .. exercise:: Search courses
479 Allow searching for courses based on their title or their description.
485 Relations between models
486 ========================
488 A record from a model may be related to a record from another model. For
489 instance, a sale order record is related to a client record that contains the
490 client data; it is also related to its sale order line records.
492 .. exercise:: Create a session model
494 For the module Open Academy, we consider a model for *sessions*: a session
495 is an occurrence of a course taught at a given time for a given audience.
497 Create a model for *sessions*. A session has a name, a start date, a
498 duration and a number of seats. Add an action and a menu item to display
499 them. Make the new model visible via a menu item.
503 #. Create the class *Session* in ``openacademy/models.py``.
504 #. Add access to the session object in ``openacademy/view/openacademy.xml``.
508 .. note:: ``digits=(6, 2)`` specifies the precision of a float number:
509 6 is the total number of digits, while 2 is the number of
510 digits after the comma. Note that it results in the number
511 digits before the comma is a maximum 4
516 Relational fields link records, either of the same model (hierarchies) or
517 between different models.
519 Relational field types are:
521 :class:`Many2one(other_model, ondelete='set null') <openerp.fields.Many2one>`
522 A simple link to an other object::
524 print foo.other_id.name
526 .. seealso:: `foreign keys <http://www.postgresql.org/docs/9.3/static/tutorial-fk.html>`_
528 :class:`One2many(other_model, related_field) <openerp.fields.One2many>`
529 A virtual relationship, inverse of a :class:`~openerp.fields.Many2one`.
530 A :class:`~openerp.fields.One2many` behaves as a container of records,
531 accessing it results in a (possibly empty) set of records::
533 for other in foo.other_ids:
538 Because a :class:`~openerp.fields.One2many` is a virtual relationship,
539 there *must* be a :class:`~openerp.fields.Many2one` field in the
540 :samp:`{other_model}`, and its name *must* be :samp:`{related_field}`
542 :class:`Many2many(other_model) <openerp.fields.Many2many>`
543 Bidirectional multiple relationship, any record on one side can be related
544 to any number of records on the other side. Behaves as a container of
545 records, accessing it also results in a possibly empty set of records::
547 for other in foo.other_ids:
550 .. exercise:: Many2one relations
552 Using a many2one, modify the *Course* and *Session* models to reflect their
553 relation with other models:
555 - A course has a *responsible* user; the value of that field is a record of
556 the built-in model ``res.users``.
557 - A session has an *instructor*; the value of that field is a record of the
558 built-in model ``res.partner``.
559 - A session is related to a *course*; the value of that field is a record
560 of the model ``openacademy.course`` and is required.
565 #. Add the relevant ``Many2one`` fields to the models, and
566 #. add them in the views.
570 .. exercise:: Inverse one2many relations
572 Using the inverse relational field one2many, modify the models to reflect
573 the relation between courses and sessions.
577 #. Modify the ``Course`` class, and
578 #. add the field in the course form view.
582 .. exercise:: Multiple many2many relations
584 Using the relational field many2many, modify the *Session* model to relate
585 every session to a set of *attendees*. Attendees will be represented by
586 partner records, so we will relate to the built-in model ``res.partner``.
587 Adapt the views accordingly.
591 #. Modify the ``Session`` class, and
592 #. add the field in the form view.
602 Odoo provides two *inheritance* mechanisms to extend an existing model in a
605 The first inheritance mechanism allows a module to modify the behavior of a
606 model defined in another module:
608 - add fields to a model,
609 - override the definition of fields on a model,
610 - add constraints to a model,
611 - add methods to a model,
612 - override existing methods on a model.
614 The second inheritance mechanism (delegation) allows to link every record of a
615 model to a record in a parent model, and provides transparent access to the
616 fields of the parent record.
618 .. image:: backend/inheritance_methods.png
623 * :attr:`~openerp.models.Model._inherit`
624 * :attr:`~openerp.models.Model._inherits`
629 Instead of modifying existing views in place (by overwriting them), Odoo
630 provides view inheritance where children "extension" views are applied on top of
631 root views, and can add or remove content from their parent.
633 An extension view references its parent using the ``inherit_id`` field, and
634 instead of a single view its ``arch`` field is composed of any number of
635 ``xpath`` elements selecting and altering the content of their parent view:
639 <!-- improved idea categories list -->
640 <record id="idea_category_list2" model="ir.ui.view">
641 <field name="name">id.category.list2</field>
642 <field name="model">ir.ui.view</field>
643 <field name="inherit_id" ref="id_category_list"/>
644 <field name="arch" type="xml">
645 <!-- find field description inside tree, and add the field
646 idea_ids after it -->
647 <xpath expr="/tree/field[@name='description']" position="after">
648 <field name="idea_ids" string="Number of ideas"/>
654 An XPath_ expression selecting a single element in the parent view.
655 Raises an error if it matches no element or more than one
657 Operation to apply to the matched element:
660 appends ``xpath``'s body at the end of the matched element
662 replaces the matched element by the ``xpath``'s body
664 inserts the ``xpath``'s body as a sibling before the matched element
666 inserts the ``xpaths``'s body as a sibling after the matched element
668 alters the attributes of the matched element using special
669 ``attribute`` elements in the ``xpath``'s body
671 .. exercise:: Alter existing content
673 * Using model inheritance, modify the existing *Partner* model to add an
674 ``instructor`` boolean field, and a many2many field that corresponds to
675 the session-partner relation
676 * Using view inheritance, display this fields in the partner form view
682 This is the opportunity to introduce the developer mode to
683 inspect the view, find its external ID and the place to put the
686 #. Create a file ``openacademy/partner.py`` and import it in
688 #. Create a file ``openacademy/views/partner.xml`` and add it to
696 In Odoo, :ref:`reference/orm/domains` are values that encode conditions on
697 records. A domain is a list of criteria used to select a subset of a model's
698 records. Each criteria is a triple with a field name, an operator and a value.
700 For instance, when used on the *Product* model the following domain selects
701 all *services* with a unit price over *1000*::
703 [('product_type', '=', 'service'), ('unit_price', '>', 1000)]
705 By default criteria are combined with an implicit AND. The logical operators
706 ``&`` (AND), ``|`` (OR) and ``!`` (NOT) can be used to explicitly combine
707 criteria. They are used in prefix position (the operator is inserted before
708 its arguments rather than between). For instance to select products "which are
709 services *OR* have a unit price which is *NOT* between 1000 and 2000"::
712 ('product_type', '=', 'service'),
714 ('unit_price', '>=', 1000),
715 ('unit_price', '<', 2000)]
717 A ``domain`` parameter can be added to relational fields to limit valid
718 records for the relation when trying to select records in the client interface.
720 .. exercise:: Domains on relational fields
722 When selecting the instructor for a *Session*, only instructors (partners
723 with ``instructor`` set to ``True``) should be visible.
731 A domain declared as a literal list is evaluated server-side and
732 can't refer to dynamic values on the right-hand side, a domain
733 declared as a string is evaluated client-side and allows
734 field names on the right-hand side
736 .. exercise:: More complex domains
738 Create new partner categories *Teacher / Level 1* and *Teacher / Level 2*.
739 The instructor for a session can be either an instructor or a teacher
744 #. Modify the *Session* model's domain
745 #. Modify ``openacademy/view/partner.xml`` to get access to
746 *Partner categories*:
750 Computed fields and default values
751 ==================================
753 So far fields have been stored directly in and retrieved directly from the
754 database. Fields can also be *computed*. In that case, the field's value is not
755 retrieved from the database but computed on-the-fly by calling a method of the
758 To create a computed field, create a field and set its attribute
759 :attr:`~openerp.fields.Field.compute` to the name of a method. The computation
760 method should simply set the value of the field to compute on every record in
763 .. danger:: ``self`` is a collection
766 The object ``self`` is a *recordset*, i.e., an ordered collection of
767 records. It supports the standard Python operations on collections, like
768 ``len(self)`` and ``iter(self)``, plus extra set operations like ``recs1 +
771 Iterating over ``self`` gives the records one by one, where each record is
772 itself a collection of size 1. You can access/assign fields on single
773 records by using the dot notation, like ``record.name``.
775 .. code-block:: python
778 from openerp import models, fields
780 class ComputedModel(models.Model):
781 _name = 'test.computed'
783 name = fields.Char(compute='_compute_name')
785 def _compute_name(self):
787 record.name = str(random.randint(1, 1e6))
789 Our compute method is very simple: it loops over ``self`` and performs the same
790 operation on every record. We can make it slightly simpler by using the
791 decorator :func:`~openerp.api.one` to automatically loop on the collection::
794 def _compute_name(self):
795 self.name = str(random.randint(1, 1e6))
800 The value of a computed field usually depends on the values of other fields on
801 the computed record. The ORM expects the developer to specify those dependencies
802 on the compute method with the decorator :func:`~openerp.api.depends`.
803 The given dependencies are used by the ORM to trigger the recomputation of the
804 field whenever some of its dependencies have been modified::
806 from openerp import models, fields, api
808 class ComputedModel(models.Model):
809 _name = 'test.computed'
811 name = fields.Char(compute='_compute_name')
812 value = fields.Integer()
815 @api.depends('value')
816 def _compute_name(self):
817 self.name = "Record with value %s" % self.value
819 .. exercise:: Computed fields
821 * Add the percentage of taken seats to the *Session* model
822 * Display that field in the tree and form views
823 * Display the field as a progress bar
827 #. Add a computed field to *Session*
828 #. Show the field in the *Session* view:
835 Any field can be given a default value. In the field definition, add the option
836 ``default=X`` where ``X`` is either a Python literal value (boolean, integer,
837 float, string), or a function taking a recordset and returning a value::
839 name = fields.Char(default="Unknown")
840 user_id = fields.Many2one('res.users', default=lambda self: self.env.user)
842 .. exercise:: Active objects – Default values
844 * Define the start_date default value as today (see
845 :class:`~openerp.fields.Date`).
846 * Add a field ``active`` in the class Session, and set sessions as active by
855 Odoo has built-in rules making fields with an ``active`` field set
856 to ``False`` invisible.
861 The "onchange" mechanism provides a way for the client interface to update a
862 form whenever the user has filled in a value in a field, without saving anything
865 For instance, suppose a model has three fields ``amount``, ``unit_price`` and
866 ``price``, and you want to update the price on the form when any of the other
867 fields is modified. To achieve this, define a method where ``self`` represents
868 the record in the form view, and decorate it with :func:`~openerp.api.onchange`
869 to specify on which field it has to be triggered. Any change you make on
870 ``self`` will be reflected on the form.
874 <!-- content of form view -->
875 <field name="amount"/>
876 <field name="unit_price"/>
877 <field name="price" readonly="1"/>
879 .. code-block:: python
882 @api.onchange('amount', 'unit_price')
883 def _onchange_price(self):
884 # set auto-changing field
885 self.price = self.amount * self.unit_price
886 # Can optionally return a warning and domains
889 'title': "Something bad happened",
890 'message': "It was very bad indeed",
894 For computed fields, valued ``onchange`` behavior is built-in as can be seen by
895 playing with the *Session* form: change the number of seats or participants, and
896 the ``taken_seats`` progressbar is automatically updated.
898 .. exercise:: Warning
900 Add an explicit onchange to warn about invalid values, like a negative
901 number of seats, or more participants than seats.
910 Odoo provides two ways to set up automatically verified invariants:
911 :func:`Python constraints <openerp.api.constrains>` and
912 :attr:`SQL constaints <openerp.models.Model._sql_constraints>`.
914 A Python constraint is defined as a method decorated with
915 :func:`~openerp.api.constrains`, and invoked on a recordset. The decorator
916 specifies which fields are involved in the constraint, so that the constraint is
917 automatically evaluated when one of them is modified. The method is expected to
918 raise an exception if its invariant is not satisfied::
920 from openerp.exceptions import ValidationError
922 @api.constrains('age')
923 def _check_something(self):
926 raise ValidationError("Your record is too old: %s" % record.age)
927 # all records passed the test, don't return anything
929 .. exercise:: Add Python constraints
931 Add a constraint that checks that the instructor is not present in the
932 attendees of his/her own session.
938 SQL constraints are defined through the model attribute
939 :attr:`~openerp.models.Model._sql_constraints`. The latter is assigned to a list
940 of triples of strings ``(name, sql_definition, message)``, where ``name`` is a
941 valid SQL constraint name, ``sql_definition`` is a table_constraint_ expression,
942 and ``message`` is the error message.
944 .. exercise:: Add SQL constraints
946 With the help of `PostgreSQL's documentation`_ , add the following
949 #. CHECK that the course description and the course title are different
950 #. Make the Course's name UNIQUE
956 .. exercise:: Exercise 6 - Add a duplicate option
958 Since we added a constraint for the Course name uniqueness, it is not
959 possible to use the "duplicate" function anymore (:menuselection:`Form -->
962 Re-implement your own "copy" method which allows to duplicate the Course
963 object, changing the original name into "Copy of [original name]".
975 Tree views can take supplementary attributes to further customize their
979 mappings of colors to conditions. If the condition evaluates to ``True``,
980 the corresponding color is applied to the row:
984 <tree string="Idea Categories" colors="blue:state=='draft';red:state=='trashed'">
986 <field name="state"/>
989 Clauses are separated by ``;``, the color and condition are separated by
993 Either ``"top"`` or ``"bottom"``. Makes the tree view editable in-place
994 (rather than having to go through the form view), the value is the
995 position where new rows appear.
997 .. exercise:: List coloring
999 Modify the Session tree view in such a way that sessions lasting less than
1000 5 days are colored blue, and the ones lasting more than 15 days are
1005 Modify the session tree view:
1012 Displays records as calendar events. Their root element is ``<calendar>`` and
1013 their most common attributes are:
1016 The name of the field used for *color segmentation*. Colors are
1017 automatically distributed to events, but events in the same color segment
1018 (records which have the same value for their ``@color`` field) will be
1019 given the same color.
1021 record's field holding the start date/time for the event
1022 ``date_stop`` (optional)
1023 record's field holding the end date/time for the event
1025 field (to define the label for each calendar event)
1029 <calendar string="Ideas" date_start="invent_date" color="inventor_id">
1030 <field name="name"/>
1033 .. exercise:: Calendar view
1035 Add a Calendar view to the *Session* model enabling the user to view the
1036 events associated to the Open Academy.
1040 #. Add an ``end_date`` field computed from ``start_date`` and
1043 .. tip:: the inverse function makes the field writable, and allows
1044 moving the sessions (via drag and drop) in the calendar view
1046 #. Add a calendar view to the *Session* model
1047 #. And add the calendar view to the *Session* model's actions
1054 Search view fields can take custom operators or :ref:`reference/orm/domains`
1055 for more flexible matching of results.
1057 Search views can also contain *filters* which act as toggles for predefined
1058 searches (defined using :ref:`reference/orm/domains`):
1062 <search string="Ideas">
1063 <filter name="my_ideas" domain="[('inventor_id','=',uid)]"
1064 string="My Ideas" icon="terp-partner"/>
1065 <field name="name"/>
1066 <field name="description"/>
1067 <field name="inventor_id"/>
1068 <field name="country_id" widget="selection"/>
1071 To use a non-default search view in an action, it should be linked using the
1072 ``search_view_id`` field of the action record.
1074 The action can also set default values for search fields through its
1075 ``context`` field: context keys of the form
1076 :samp:`search_default_{field_name}` will initialize *field_name* with the
1077 provided value. Search filters must have an optional ``@name`` to have a
1078 default and behave as booleans (they can only be enabled by default).
1080 .. exercise:: Search views
1082 Add a button to filter the courses for which the current user is the
1083 responsible in the course search view. Make it selected by default.
1092 Horizontal bar charts typically used to show project planning and advancement,
1093 their root element is ``<gantt>``.
1097 <gantt string="Ideas" date_start="invent_date" color="inventor_id">
1098 <level object="idea.idea" link="id" domain="[]">
1099 <field name="inventor_id"/>
1103 .. exercise:: Gantt charts
1105 Add a Gantt Chart enabling the user to view the sessions scheduling linked
1106 to the Open Academy module. The sessions should be grouped by instructor.
1110 #. Create a computed field expressing the session's duration in hours
1111 #. Add the gantt view's definition, and add the gantt view to the
1112 *Session* model's action
1119 Graph views allow aggregated overview and analysis of models, their root
1120 element is ``<graph>``.
1122 Graph views have 4 display modes, the default mode is selected using the
1123 ``@type`` attribute.
1126 a multidimensional table, allows the selection of filers and dimensions
1127 to get the right aggregated dataset before moving to a more graphical
1130 a bar chart, the first dimension is used to define groups on the
1131 horizontal axis, other dimensions define aggregated bars within each group.
1133 By default bars are side-by-side, they can be stacked by using
1134 ``@stacked="True"`` on the ``<graph>``
1136 2-dimensional line chart
1140 Graph views contain ``<field>`` with a mandatory ``@type`` attribute taking
1144 the field should be aggregated by default
1146 the field should be aggregated rather than grouped on
1150 <graph string="Total idea score by Inventor">
1151 <field name="inventor_id"/>
1152 <field name="score" type="measure"/>
1157 Graph views perform aggregations on database values, they do not work
1158 with non-stored computed fields.
1160 .. exercise:: Graph view
1162 Add a Graph view in the Session object that displays, for each course, the
1163 number of attendees under the form of a bar chart.
1167 #. Add the number of attendees as a stored computed field
1168 #. Then add the relevant view
1175 Used to organize tasks, production processes, etc… their root element is
1178 A kanban view shows a set of cards possibly grouped in columns. Each card
1179 represents a record, and each column the values of an aggregation field.
1181 For instance, project tasks may be organized by stage (each column is a
1182 stage), or by responsible (each column is a user), and so on.
1184 Kanban views define the structure of each card as a mix of form elements
1185 (including basic HTML) and :ref:`reference/qweb`.
1187 .. exercise:: Kanban view
1189 Add a Kanban view that displays sessions grouped by course (columns are
1194 #. Add an integer ``color`` field to the *Session* model
1195 #. Add the kanban view and update the action
1202 Workflows are models associated to business objects describing their dynamics.
1203 Workflows are also used to track processes that evolve over time.
1205 .. exercise:: Almost a workflow
1207 Add a ``state`` field to the *Session* model. It will be used to define
1210 A sesion can have three possible states: Draft (default), Confirmed and
1213 In the session form, add a (read-only) field to
1214 visualize the state, and buttons to change it. The valid transitions are:
1223 #. Add a new ``state`` field
1224 #. Add state-transitioning methods, those can be called from view
1225 buttons to change the record's state
1226 #. And add the relevant buttons to the session's form view
1230 Workflows may be associated with any object in Odoo, and are entirely
1231 customizable. Workflows are used to structure and manage the lifecycles of
1232 business objects and documents, and define transitions, triggers, etc. with
1233 graphical tools. Workflows, activities (nodes or actions) and transitions
1234 (conditions) are declared as XML records, as usual. The tokens that navigate
1235 in workflows are called workitems.
1237 .. exercise:: Workflow
1239 Replace the ad-hoc *Session* workflow by a real workflow. Transform the
1240 *Session* form view so its buttons call the workflow instead of the
1249 A workflow associated with a model is only created when the
1250 model's records are created. Thus there is no workflow instance
1251 associated with session instances created before the workflow's
1256 In order to check if instances of the workflow are correctly
1257 created alongside sessions, go to :menuselection:`Settings -->
1258 Technical --> Workflows --> Instances`
1262 .. exercise:: Automatic transitions
1264 Automatically transition sessions from *Draft* to *Confirmed* when more
1265 than half the session's seats are reserved.
1271 .. exercise:: Server actions
1273 Replace the Python methods for synchronizing session state by
1276 Both the workflow and the server actions could have been created entirely
1286 Access control mechanisms must be configured to achieve a coherent security
1289 Group-based access control mechanisms
1290 -------------------------------------
1292 Groups are created as normal records on the model “res.groups”, and granted
1293 menu access via menu definitions. However even without a menu, objects may
1294 still be accessible indirectly, so actual object-level permissions (read,
1295 write, create, unlink) must be defined for groups. They are usually inserted
1296 via CSV files inside modules. It is also possible to restrict access to
1297 specific fields on a view or object using the field's groups attribute.
1302 Access rights are defined as records of the model “ir.model.access”. Each
1303 access right is associated to a model, a group (or no group for global
1304 access), and a set of permissions: read, write, create, unlink. Such access
1305 rights are usually created by a CSV file named after its model:
1306 ``ir.model.access.csv``.
1308 .. code-block:: text
1310 id,name,model_id/id,group_id/id,perm_read,perm_write,perm_create,perm_unlink
1311 access_idea_idea,idea.idea,model_idea_idea,base.group_user,1,1,1,0
1312 access_idea_vote,idea.vote,model_idea_vote,base.group_user,1,1,1,0
1314 .. exercise:: Add access control through the OpenERP interface
1316 Create a new user "John Smith". Then create a group
1317 "OpenAcademy / Session Read" with read access to the *Session* model.
1321 #. Create a new user *John Smith* through
1322 :menuselection:`Settings --> Users --> Users`
1323 #. Create a new group ``session_read`` through
1324 :menuselection:`Settings --> Users --> Groups`, it should have
1325 read access on the *Session* model
1326 #. Edit *John Smith* to make them a member of ``session_read``
1327 #. Log in as *John Smith* to check the access rights are correct
1329 .. exercise:: Add access control through data files in your module
1333 * Create a group *OpenAcademy / Manager* with full access to all
1335 * Make *Session* and *Course* readable by all users
1339 #. Create a new file ``openacademy/security/security.xml`` to
1340 hold the OpenAcademy Manager group
1341 #. Edit the file ``openacademy/security/ir.model.access.csv`` with
1342 the access rights to the models
1343 #. Finally update ``openacademy/__openerp__.py`` to add the new data
1351 A record rule restricts the access rights to a subset of records of the given
1352 model. A rule is a record of the model “ir.rule”, and is associated to a
1353 model, a number of groups (many2many field), permissions to which the
1354 restriction applies, and a domain. The domain specifies to which records the
1355 access rights are limited.
1357 Here is an example of a rule that prevents the deletion of leads that are not
1358 in state “cancel”. Notice that the value of the field “groups” must follow
1359 the same convention as the method “write” of the ORM.
1363 <record id="delete_cancelled_only" model="ir.rule">
1364 <field name="name">Only cancelled leads may be deleted</field>
1365 <field name="model_id" ref="crm.model_crm_lead"/>
1366 <field name="groups" eval="[(4, ref('base.group_sale_manager'))]"/>
1367 <field name="perm_read" eval="0"/>
1368 <field name="perm_write" eval="0"/>
1369 <field name="perm_create" eval="0"/>
1370 <field name="perm_unlink" eval="1" />
1371 <field name="domain_force">[('state','=','cancel')]</field>
1374 .. exercise:: Record rule
1376 Add a record rule for the model Course and the group
1377 "OpenAcademy / Manager", that restricts ``write`` and ``unlink`` accesses
1378 to the responsible of a course. If a course has no responsible, all users
1379 of the group must be able to modify it.
1383 Create a new rule in ``openacademy/security/security.xml``:
1387 Internationalization
1388 ====================
1390 Each module can provide its own translations within the i18n directory, by
1391 having files named LANG.po where LANG is the locale code for the language, or
1392 the language and country combination when they differ (e.g. pt.po or
1393 pt_BR.po). Translations will be loaded automatically by Odoo for all
1394 enabled languages. Developers always use English when creating a module, then
1395 export the module terms using Odoo's gettext POT export feature
1396 (:menuselection:`Settings --> Translations --> Import/Export --> Export
1397 Translation` without specifying a language), to create the module template POT
1398 file, and then derive the translated PO files. Many IDE's have plugins or modes
1399 for editing and merging PO/POT files.
1401 .. tip:: The GNU gettext format (Portable Object) used by Odoo is
1402 integrated into LaunchPad, making it an online collaborative
1403 translation platform.
1405 .. code-block:: text
1407 |- idea/ # The module directory
1408 |- i18n/ # Translation files
1409 | - idea.pot # Translation Template (exported from Odoo)
1410 | - fr.po # French translation
1411 | - pt_BR.po # Brazilian Portuguese translation
1416 By default Odoo's POT export only extracts labels inside XML files or
1417 inside field definitions in Python code, but any Python string can be
1418 translated this way by surrounding it with the function :func:`openerp._`
1419 (e.g. ``_("Label")``)
1421 .. exercise:: Translate a module
1423 Choose a second language for your Odoo installation. Translate your
1424 module using the facilities provided by Odoo.
1428 #. Create a directory ``openacademy/i18n/``
1429 #. Install whichever language you want (
1430 :menuselection:`Administration --> Translations --> Load an
1431 Official Translation`)
1432 #. Synchronize translatable terms (:menuselection:`Administration -->
1433 Translations --> Application Terms --> Synchronize Translations`)
1434 #. Create a template translation file by exporting (
1435 :menuselection:`Administration --> Translations -> Import/Export
1436 --> Export Translation`) without specifying a language, save in
1437 ``openacademy/i18n/``
1438 #. Create a translation file by exporting (
1439 :menuselection:`Administration --> Translations --> Import/Export
1440 --> Export Translation`) and specifying a language. Save it in
1441 ``openacademy/i18n/``
1442 #. Open the exported translation file (with a basic text editor or a
1443 dedicated PO-file editor e.g. POEdit_ and translate the missing
1446 #. Add ``from openerp import _`` to ``course.py`` and
1447 mark missing strings as translatable
1453 .. todo:: do we never reload translations?
1462 Odoo 8.0 comes with a new report engine based on :ref:`reference/qweb`,
1463 `Twitter Bootstrap`_ and Wkhtmltopdf_.
1465 A report is a combination two elements:
1467 * an ``ir.actions.report.xml``, for which a ``<report>`` shortcut element is
1468 provided, it sets up various basic parameters for the report (default
1469 type, whether the report should be saved to the database after generation,…)
1475 id="account_invoices"
1476 model="account.invoice"
1478 report_type="qweb-pdf"
1479 name="account.report_invoice"
1480 file="account.report_invoice"
1481 attachment_use="True"
1482 attachment="(object.state in ('open','paid')) and
1483 ('INV'+(object.number or '').replace('/','')+'.pdf')"
1486 * A standard :ref:`QWeb view <reference/views/qweb>` for the actual report:
1490 <t t-call="report.html_container">
1491 <t t-foreach="docs" t-as="o">
1492 <t t-call="report.external_layout">
1494 <h2>Report title</h2>
1500 the standard rendering context provides a number of elements, the most
1504 the records for which the report is printed
1506 the user printing the report
1508 Because reports are standard web pages, they are available through a URL and
1509 output parameters can be manipulated through this URL, for instance the HTML
1510 version of the *Invoice* report is available through
1511 http://localhost:8069/report/html/account.report_invoice/1 (if ``account`` is
1512 installed) and the PDF version through
1513 http://localhost:8069/report/pdf/account.report_invoice/1.
1515 .. exercise:: Create a report for the Session model
1517 For each session, it should display session's name, its start and end,
1518 and list the session's attendees.
1527 .. exercise:: Define a Dashboard
1529 Define a dashboard containing the graph view you created, the sessions
1530 calendar view and a list view of the courses (switchable to a form
1531 view). This dashboard should be available through a menuitem in the menu,
1532 and automatically displayed in the web client when the OpenAcademy main
1537 #. Create a file ``openacademy/views/session_board.xml``. It should contain
1538 the board view, the actions referenced in that view, an action to
1539 open the dashboard and a re-definition of the main menu item to add
1540 the dashboard action
1542 .. note:: Available dashboard styles are ``1``, ``1-1``, ``1-2``,
1543 ``2-1`` and ``1-1-1``
1545 #. Update ``openacademy/__openerp__.py`` to reference the new data
1553 The web-service module offer a common interface for all web-services :
1558 Business objects can also be accessed via the distributed object
1559 mechanism. They can all be modified via the client interface with contextual
1562 Odoo is accessible through XML-RPC/JSON-RPC interfaces, for which libraries
1563 exist in many languages.
1568 The following example is a Python program that interacts with an Odoo
1569 server with the library xmlrpclib.
1575 root = 'http://%s:%d/xmlrpc/' % (HOST, PORT)
1577 uid = xmlrpclib.ServerProxy(root + 'common').login(db, username, password)
1578 print "Logged in as %s (uid: %d)" % (USER, uid)
1581 sock = xmlrpclib.ServerProxy(root + 'object')
1583 'name' : 'Another idea',
1584 'description' : 'This is another idea of mine',
1587 idea_id = sock.execute(db, uid, password, 'idea.idea', 'create', args)
1589 .. exercise:: Add a new service to the client
1591 Write a Python program able to send XML-RPC requests to a PC running
1592 Odoo (yours, or your instructor's). This program should display all
1593 the sessions, and their corresponding number of seats. It should also
1594 create a new session for one of the courses.
1598 .. code-block:: python
1607 ROOT = 'http://%s:%d/xmlrpc/' % (HOST,PORT)
1610 uid = xmlrpclib.ServerProxy(ROOT + 'common').login(DB,USER,PASS)
1611 print "Logged in as %s (uid:%d)" % (USER,uid)
1613 call = functools.partial(
1614 xmlcprlib.ServerProxy(ROOT + 'object').execute,
1617 # 2. Read the sessions
1618 sessions = call('openacademy.session','search_read', [], ['name','seats'])
1619 for session in sessions :
1620 print "Session %s (%s seats)" % (session['name'], session['seats'])
1621 # 3.create a new session
1622 session_id = call('openacademy.session', 'create', {
1623 'name' : 'My session',
1627 Instead of using a hard-coded course id, the code can look up a course
1630 # 3.create a new session for the "Functional" course
1631 course_id = call('openacademy.course', 'search', [('name','ilike','Functional')])[0]
1632 session_id = call('openacademy.session', 'create', {
1633 'name' : 'My session',
1634 'course_id' : course_id,
1637 .. note:: there are also a number of high-level APIs in various languages to
1638 access Odoo systems without *explicitly* going through XML-RPC e.g.
1640 * https://github.com/akretion/ooor
1641 * https://github.com/syleam/openobject-library
1642 * https://github.com/nicolas-van/openerp-client-lib
1643 * https://pypi.python.org/pypi/oersted/
1645 .. [#autofields] it is possible to :attr:`disable the automatic creation of some
1646 fields <openerp.models.Model._log_access>`
1647 .. [#rawsql] writing raw SQL queries is possible, but requires care as it
1648 bypasses all Odoo authentication and security mechanisms.
1651 http://use-the-index-luke.com/sql/preface
1653 .. _POEdit: http://poedit.net
1655 .. _PostgreSQL's documentation:
1656 .. _table_constraint:
1657 http://www.postgresql.org/docs/9.3/static/ddl-constraints.html
1659 .. _python: http://python.org
1661 .. _XPath: http://w3.org/TR/xpath
1663 .. _twitter bootstrap: http://getbootstrap.com
1665 .. _wkhtmltopdf: http://wkhtmltopdf.org