+.. _module-dev-structure:
+
Module structure
================
you will shortcut important steps like constraints checking or workflow
modification.
-.. figure:: images/pom_3_0_3.png
- :scale: 50
- :align: center
+.. .. figure:: images/pom_3_0_3.png
+.. :scale: 50
+.. :align: center
- *The Physical Objects Model of [OpenERP version 3.0.3]*
+.. *The Physical Objects Model of [OpenERP version 3.0.3]*
XML Files
</data>
</openerp>
-Record Tag
-//////////
+``<record>``
+////////////
+
+Defines a new record in a specified OpenERP model.
-**Description**
+``@model`` (required)
-The addition of new data is made with the record tag. This one takes a
-mandatory attribute : model. Model is the object name where the insertion has
-to be done. The tag record can also take an optional attribute: id. If this
-attribute is given, a variable of this name can be used later on, in the same
-file, to make reference to the newly created resource ID.
+ Name of the model in which this record will be created/inserted.
-A record tag may contain field tags. They indicate the record's fields value.
-If a field is not specified the default value will be used.
+``@id`` (optional)
-The Record Field tag
-////////////////////
+ :term:`external ID` for the record, also allows referring to this record in
+ the rest of this file or in other files (through ``field/@ref`` or the
+ :py:func:`ref() <openerp.tools.convert._ref>` function)
-The attributes for the field tag are the following:
+A record tag generally contains multiple ``field`` tags specifying the values
+set on the record's fields when creating it. Fields left out will be set to
+their default value unless required.
-name : mandatory
- the field name
+``<field>``
+///////////
+
+In its most basic use, the ``field`` tag will set its body (as a string) as
+the value of the corresponding ``record``'s ``@name`` field.
+
+Extra attributes can either preprocess the body or replace its use entirely:
+
+``@name`` (mandatory)
+
+ Name of the field in the containing ``record``'s model
+
+``@type`` (optional)
+
+ One of ``char``, ``int``, ``float``, ``list``, ``tuple``, ``xml`` or
+ ``html``, ``file`` or ``base64``. Converts the ``field``'s body to the
+ specified type (or validates the body's content)
-eval : optional
- python expression that indicating the value to add
-
-ref
- reference to an id defined in this file
+ * ``xml`` will join multiple XML nodes under a single ``<data>`` root
+ * in ``xml`` and ``html``, external ids can be referenced using
+ ``%(id_name)s``
+ * ``list`` and ``tuple``'s element are specified using ``<value>``
+ sub-nodes with the same attributes as ``field``.
+ * ``file`` expects a module-local path and will save the path prefixed with
+ the current module's name, separated by a ``,`` (comma). For use with
+ :py:func:`~openerp.modules.module.get_module_resource`.
+ * ``base64`` expects binary data, encodes it to base64 and sets it. Mostly
+ useful with ``@file``
-model
- model to be looked up in the search
+``@file``
-search
- a query
+ Can be used with types ``char`` and ``base64``, sources the field's content
+ from the specified file instead of the field's text body.
+``@model``
+
+ Model used for ``@search``'s search, or registry object put in context for
+ ``@eval``. Required if ``@search`` but optional if ``@eval``.
+
+``@eval`` (optional)
+
+ A Python expression evaluated to obtain the value to set on the record
+
+``@ref`` (optional)
+
+ Links to an other record through its :term:`external id`. The module prefix
+ may be ommitted to link to a record defined in the same module.
+
+``@search`` (optional)
+
+ Search domain (evaluated Python expression) into ``@model`` to get the
+ records to set on the field.
+
+ Sets all the matches found for m2m fields, the first id for other field
+ types.
**Example**
* The client asks (with XML-RPC) to the server what views are defined for the invoice object and what are the data it must show.
* The client displays the form according to the view
-.. figure:: images/arch_view_use.png
- :scale: 50
- :align: center
+.. .. figure:: images/arch_view_use.png
+.. :scale: 50
+.. :align: center
To develop new objects
//////////////////////
Below is an example workflow used for sale orders. It must generate invoices and shipments according to certain conditions.
-.. figure:: images/arch_workflow_sale.png
- :scale: 85
- :align: center
+.. .. figure:: images/arch_workflow_sale.png
+.. :scale: 85
+.. :align: center
In this graph, the nodes represent the actions to be done: