diff options
Diffstat (limited to 'doc/reference')
| -rw-r--r-- | doc/reference/cmdline.rst | 85 | ||||
| -rw-r--r-- | doc/reference/data.rst | 275 | ||||
| -rw-r--r-- | doc/reference/http.rst | 27 | ||||
| -rw-r--r-- | doc/reference/javascript.rst | 9 | ||||
| -rw-r--r-- | doc/reference/module.rst | 80 | ||||
| -rw-r--r-- | doc/reference/orm.rst | 353 | ||||
| -rw-r--r-- | doc/reference/qweb.rst | 35 | ||||
| -rw-r--r-- | doc/reference/reports.rst | 74 | ||||
| -rw-r--r-- | doc/reference/security.rst | 16 | ||||
| -rw-r--r-- | doc/reference/views.rst | 277 |
10 files changed, 1231 insertions, 0 deletions
diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst new file mode 100644 index 00000000000..dcedbe03eba --- /dev/null +++ b/doc/reference/cmdline.rst @@ -0,0 +1,85 @@ +.. _reference/cmdline: + +=============================== +Command-line interface: oodo.py +=============================== + +.. _reference/cmdline/server: + +Running the server +================== + +.. program:: odoo.py + +.. option:: -d <database>, --database=<database> + + database used when installing or updating modules. + +.. option:: -i <modules>, --init=<modules> + + comma-separated list of modules to :ref:`install + <reference/module/lifecycle/install>` before running the server. + +.. option:: -u <modules>, --update=<modules> + + comma-separated list of modules to :ref:`update + <reference/module/lifecycle/update>` before running the server. + +.. option:: --addons-path <directories> + + comma-separated list of directories in which modules are stored. These + directories are scanned for modules (nb: when and why?) + +.. option:: -c <config>, --config <config> + + provide an alternate configuration file + +.. option:: -s, --save + + saves the server configuration to the current configuration file + (:file:`{$HOME}/.openerp_serverrc` by default, overridable using + :option:`-c`) + +.. _reference/cmdline/scaffold: + +Scaffolding +=========== + +.. program:: odoo.py scaffold + +Scaffolding is the automated creation of a skeleton structure to simplify +bootstrapping (of new modules, in the case of Odoo). While not necessary it +avoids the tedium of setting up basic structures and looking up what all +starting requirements are. + +Scaffolding is available via the :command:`odoo.py scaffold` subcommand. + +.. option:: -t <template> + + a template directory, files are passed through jinja2_ then copied to + the :option:`destination` directory + +.. option:: name + + the name of the module to create, may munged in various manners to + generate programmatic names (e.g. module directory name, model names, …) + +.. option:: destination + + directory in which to create the new module, defaults to the current + directory + +.. _reference/cmdline/config: + +Configuration file +================== + +Most of the command-line options can also be specified via a configuration +file. + +The default configuration file is :file:`{$HOME}/.openerp_serverrc` which +can be overridden using :option:`--config <odoo.py -c>`. Specifying +:option:`--save <odoo.py -s>` will save the current configuration state back +to that file. + +.. _jinja2: http://jinja.pocoo.org diff --git a/doc/reference/data.rst b/doc/reference/data.rst new file mode 100644 index 00000000000..6e9a004f9ac --- /dev/null +++ b/doc/reference/data.rst @@ -0,0 +1,275 @@ +.. _reference/data: + +========== +Data Files +========== + +Odoo is greatly data-driven, and a big part of modules definition is thus +the definition of the various records it manages: UI (menus and views), +security (access rights and access rules), reports and plain data are all +defined via records. + +Structure +========= + +The main way to define data in Odoo is via XML data files: The broad structure +of an XML data file is the following: + +* The nested root elements ``openerp`` and ``data`` +* Any number of operation elements within ``data`` + +.. code-block:: xml + + <!-- the root elements of the data file --> + <openerp><data> + <operation/> + ... + </data></openerp> + +Data files are executed sequentially, operations can only refer to the result +of operations defined previously + +Core operations +=============== + +.. _reference/data/record: + +``record`` +---------- + +``record`` appropriately defines or updates a database record, it has the +following attributes: + +``model`` (required) + name of the model to create (or update) +``id`` + the :term:`external identifier` for this record. It is strongly + recommended to provide one + + * for record creation, allows subsequent definitions to either modify or + refer to this record + * for record modification, the record to modify +``context`` + context to use when creating the record +``forcecreate`` + in :ref:`update mode <reference/module/lifecycle/update>`, whether the + record should be created if it doesn't exist. + + Requires an :term:`external id`, defaults to ``True``. + +``field`` +''''''''' + +Each record can be composed of ``field`` tags, defining values to set when +creating the record. A ``record`` with no ``field`` will use all default +values (creation) or do nothing (update). + +A ``field`` has a mandatory ``name`` attribute, the name of the field to set, +and various methods to define the value itself: + +Nothing + if no value is provided for the field, an implicit ``False`` will be set + on the field. Can be used to clear a field, or avoid using a default value + for the field. +``search`` + for :ref:`relational fields <reference/orm/fields/relational>`, should be + a :ref:`domain <reference/orm/domains>` on the field's model. + + Will evaluate the domain, search the field's model using it and set the + search's result as the field's value. Will only use the first result if + the field is a :class:`~openerp.fields.Many2one` +``ref`` + if a ``ref`` attribute is provided, its value must be a valid + :term:`external id`, which will be looked up and set as the field's value. + + Mostly for :class:`~openerp.fields.Many2one` and + :class:`~openerp.fields.Reference` fields +``type`` + if a ``type`` attribute is provided, it is used to interpret and convert + the field's content. The field's content can be provided through an + external file using the ``file`` attribute, or through the node's body. + + Available types are: + + ``xml``, ``html`` + extracts the ``field``'s children as a single document, evaluates + any :term:`external id` specified with the form ``%(external_id)s``. + ``%%`` can be used to output actual *%* signs. + ``file`` + ensures that the field content is a valid file path in the current + model, saves the pair :samp:`{module},{path}` as the field value + ``char`` + sets the field content directly as the field's value without + alterations + ``base64`` + base64_-encodes the field's content, useful combined with the ``file`` + *attribute* to load e.g. image data into attachments + ``int`` + converts the field's content to an integer and sets it as the field's + value + ``float`` + converts the field's content to a float and sets it as the field's + value + ``list``, ``tuple`` + should contain any number of ``value`` elements with the same + properties as ``field``, each element resolves to an item of a + generated tuple or list, and the generated collection is set as the + field's value +``eval`` + for cases where the previous methods are unsuitable, the ``eval`` + attributes simply evaluates whatever Python expression it is provided and + sets the result as the field's value. + + The evaluation context contains various modules (``time``, ``datetime``, + ``timedelta``, ``relativedelta``), a function to resolve :term:`external + identifiers` (``ref``) and the model object for the current field if + applicable (``obj``) + +``delete`` +---------- + +The ``delete`` tag can remove any number of records previously defined. It +has the following attributes: + +``model`` (required) + the model in which a specified record should be deleted +``id`` + the :term:`external id` of a record to remove +``search`` + a :ref:`domain <reference/orm/domains>` to find records of the model to + remove + +``id`` and ``search`` are exclusive + +``function`` +------------ + +The ``function`` tag calls a method on a model, with provided parameters. +It has two mandatory parameters ``model`` and ``name`` specifying respectively +the model and the name of the method to call. + +Parameters can be provided using ``eval`` (should evaluate to a sequence of +parameters to call the method with) or ``value`` elements (see ``list`` +values). + +``workflow`` +------------ + +The ``workflow`` tag sends a signal to an existing workflow. The workflow +can be specified via a ``ref`` attribute (the :term:`external id` of +an existing workflow) or a ``value`` tag returning the id of a workflow. + +The tag also has two mandatory attributes ``model`` (the model linked to the +workflow) and ``action`` (the name of the signal to send to the workflow). + +.. ignored assert + +Shortcuts +========= + +Because some important structural models of Odoo are complex and involved, +data files provide shorter alternatives to defining them using +:ref:`record tags <reference/data/record>`: + +``menuitem`` +------------ + +Defines an ``ir.ui.menu`` record with a number of defaults and fallbacks: + +Parent menu + * If a ``parent`` attribute is set, it should be the :term:`external id` + of an other menu item, used as the new item's parent + * If no ``parent`` is provided, tries to interpret the ``name`` attribute + as a ``/``-separated sequence of menu names and find a place in the menu + hierarchy. In that interpretation, intermediate menus are automatically + created + * Otherwise the menu is defined as a "top-level" menu item (*not* a menu + with no parent) +Menu name + If no ``name`` attribute is specified, tries to get the menu name from + a linked action if any. Otherwise uses the record's ``id`` +Groups + A ``groups`` attribute is interpreted as a comma-separated sequence of + :term:`external identifiers` for ``res.groups`` models. If an + :term:`external identifier` is prefixed with a minus (``-``), the group + is *removed* from the menu's groups +``action`` + if specified, the ``action`` attribute should be the :term:`external id` + of an action to execute when the menu is open +``id`` + the menu item's :term:`external id` + +``template`` +------------ + +Creates a :ref:`QWeb view <reference/views/qweb>` requiring only the ``arch`` +section of the view, and allowing a few *optional* attributes: + +``id`` + the view's :term:`external identifier` +``name``, ``inherit_id``, ``priority`` + same as the corresponding field on ``ir.ui.view`` (nb: ``inherit_id`` + should be an :term:`external identifier`) +``primary`` + if set to ``True`` and combined with a ``inherit_id``, defines the view + as a primary +``groups`` + comma-separated list of group :term:`external identifiers` +``page`` + if set to ``"True"``, the template is a website page (linkable to, + deletable) +``optional`` + ``enabled`` or ``disabled``, whether the view can be disabled (in the + website interface) and its default status. If unset, the view is always + enabled. + +``report`` +---------- + +Creates a ``ir.actions.report.xml`` record with a few default values. + +Mostly just proxies attributes to the corresponding fields on +``ir.actions.report.xml``, but also automatically creates the item in the +:guilabel:`More` menu of the report's ``model``. + +.. ignored url, act_window and ir_set + +CSV data files +============== + +XML data files are flexible and self-descriptive, but very verbose when +creating a number of simple records of the same model in bulk. + +For this case, data files can also use csv_, this is often the case for +:ref:`access rights <reference/security/acl>`: + +* the file name is :file:`{model_name}.csv` +* the first row lists the fields to write, with the special field ``id`` + for :term:`external identifiers` (used for creation or update) +* each row thereafter creates a new record + +Here's the first lines of the data file defining US states +``res.country.state.csv`` + +.. literalinclude:: ../../openerp/addons/base/res/res.country.state.csv + :language: text + :lines: 1-15 + +rendered in a more readable format: + +.. csv-table:: + :file: ../../openerp/addons/base/res/res.country.state.csv + :header-rows: 1 + :class: table-striped table-hover table-condensed + +For each row (record): + +* the first column is the :term:`external id` of the record to create or + update +* the second column is the :term:`external id` of the country object to link + to (country objects must have been defined beforehand) +* the third column is the ``name`` field for ``res.country.state`` +* the fourth column is the ``code`` field for ``res.country.state`` + +.. _base64: http://tools.ietf.org/html/rfc3548.html#section-3 +.. _csv: http://en.wikipedia.org/wiki/Comma-separated_values diff --git a/doc/reference/http.rst b/doc/reference/http.rst new file mode 100644 index 00000000000..6459e2bbd1b --- /dev/null +++ b/doc/reference/http.rst @@ -0,0 +1,27 @@ +=============== +Web Controllers +=============== + +Routing +======= + +.. autofunction:: openerp.http.route + +.. _reference/http/request: + +Request +======= + +Response +======== + +JSON-RPC +======== + +.. _reference/http/controllers: + +Extension: controllers +====================== + +.. this should be about inheritance/extension, do web controllers still do + anything else nowadays? diff --git a/doc/reference/javascript.rst b/doc/reference/javascript.rst new file mode 100644 index 00000000000..668543a906d --- /dev/null +++ b/doc/reference/javascript.rst @@ -0,0 +1,9 @@ +========== +Javascript +========== + +Widgets +======= + +RPC +=== diff --git a/doc/reference/module.rst b/doc/reference/module.rst new file mode 100644 index 00000000000..933b263f7ba --- /dev/null +++ b/doc/reference/module.rst @@ -0,0 +1,80 @@ +======= +Modules +======= + +.. _reference/module/manifest: + +Manifest +======== + +The manifest file serves to both declare a python package as an Odoo module, +and to specify a number of module metadata. + +It is a file called ``__openerp__.py`` and contains a single Python +dictionary, each dictionary key specifying a module metadatum. + +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: ``AGPL-3``) + distribution license for the module +``category`` (``str``, default: ``Uncategorized``) + classification category within Odoo, 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)``) + Odoo 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 during modules loading. +``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 + +.. _reference/module/lifecycle: + +Lifecycle +========= + +.. _reference/module/lifecycle/install: + +Install +------- + +.. _reference/module/lifecycle/update: + +Update +------ + +.. _semantic versioning: http://semver.org +.. _existing categories: + https://github.com/odoo/odoo/blob/master/openerp/addons/base/module/module_data.xml diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst new file mode 100644 index 00000000000..3a1e1e6fd2a --- /dev/null +++ b/doc/reference/orm.rst @@ -0,0 +1,353 @@ +.. _reference/orm: + +=== +ORM +=== + +.. _reference/orm/model: + +Model +===== + +.. - can't get autoattribute to import docstrings, so use regular attribute + - no autoclassmethod + +.. currentmodule:: openerp.models + +.. autoclass:: openerp.models.Model + + .. rubric:: Structural attributes + + .. attribute:: _name + + business object name, in dot-notation (in module namespace) + + .. attribute:: _rec_name + + Alternative field to use as name, used by osv’s name_get() + (default: ``'name'``) + + .. attribute:: _inherit + + * If :attr:`._name` is set, names of parent models to inherit from. + Can be a ``str`` if inheriting from a single parent + * If :attr:`._name` is unset, name of a single model to extend + in-place + + .. attribute:: _order + + Ordering field when searching without an ordering specified (default: + ``'id'``) + + :type: str + + .. attribute:: _auto + + Whether a database table should be created (default: ``True``) + + If set to ``False``, override :meth:`.init` to create the database + table + + .. attribute:: _table + + Name of the table backing the model created when + :attr:`~openerp.models.Model._auto`, automatically generated by + default. + + .. attribute:: _inherits + + dictionary mapping the _name of the parent business objects to the + names of the corresponding foreign key fields to use:: + + _inherits = { + 'a.model': 'a_field_id', + 'b.model': 'b_field_id' + } + + implements composition-based inheritance: the new model exposes all + the fields of the :attr:`~openerp.models.Model._inherits`-ed model but + stores none of them: the values themselves remain stored on the linked + record. + + .. warning:: + + if the same field is defined on multiple + :attr:`~openerp.models.Model._inherits`-ed + + .. attribute:: _constraints + + list of ``(constraint_function, message, fields)`` defining Python + constraints. The fields list is indicative + + .. deprecated:: 8.0 + + use :func:`~openerp.api.constrains` + + .. attribute:: _sql_constraints + + list of ``(name, sql_definition, message)`` triples defining SQL + constraints to execute when generating the backing table + + .. attribute:: _parent_store + + Alongside :attr:`~.parent_left` and :attr:`~.parent_right`, sets up a + `nested set <http://en.wikipedia.org/wiki/Nested_set_model>`_ to + enable fast hierarchical queries on the records of the current model + (default: ``False``) + + :type: bool + + .. rubric:: CRUD + + .. automethod:: create + .. automethod:: browse + .. automethod:: unlink + .. automethod:: write + + .. automethod:: read + + .. rubric:: Research + + .. automethod:: search + .. automethod:: search_count + .. automethod:: name_search + + .. rubric:: Recordset operations + + .. autoattribute:: ids + .. automethod:: ensure_one + .. automethod:: exists + .. automethod:: filtered + .. automethod:: sorted + .. automethod:: update + + .. rubric:: Environment swapping + + .. automethod:: sudo + .. automethod:: with_context + .. automethod:: with_env + + .. rubric:: Fields and views querying + + .. automethod:: fields_get + .. automethod:: fields_view_get + + .. rubric:: ??? + + .. automethod:: default_get + .. automethod:: copy + .. automethod:: add_default_value + .. automethod:: name_get + .. automethod:: name_create + + .. rubric:: Automatic fields + + .. attribute:: id + + Identifier :class:`field <openerp.fields.Field>` + + .. attribute:: _log_access + + Whether log access fields (``create_date``, ``write_uid``, ...) should + be generated (default: ``True``) + + .. attribute:: create_date + + Date at which the record was created + + :type: :class:`~openerp.field.Datetime` + + .. attribute:: create_uid + + Relational field to the user who created the record + + :type: ``res.users`` + + .. attribute:: write_date + + Date at which the record was last modified + + :type: :class:`~openerp.field.Datetime` + + .. attribute:: write_uid + + Relational field to the last user who modified the record + + :type: ``res.users`` + + .. rubric:: Reserved field names + + A few field names are reserved for pre-defined behaviors beyond that of + automated fields. They should be defined on a model when the related + behavior is desired: + + .. attribute:: name + + default value for :attr:`~._rec_name`, used to + display records in context where a representative "naming" is + necessary. + + :type: :class:`~openerp.fields.Char` + + .. attribute:: active + + toggles the global visibility of the record, if ``active`` is set to + ``False`` the record is invisible in most searches and listing + + :type: :class:`~openerp.fields.Boolean` + + .. attribute:: sequence + + Alterable ordering criteria, allows drag-and-drop reordering of models + in list views + + :type: :class:`~openerp.fields.Integer` + + .. attribute:: state + + lifecycle stages of the object, used by the ``states`` attribute on + :class:`fields <openerp.fields.Field>` + + :type: :class:`~openerp.fields.Selection` + + .. attribute:: parent_id + + used to order records in a tree structure and enables the ``child_of`` + operator in domains + + :type: :class:`~openerp.fields.Many2one` + + .. attribute:: parent_left + + used with :attr:`~._parent_store`, allows faster tree structure access + + .. attribute:: parent_right + + see :attr:`~.parent_left` + +.. _reference/orm/decorators: + +Method decorators +================= + +.. automodule:: openerp.api + :members: one, multi, model, depends, constrains, onchange, returns + +.. _reference/orm/fields: + +Fields +====== + +.. _reference/orm/fields/basic: + +Basic fields +------------ + +.. autodoc documents descriptors as attributes, even for the *definition* of + descriptors. As a result automodule:: openerp.fields lists all the field + classes as attributes without providing inheritance info or methods (though + we don't document methods as they're not useful for "external" devs) + (because we don't support pluggable field types) (or do we?) + +.. autoclass:: openerp.fields.Field + +.. autoclass:: openerp.fields.Char + :show-inheritance: + +.. autoclass:: openerp.fields.Boolean + :show-inheritance: + +.. autoclass:: openerp.fields.Integer + :show-inheritance: + +.. autoclass:: openerp.fields.Float + :show-inheritance: + +.. autoclass:: openerp.fields.Text + :show-inheritance: + +.. autoclass:: openerp.fields.Selection + :show-inheritance: + +.. autoclass:: openerp.fields.Html + :show-inheritance: + +.. autoclass:: openerp.fields.Date + :show-inheritance: + :members: today, context_today, from_string, to_string + +.. autoclass:: openerp.fields.Datetime + :show-inheritance: + :members: now, context_timestamp, from_string, to_string + +.. _reference/orm/fields/relational: + +Relational fields +----------------- + +.. autoclass:: openerp.fields.Many2one + :show-inheritance: + +.. autoclass:: openerp.fields.One2many + :show-inheritance: + +.. autoclass:: openerp.fields.Many2many + :show-inheritance: + +.. autoclass:: openerp.fields.Reference + :show-inheritance: + +.. _reference/orm/domains: + +Domains +======= + +A domain is a list of criterion, each criterion being a triple (either a +``list`` or a ``tuple``) of ``(field_name, operator, value)`` where: + +``field_name`` (``str``) + a field name of the current model, or a relationship traversal through + a :class:`~openerp.fields.Many2one` using dot-notation e.g. ``'street'`` + or ``'partner_id.country'`` +``operator`` (``str``) + a comparison operator between the criterion's field and value. + + .. todo:: list and detail operators, original list is way incomplete +``value`` + variable type, must be comparable (through ``operator``) to the named + field + +Domain criteria can be combined using logical operators in *prefix* form: + +``'&'`` + logical *AND*, default operation to combine criteria following one + another. Arity 2 (uses the next 2 criteria or combinations). +``'|'`` + logical *OR*, arity 2. +``'!'`` + logical *NOT*, arity 1. + + .. tip:: Mostly to negate combinations of criteria + :class: aphorism + + Individual criterion generally have a negative form (e.g. ``=`` -> + ``!=``, ``<`` -> ``>=``) which is simpler than negating the positive. + +.. admonition:: Example + + To search for partners named *ABC*, from belgium or germany, whose language + is not english:: + + [('name','=','ABC'), + ('language.code','!=','en_US'), + '|',('country_id.code','=','be'), + ('country_id.code','=','de')] + + This domain is interpreted as: + + .. code-block:: text + + (name is 'ABC') + AND (language is NOT english) + AND (country is Belgium OR Germany) + diff --git a/doc/reference/qweb.rst b/doc/reference/qweb.rst new file mode 100644 index 00000000000..53ca153d7d5 --- /dev/null +++ b/doc/reference/qweb.rst @@ -0,0 +1,35 @@ +.. _reference/qweb: + +==== +QWeb +==== + +Basics +====== + +.. _reference/qweb/output: + +data output +----------- + +.. _reference/qweb/conditionals: + +conditionals +------------ + +.. _reference/qweb/loops: + +loops +----- + +Python +====== + +Bundles +------- + +Javascript +========== + +loading +------- diff --git a/doc/reference/reports.rst b/doc/reference/reports.rst new file mode 100644 index 00000000000..78211ff4e49 --- /dev/null +++ b/doc/reference/reports.rst @@ -0,0 +1,74 @@ +.. _reference/reports: + +============ +QWeb Reports +============ + +Paper Formats +------------- + +There is a model called Paper Format allowing to define details specific to +the PDF output. These details include margins, header line, ... Everything +related to the printed pdf. Defining a paper format is not mandatory as there +is a default one set on the company. If you want a specific report to be +associated to a specific paper format , just link the ir.actions.report.xml to +it. + +Expressions used in Odoo report templates +----------------------------------------- + +There are some magic variables used in the report rendering. The main ones are +the following: + +``docs`` + records for the current report +``doc_ids`` + list of ids for the ``docs`` records +``doc_model`` + model for teh ``docs`` records +``time`` + a reference to time_ from the Python standard library +``translate_doc`` + a function to translate a part of a report. It must be used as follow: + + .. code-block:: xml + + <t t-foreach="doc_ids" t-as="doc_id"> + <t t-raw="translate_doc(doc_id, doc_model, 'partner_id.lang', account.report_invoice_document')"/> + </t> +``user`` + ``res.user`` record for the user printing the report +``res_company`` + record the current ``user``'s company + +Custom report +------------- + +A generic report use the default rendering context, containing the magic +variables as explained before. If you want a new rendering context containing +anything you want to process your data Odoo AbstractModel, a custom module is +needed. These reports are called "particular report". + +For a particular report, you have to write an Odoo Model containing a +render_html method. Classically, this method returns a call to the original +**QWeb render** with a **custom rendering context**. + +.. code-block:: python + + from openerp import api, models + + + class ParticularReport(models.AbstractModel): + _name = 'report.<<module.reportname>>' + @api.multi + def render_html(self, data=None): + report_obj = self.env['report'] + report = report_obj._get_report_from_name('<<module.reportname>>') + docargs = { + 'doc_ids': ids, + 'doc_model': report.model, + 'docs': self.env[report.model].browse(ids), + } + return report_obj.render('<<module.reportname>>', docargs) + +.. _time: https://docs.python.org/2/library/time.html diff --git a/doc/reference/security.rst b/doc/reference/security.rst new file mode 100644 index 00000000000..15dbd1c0c7e --- /dev/null +++ b/doc/reference/security.rst @@ -0,0 +1,16 @@ +.. _reference/security: + +================ +Security in Odoo +================ + +.. _reference/security/acl: + +Access Control +============== + +.. _reference/security/rules: + +Record Rules +============ + diff --git a/doc/reference/views.rst b/doc/reference/views.rst new file mode 100644 index 00000000000..4a0d5da9e6d --- /dev/null +++ b/doc/reference/views.rst @@ -0,0 +1,277 @@ +.. _reference/views: + +===== +Views +===== + +.. _reference/views/structure: + +Structure +========= + +View objects expose a number of fields, they are optional unless specified +otherwise) + +``name`` (mandatory) + only useful as a mnemonic/description of the view when looking for one in + a list of some sort +``model`` + the model linked to the view, if applicable (it doesn't for QWeb views) +``priority`` + client programs can request views by ``id``, or by ``(model, type)``. For + the latter, all the views for the right type and model will be looked for, + and the one with the lowest ``priority`` number will be returned (it is + the "default view"). + + ``priority`` also defines the order of application during :ref:`view + inheritance <reference/views/inheritance>` +``arch`` + the description of the view's layout, see + :ref:`reference/views/architecture` +``groups_id`` + :class:`~openerp.fields.Many2many` field to the groups allowed to view/use + the current view +``inherit_id`` + the current view's parent view, see :ref:`reference/views/inheritance`, + unset by default +``mode`` + inheritance mode, see :ref:`reference/views/inheritance`. If + ``inherit_id`` is unset the ``mode`` can only be ``primary``. If + ``inherit_id`` is set, ``extension`` by default but can be explicitly set + to ``primary`` +``application`` + website feature defining togglable views. By default, views are always + applied + +.. _reference/views/inheritance: + +Inheritance +=========== + +View matching +------------- + +* if a view is requested by ``(model, type)``, the view with the right model + and type, ``mode=primary`` and the lowest priority is matched +* when a view is requested by ``id``, if its mode is not ``primary`` its + *closest* parent with mode ``primary`` is matched + +View resolution +--------------- + +Resolution generates the final ``arch`` for a requested/matched ``primary`` +view: + +#. if the view has a parent, the parent is fully resolved then the current + view's inheritance specs are applied +#. if the view has no parent, its ``arch`` is used as-is +#. the current view's children with mode ``extension`` are looked up and their + inheritance specs are applied depth-first (a child view is applied, then + its children, then its siblings) + +The result of applying children views yields the final ``arch`` + +Inheritance specs +----------------- + +There are three types of inheritance specs: + +* An ``xpath`` element with an ``expr`` attribute. ``expr`` is an XPath_ + expression\ [#hasclass]_ applied to the current ``arch``, the first node + it finds is the match +* a ``field`` element with a ``name`` attribute, matches the first ``field`` + with the same ``name`` +* any other element, the first element with the same name and identical + attributes (ignoring ``position``) is matched + +The inheritance spec can an optional ``position`` attribute specifhing how +the matched node should be altered: + +``inside`` (default) + the content of the inheritance spec is appended to the matched node +``replace`` + the content of the inheritance spec replaces the matched node +``after`` + the content of the inheritance spec is added to the matched node's + parent, after the matched node +``before`` + the content of the inheritance spec is added to the matched node's + parent, before the matched node +``attribute`` + the content of the inheritance spec should be ``attribute`` elements + with a ``name`` attribute and an optional body: + + * if the ``attribute`` element has a body, a new attributed named + after its ``name`` is created on the matched node with the + ``attribute`` element's text as value + * if the ``attribute`` element has no body, the attribute named after + its ``name`` is removed from the matched node. If no such attribute + exists, an error is raised + +A view's specs are applied sequentially. + +.. _reference/views/architecture: + +Architecture structures +======================= + +.. _reference/views/list: + +Lists +----- + +The root element of list views is ``<tree>``\ [#treehistory]_. The list view's +root can have the following attributes: + +``editable`` + by default, selecting a list view's row opens the corresponding + :ref:`form view <reference/views/form>`. The ``editable`` attributes makes + the list view itself editable in-place. + + Valid values are ``top`` and ``bottom``, making *new* records appear + respectively at the top or bottom of the list +``colors`` + allows changing the color of a row's text based on the corresponding + record's attributes. + + Defined as a mapping of colors to Python expressions. Values are of the + form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested + in-order, the expression is evaluated for the record and if ``true`` the + corresponding color is applied to the row. If no color matches, uses the + default text color (black). + + * ``color`` can be any valid `CSS color unit`_. + * ``expr`` should be a Python expression evaluated with the current + record's attributes as context values. Other context values are ``uid`` + (the id of the current user) and ``current_date`` (the current date as + a string of the form ``yyyy-MM-dd``) +``fonts`` + allows changing a row's font style based on the corresponding record's + attributes. + + The format is the same as for ``color``, but the ``color`` of each pair + is replaced by ``bold``, ``italic`` or ``underline``, the expression + evaluating to ``true`` will apply the corresponding style to the row's + text. Contrary to ``colors``, multiple pairs can match each record +``create``, ``edit``, ``delete`` + allows *dis*\ abling the corresponding action in the view by setting the + corresponding attribute to ``false`` +``on_write`` + only makes sense on an ``editable`` list. Should be the name of a method + on the list's model. The method will be called with the ``id`` of a record + after having created or edited that record (in database). + + The method should return a list of ids of other records to load or update. +``string`` + alternative translatable label for the view + + .. deprecated:: 8.0 + + not displayed anymore + +.. toolbar attribute is for tree-tree views + +Possible children elements of the list view are: + +``button`` + displays a button in a list cell + + ``icon`` + icon to use to display the button + ``string`` + * if there is no ``icon``, the button's text + * if there is an ``icon``, ``alt`` text for the icon + ``type`` + type of button, indicates how it clicking it affects Odoo: + + ``workflow`` (default) + sends a signal to a workflow. The button's ``name`` is the + workflow signal, the row's record is passed as argument to the + signal + ``object`` + call a method on the list's model. The button's ``name`` is the + method, which is called with the current row's record id and the + current context. + + .. web client also supports a @args, which allows providing + additional arguments as JSON. Should that be documented? Does + not seem to be used anywhere + + ``action`` + load an execute an ``ir.actions``, the button's ``name`` is the + database id of the action. The context is expanded with the list's + model (as ``active_model``), the current row's record + (``active_id``) and all the records currently loaded in the list + (``active_ids``, may be just a subset of the database records + matching the current search) + ``name`` + see ``type`` + ``args`` + see ``type`` + ``attrs`` + dynamic attributes based on record values. + + A mapping of attributes to domains, domains are evaluated in the + context of the current row's record, if ``True`` the corresponding + attribute is set on the cell. + + Possible attributes are ``invisible`` (hides the button) and + ``readonly`` (disables the button but still shows it) + ``states`` + shorthand for ``invisible`` ``attrs``: a list of space, separated + states, requires that the model has a ``state`` field and that it is + used in the view. + + Makes the button ``invisible`` if the record is *not* in one of the + listed states + ``context`` + merged into the view's context when performing the button's Odoo call + ``confirm`` + confirmation message to display (and for the user to accept) before + performing the button's Odoo call + + .. declared but unused: help + +``field`` + displays a field's value in a list cell + +.. _reference/views/form: + +Forms +----- + +.. _reference/views/search: + +Search +------ + +.. _reference/views/graphs: + +Graphs +------ + +@type=row/@type=col + +.. _reference/views/kanban: + +Kanban +------ + +.. _reference/views/calendar: + +Calendar +-------- + +.. _reference/views/qweb: + +QWeb (?) +-------- + +.. [#hasclass] an extension function is added for simpler matching in QWeb + views: ``hasclass(*classes)`` matches if the context node has + all the specified classes +.. [#treehistory] for historical reasons, it has its origin in tree-type views + later repurposed to a more table/list-type display + +.. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits +.. _XPath: http://en.wikipedia.org/wiki/XPath |