[DOC] [REF] Refactoring of the module chapter, still WIP ...
bzr revid: tde@openerp.com-20120417172034-h5pzpiair5sk94wz
This commit is contained in:
parent
c57660ae79
commit
c472efa688
|
@ -1,32 +1,53 @@
|
||||||
Module development
|
Module structure
|
||||||
==================
|
================
|
||||||
|
|
||||||
Module Structure
|
A module can contain the following elements:
|
||||||
+++++++++++++++++
|
|
||||||
|
|
||||||
All the modules are located in the source/addons directory. The following
|
- **Business object** : declared as Python classes extending the OpenObject c
|
||||||
steps are necessary to create a new module:
|
lass osv.Model, the persistence of these resource is completly managed
|
||||||
|
by OpenObject,
|
||||||
|
- **Data** : XML/CSV files with meta-data (views and workflows declaration),
|
||||||
|
configuration data (modules parametrization) and demo data (optional but
|
||||||
|
recommended for testing),
|
||||||
|
- **Wizards** : stateful interactive forms used to assist users, often available
|
||||||
|
as contextual actions on resources,
|
||||||
|
- **Reports** : RML (XML format). MAKO or OpenOffice report templates, to be
|
||||||
|
merged with any kind of business data, and generate HTML, ODT or PDF reports.
|
||||||
|
|
||||||
* create a subdirectory in the source/addons directory
|
.. figure:: _static/03_module_gen_view.png
|
||||||
* create the import **__init__.py** file
|
:width: 75%
|
||||||
* create a module description file: **__openerp__.py**
|
:alt: Module composition
|
||||||
* create the **Python** file containing the **objects**
|
:align: center
|
||||||
* create **.xml files** that create the data (views, menu entries, demo data, ...)
|
|
||||||
* optionally create **reports**, **wizards** or **workflows**.
|
Module composition
|
||||||
|
|
||||||
Python Module Descriptor File __init__.py
|
Each module is contained in its own directory within either the server/bin/addons
|
||||||
-----------------------------------------
|
directory or another directory of addons, configured in server installation.
|
||||||
|
To create a new module, the following steps are required:
|
||||||
|
|
||||||
The ``__init__.py`` file is, like any Python module, executed at the start
|
- create a ``my_module`` subdirectory in the source/addons directory
|
||||||
of the program. It needs to import the Python files that need to be loaded.
|
- create the module description file ``__init__.py``
|
||||||
|
- create the module declaration file ``__openerp__.py``
|
||||||
|
- create **Python** files containing **objects**
|
||||||
|
- create **.xml files** holding module data such as views, menu entries
|
||||||
|
or demo data
|
||||||
|
- optionally create **reports**, **wizards** or **workflows**
|
||||||
|
|
||||||
So, if you create a "module.py" file, containing the description of your
|
Description file __init__.py
|
||||||
objects, you have to write one line in __init__.py::
|
++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
The ``__init__.py`` file is the Python module descriptor, because an OpenERP
|
||||||
|
module is also a regular Python module. Like any Python module, it is executed
|
||||||
|
at program start. It needs to import the Python files that need to be loaded.
|
||||||
|
|
||||||
|
It contains the importation instruction applied to all Python files of the
|
||||||
|
module, without the .py extension. For example, if a module contains a single
|
||||||
|
python file named ``mymodule.py``, the file should look like:
|
||||||
|
|
||||||
import module
|
import module
|
||||||
|
|
||||||
OpenERP Module Descriptor File __openerp__.py
|
Declaration file __openerp__.py
|
||||||
---------------------------------------------
|
+++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
In the created module directory, you must add a **__openerp__.py** file.
|
In the created module directory, you must add a **__openerp__.py** file.
|
||||||
This file, which must be in Python format, is responsible to
|
This file, which must be in Python format, is responsible to
|
||||||
|
@ -37,76 +58,55 @@ This file, which must be in Python format, is responsible to
|
||||||
|
|
||||||
This file must contain a Python dictionary with the following values:
|
This file must contain a Python dictionary with the following values:
|
||||||
|
|
||||||
**name**
|
::
|
||||||
|
|
||||||
The (Plain English) name of the module.
|
name The (Plain English) name of the module.
|
||||||
|
version The version of the module.
|
||||||
|
description The module description (text).
|
||||||
|
author The author of the module.
|
||||||
|
website The website of the module.
|
||||||
|
license The license of the module (default:GPL-2).
|
||||||
|
depends List of modules on which this module depends. The base
|
||||||
|
module must almost always be in the dependencies because
|
||||||
|
some necessary data for the views, reports, ... are in
|
||||||
|
the base module.
|
||||||
|
init_xml List of .xml files to load when the server is launched
|
||||||
|
with the "--init=module" argument. Filepaths must be
|
||||||
|
relative to the directory where the module is. OpenERP
|
||||||
|
XML file format is detailed in this section.
|
||||||
|
update_xml List of .xml files to load when the server is launched with
|
||||||
|
the "--update=module" launched. Filepaths must be relative
|
||||||
|
to the directory where the module is. Files in **update_xml**
|
||||||
|
concern: views, reports and wizards.
|
||||||
|
installable True or False. Determines whether the module is installable
|
||||||
|
or not.
|
||||||
|
auto_install True or False (default: False). If set to ``True``, the
|
||||||
|
module is a link module. It will be installed as soon
|
||||||
|
as all its dependencies are installed.
|
||||||
|
|
||||||
**version**
|
For the ``my_module`` module, here is an example of ``__openerp__.py``
|
||||||
|
declaration file:
|
||||||
The version of the module.
|
|
||||||
|
|
||||||
**description**
|
|
||||||
|
|
||||||
The module description (text).
|
|
||||||
|
|
||||||
**author**
|
|
||||||
|
|
||||||
The author of the module.
|
|
||||||
|
|
||||||
**website**
|
|
||||||
|
|
||||||
The website of the module.
|
|
||||||
|
|
||||||
**license**
|
|
||||||
|
|
||||||
The license of the module (default:GPL-2).
|
|
||||||
|
|
||||||
**depends**
|
|
||||||
|
|
||||||
List of modules on which this module depends. The base module must
|
|
||||||
almost always be in the dependencies because some necessary data for
|
|
||||||
the views, reports, ... are in the base module.
|
|
||||||
|
|
||||||
**init_xml**
|
|
||||||
|
|
||||||
List of .xml files to load when the server is launched with the "--init=module"
|
|
||||||
argument. Filepaths must be relative to the directory where the module is.
|
|
||||||
OpenERP XML File Format is detailed in this section.
|
|
||||||
|
|
||||||
**update_xml**
|
|
||||||
|
|
||||||
List of .xml files to load when the server is launched with the "--update=module"
|
|
||||||
launched. Filepaths must be relative to the directory where the module is.
|
|
||||||
OpenERP XML File Format is detailed in this section. The files in **update_xml**
|
|
||||||
concern: views, reports and wizards.
|
|
||||||
|
|
||||||
**installable**
|
|
||||||
|
|
||||||
True or False. Determines if the module is installable or not.
|
|
||||||
|
|
||||||
**active**
|
|
||||||
|
|
||||||
True or False (default: False). Determines the modules that are installed
|
|
||||||
on the database creation.
|
|
||||||
|
|
||||||
**Example**
|
|
||||||
|
|
||||||
Here is an example of __openerp__.py file for the product module
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
{
|
{
|
||||||
"name" : "Products & Pricelists",
|
'name' : "My Module",
|
||||||
"version" : "1.1",
|
'version' : "1.0",
|
||||||
"author" : "Open",
|
'author' : "OpenERP",
|
||||||
"category" : "Generic Modules/Inventory Control",
|
'category' : "Tools",
|
||||||
"depends" : ["base", "account"],
|
'depends' : ['base',],
|
||||||
"init_xml" : [],
|
'init_xml' : [],
|
||||||
"demo_xml" : ["product_demo.xml"],
|
'demo_xml' : [
|
||||||
"update_xml" : ["product_data.xml", "product_report.xml", "product_wizard.xml",
|
'module_demo.xml'
|
||||||
"product_view.xml", "pricelist_view.xml"],
|
],
|
||||||
"installable": True,
|
'update_xml' : [
|
||||||
"active": True
|
'module_view.xml',
|
||||||
|
'data/module_data.xml',
|
||||||
|
'report/module_report.xml',
|
||||||
|
'wizard/module_wizard.xml',
|
||||||
|
],
|
||||||
|
'installable': True,
|
||||||
|
'auto_install': False,
|
||||||
}
|
}
|
||||||
|
|
||||||
The files that must be placed in init_xml are the ones that relate to the
|
The files that must be placed in init_xml are the ones that relate to the
|
||||||
|
@ -546,52 +546,23 @@ which corresponds to the tools profile in OpenERP.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Action creation
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Linking events to action
|
|
||||||
++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The available type of events are:
|
|
||||||
|
|
||||||
* **client_print_multi** (print from a list or form)
|
Appendix
|
||||||
* **client_action_multi** (action from a list or form)
|
+++++++++
|
||||||
* **tree_but_open** (double click on the item of a tree, like the menu)
|
|
||||||
* **tree_but_action** (action on the items of a tree)
|
|
||||||
|
|
||||||
To map an events to an action:
|
Configure addons locations
|
||||||
|
--------------------------
|
||||||
|
|
||||||
.. code-block:: xml
|
By default, the only directory of addons known by the server is server/bin/addons.
|
||||||
|
It is possible to add new addons by
|
||||||
|
|
||||||
<record model="ir.values" id="ir_open_journal_period">
|
- copying them in server/bin/addons, or creating a symbolic link to each
|
||||||
<field name="key2">tree_but_open</field>
|
of them in this directory, or
|
||||||
<field name="model">account.journal.period</field>
|
- specifying another directory containing addons to the server. The later
|
||||||
<field name="name">Open Journal</field>
|
can be accomplished either by running the server with the ``--addons-path=``
|
||||||
<field name="value" eval="'ir.actions.wizard,%d'%action_move_journal_line_form_select"/>
|
option, or by configuring this option in the openerp_serverrc file,
|
||||||
<field name="object" eval="True"/>
|
automatically generated under Linux in your home directory by the
|
||||||
</record>
|
server when executed with the ``--save`` option. You can provide several
|
||||||
|
addons to the ``addons_path`` = option, separating them using commas.
|
||||||
If you double click on a journal/period (object: account.journal.period), this will open the selected wizard. (id="action_move_journal_line_form_select").
|
|
||||||
|
|
||||||
You can use a res_id field to allow this action only if the user click on a specific object.
|
|
||||||
|
|
||||||
.. code-block:: xml
|
|
||||||
|
|
||||||
<record model="ir.values" id="ir_open_journal_period">
|
|
||||||
<field name="key2">tree_but_open</field>
|
|
||||||
<field name="model">account.journal.period</field>
|
|
||||||
<field name="name">Open Journal</field>
|
|
||||||
<field name="value" eval="'ir.actions.wizard,%d'%action_move_journal_line_form_select"/>
|
|
||||||
<field name="res_id" eval="3"/>
|
|
||||||
<field name="object" eval="True"/>
|
|
||||||
</record>
|
|
||||||
|
|
||||||
The action will be triggered if the user clicks on the account.journal.period n°3.
|
|
||||||
|
|
||||||
When you declare wizard, report or menus, the ir.values creation is automatically made with these tags:
|
|
||||||
|
|
||||||
* <wizard... />
|
|
||||||
* <menuitem... />
|
|
||||||
* <report... />
|
|
||||||
|
|
||||||
So you usually do not need to add the mapping by yourself.
|
|
||||||
|
|
|
@ -316,3 +316,58 @@ A report is declared using a **report tag** inside a "data" block. The different
|
||||||
* **rml** : the .RML report model. Important Note : Path is relative to addons/ directory.
|
* **rml** : the .RML report model. Important Note : Path is relative to addons/ directory.
|
||||||
* **menu** : whether the report will be able to be called directly via the client or not. Setting menu to False is useful in case of reports called by wizards.
|
* **menu** : whether the report will be able to be called directly via the client or not. Setting menu to False is useful in case of reports called by wizards.
|
||||||
* **auto** : determines if the .RML file must be parsed using the default parser or not. Using a custom parser allows you to define additional functions to your report.
|
* **auto** : determines if the .RML file must be parsed using the default parser or not. Using a custom parser allows you to define additional functions to your report.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Action creation
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Linking events to action
|
||||||
|
++++++++++++++++++++++++
|
||||||
|
|
||||||
|
The available type of events are:
|
||||||
|
|
||||||
|
* **client_print_multi** (print from a list or form)
|
||||||
|
* **client_action_multi** (action from a list or form)
|
||||||
|
* **tree_but_open** (double click on the item of a tree, like the menu)
|
||||||
|
* **tree_but_action** (action on the items of a tree)
|
||||||
|
|
||||||
|
To map an events to an action:
|
||||||
|
|
||||||
|
.. code-block:: xml
|
||||||
|
|
||||||
|
<record model="ir.values" id="ir_open_journal_period">
|
||||||
|
<field name="key2">tree_but_open</field>
|
||||||
|
<field name="model">account.journal.period</field>
|
||||||
|
<field name="name">Open Journal</field>
|
||||||
|
<field name="value" eval="'ir.actions.wizard,%d'%action_move_journal_line_form_select"/>
|
||||||
|
<field name="object" eval="True"/>
|
||||||
|
</record>
|
||||||
|
|
||||||
|
If you double click on a journal/period (object: account.journal.period), this will open the selected wizard. (id="action_move_journal_line_form_select").
|
||||||
|
|
||||||
|
You can use a res_id field to allow this action only if the user click on a specific object.
|
||||||
|
|
||||||
|
.. code-block:: xml
|
||||||
|
|
||||||
|
<record model="ir.values" id="ir_open_journal_period">
|
||||||
|
<field name="key2">tree_but_open</field>
|
||||||
|
<field name="model">account.journal.period</field>
|
||||||
|
<field name="name">Open Journal</field>
|
||||||
|
<field name="value" eval="'ir.actions.wizard,%d'%action_move_journal_line_form_select"/>
|
||||||
|
<field name="res_id" eval="3"/>
|
||||||
|
<field name="object" eval="True"/>
|
||||||
|
</record>
|
||||||
|
|
||||||
|
The action will be triggered if the user clicks on the account.journal.period n°3.
|
||||||
|
|
||||||
|
When you declare wizard, report or menus, the ir.values creation is automatically made with these tags:
|
||||||
|
|
||||||
|
* <wizard... />
|
||||||
|
* <menuitem... />
|
||||||
|
* <report... />
|
||||||
|
|
||||||
|
So you usually do not need to add the mapping by yourself.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue