From c472efa688fbf4e0de1a3bec0ea620ed0f43c988 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Delavall=C3=A9e?= Date: Tue, 17 Apr 2012 19:20:34 +0200 Subject: [PATCH] [DOC] [REF] Refactoring of the module chapter, still WIP ... bzr revid: tde@openerp.com-20120417172034-h5pzpiair5sk94wz --- doc/03_module_dev_01.rst | 225 +++++++++++++++++---------------------- doc/03_module_dev_04.rst | 55 ++++++++++ 2 files changed, 153 insertions(+), 127 deletions(-) diff --git a/doc/03_module_dev_01.rst b/doc/03_module_dev_01.rst index 2da148fe1ca..b704e44fcab 100644 --- a/doc/03_module_dev_01.rst +++ b/doc/03_module_dev_01.rst @@ -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 -steps are necessary to create a new module: + - **Business object** : declared as Python classes extending the OpenObject c + 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 - * create the import **__init__.py** file - * create a module description file: **__openerp__.py** - * create the **Python** file containing the **objects** - * create **.xml files** that create the data (views, menu entries, demo data, ...) - * optionally create **reports**, **wizards** or **workflows**. +.. figure:: _static/03_module_gen_view.png + :width: 75% + :alt: Module composition + :align: center + + 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 -of the program. It needs to import the Python files that need to be loaded. + - create a ``my_module`` subdirectory in the source/addons directory + - 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 -objects, you have to write one line in __init__.py:: +Description file __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 -OpenERP Module Descriptor File __openerp__.py ---------------------------------------------- +Declaration file __openerp__.py ++++++++++++++++++++++++++++++++ In the created module directory, you must add a **__openerp__.py** file. 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: -**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** - - 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 +For the ``my_module`` module, here is an example of ``__openerp__.py`` +declaration file: .. code-block:: python { - "name" : "Products & Pricelists", - "version" : "1.1", - "author" : "Open", - "category" : "Generic Modules/Inventory Control", - "depends" : ["base", "account"], - "init_xml" : [], - "demo_xml" : ["product_demo.xml"], - "update_xml" : ["product_data.xml", "product_report.xml", "product_wizard.xml", - "product_view.xml", "pricelist_view.xml"], - "installable": True, - "active": True + 'name' : "My Module", + 'version' : "1.0", + 'author' : "OpenERP", + 'category' : "Tools", + 'depends' : ['base',], + 'init_xml' : [], + 'demo_xml' : [ + 'module_demo.xml' + ], + 'update_xml' : [ + '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 @@ -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) - * **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) +Appendix ++++++++++ -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 - - tree_but_open - account.journal.period - Open Journal - - - - -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 - - - tree_but_open - account.journal.period - Open Journal - - - - - -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: - - * - * - * - -So you usually do not need to add the mapping by yourself. + - copying them in server/bin/addons, or creating a symbolic link to each + of them in this directory, or + - specifying another directory containing addons to the server. The later + can be accomplished either by running the server with the ``--addons-path=`` + option, or by configuring this option in the openerp_serverrc file, + automatically generated under Linux in your home directory by the + server when executed with the ``--save`` option. You can provide several + addons to the ``addons_path`` = option, separating them using commas. diff --git a/doc/03_module_dev_04.rst b/doc/03_module_dev_04.rst index 9bd17c8e7dd..f8ad0e2f554 100644 --- a/doc/03_module_dev_04.rst +++ b/doc/03_module_dev_04.rst @@ -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. * **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. + + + + + +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 + + + tree_but_open + account.journal.period + Open Journal + + + + +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 + + + tree_but_open + account.journal.period + Open Journal + + + + + +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: + + * + * + * + +So you usually do not need to add the mapping by yourself. +