flectra/doc/reference/module.rst
2018-02-11 23:55:56 -08:00

132 lines
5.1 KiB
ReStructuredText

=======
Modules
=======
.. _reference/module/manifest:
Manifest
========
The manifest file serves to declare a python package as an Flectra module
and to specify module metadata.
It is a file called ``__manifest__.py`` and contains a single Python
dictionary, where each key specifies module metadatum.
::
{
'name': "A Module",
'version': '1.0',
'depends': ['base'],
'author': "Author Name",
'category': 'Category',
'description': """
Description text
""",
# data files always loaded at installation
'data': [
'views/mymodule_view.xml',
],
# data files containing optionally loaded demonstration data
'demo': [
'demo/demo_data.xml',
],
}
Available manifest fields are:
``name`` (``str``, required)
the human-readable name of the module
``version`` (``str``)
this module's version, should follow `semantic versioning`_ rules
``description`` (``str``)
extended description for the module, in reStructuredText
``author`` (``str``)
name of the module author
``website`` (``str``)
website URL for the module author
``license`` (``str``, defaults: ``LGPL-3``)
distribution license for the module
``category`` (``str``, default: ``Uncategorized``)
classification category within Flectra, rough business domain for the module.
Although using `existing categories`_ is recommended, the field is
freeform and unknown categories are created on-the-fly. Category
hierarchies can be created using the separator ``/`` e.g. ``Foo / Bar``
will create a category ``Foo``, a category ``Bar`` as child category of
``Foo``, and will set ``Bar`` as the module's category.
``depends`` (``list(str)``)
Flectra modules which must be loaded before this one, either because this
module uses features they create or because it alters resources they
define.
When a module is installed, all of its dependencies are installed before
it. Likewise dependencies are loaded before a module is loaded.
``data`` (``list(str)``)
List of data files which must always be installed or updated with the
module. A list of paths from the module root directory
``demo`` (``list(str)``)
List of data files which are only installed or updated in *demonstration
mode*
``auto_install`` (``bool``, default: ``False``)
If ``True``, this module will automatically be installed if all of its
dependencies are installed.
It is generally used for "link modules" implementing synergic integration
between two otherwise independent modules.
For instance ``sale_crm`` depends on both ``sale`` and ``crm`` and is set
to ``auto_install``. When both ``sale`` and ``crm`` are installed, it
automatically adds CRM campaigns tracking to sale orders without either
``sale`` or ``crm`` being aware of one another
``external_dependencies`` (``dict(key=list(str))``)
A dictionary containing python and/or binary dependencies.
For python dependencies, the ``python`` key must be defined for this
dictionary and a list of python modules to be imported should be assigned
to it.
For binary dependencies, the ``bin`` key must be defined for this
dictionary and a list of binary executable names should be assigned to it.
The module won't be installed if either the python module is not installed
in the host machine or the binary executable is not found within the
host machine's PATH environment variable.
``application`` (``bool``, default: ``False``)
Whether the module should be considered as a fully-fledged application
(``True``) or is just a technical module (``False``) that provides some
extra functionality to an existing application module.
``css`` (``list(str)``)
Specify css files with custom rules to be imported, these files should be
located in ``static/src/css`` inside the module.
``images`` (``list(str)``)
Specify image files to be used by the module.
``installable`` (``bool`` default: ``False``)
Whether a user should be able to install the module from the Web UI or not.
``maintainer`` (``str``)
Person or entity in charge of the maintenance of this module, by default
it is assumed that the author is the maintainer.
``{pre_init, post_init, uninstall}_hook`` (``str``)
Hooks for module installation/uninstallation, their value should be a
string representing the name of a function defined inside the module's
``__init__.py``.
``pre_init_hook`` takes a cursor as its only argument, this function is
executed prior to the module's installation.
``post_init_hook`` takes a cursor and a registry as its arguments, this
function is executed right after the module's installation.
``uninstall_hook`` takes a cursor and a registry as its arguments, this
function is executed after the module's uninstallation.
These hooks should only be used when setup/cleanup required for this module
is either extremely difficult or impossible through the api.
.. _semantic versioning: http://semver.org
.. _existing categories:
https://github.com/flectra/flectra/blob/master/flectra/addons/base/module/module_data.xml