From 5d64577f570282d0382309c7657963fdbae63d5b Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Wed, 8 Oct 2014 13:06:33 +0200 Subject: [PATCH] [ADD] actions documentation --- doc/reference.rst | 1 + doc/reference/actions.rst | 397 +++++++++++++++++++++++++++++++++++++- 2 files changed, 388 insertions(+), 10 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index bc54ce4b2b8..bf0ad5d6d1a 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -7,6 +7,7 @@ Reference reference/orm reference/data + reference/actions reference/views reference/module reference/cmdline diff --git a/doc/reference/actions.rst b/doc/reference/actions.rst index d3ab6d31b69..8e31d58b36c 100644 --- a/doc/reference/actions.rst +++ b/doc/reference/actions.rst @@ -1,24 +1,401 @@ -:orphan: - .. _reference/actions: ======= Actions ======= -.. todo:: fill in documentation, add to TOC - Actions define the behavior of the system in response to user actions: login, action button, selection of an invoice, ... -Window Actions -============== +Actions can be stored in the database or returned directly as dictionaries in +e.g. button methods. All actions share two mandatory attributes: -URL Actions -=========== +``type`` + the category of the current action, determines which fields may be + used and how the action is interpreted +``name`` + short user-readable description of the action, may be displayed in the + client's interface -Server Actions -============== +A client can get actions in 4 forms: + +``False`` + if any action dialog is currently open, close it +A string + if a :ref:`client action ` matches, interpret as + a client action's tag, otherwise treat as a number +A number + read the corresponding action record from the database, may be a database + identifier or an :term:`external id` +A dictionary + treat as a client action descriptor and execute + +.. _reference/actions/window: + +Window Actions (``ir.actions.act_window``) +========================================== + +The most common action type, used to present visualisations of a model through +:ref:`views `: a window action defines a set of view types +(and possibly specific views) for a model (and possibly specific record of the +model). + +Its fields are: + +``res_model`` + model to present views for +``views`` + a list of ``(view_id, view_type)`` pairs. The second element of each pair + is the category of the view (tree, form, graph, ...) and the first is + an optional database id (or ``False``). If no id is provided, the client + should fetch the default view of the specified type for the requested + model (this is automatically done by + :meth:`~openerp.models.Model.fields_view_get`). The first type of the + list is the default view type and will be open by default when the action + is executed. Each view type should be present at most once in the list +``res_id`` (optional) + if the default view is ``form``, specifies the record to load (otherwise + a new record should be created) +``search_view_id`` (optional) + ``(id, name)`` pair, ``id`` is the database identifier of a specific + search view to load for the action. Defaults to fetching the default + search view for the model +``target`` (optional) + whether the views should be open in the main content area (``current``) + or in a dialog/popup (``new``). Defaults to ``current``. +``context`` (optional) + additional context data to pass to the views +``domain`` (optional) + filtering domain to implicitly add to all view search queries +``limit`` (optional) + number of records to display in lists by default. Defaults to 80 in the + web client +``auto_search`` (optional) + whether a search should be performed immediately after loading the default + view. Defaults to ``True`` + +For instance, to open customers (partner with the ``customer`` flag set) with +list and form views:: + + { + "type": "ir.actions.act_window", + "res_model": "res.partner", + "views": [[False, "tree"], [False, "form"]], + "domain": [["customer", "=", true]], + } + +Or to open the form view of a specific product (obtained separately) in a new +dialog:: + + { + "type": "ir.actions.act_window", + "res_model": "product.product", + "views": [[False, "form"]], + "res_id": a_product_id, + "target": "new", + } + +In-database window actions have a few different fields which should be ignored +by clients, mostly to use in composing the ``views`` list: + +``view_mode`` + comma-separated list of view types (tree, form, ...) as a string. All of + these types will be present in the generated ``views`` list (with at least + a ``False`` view_id) +``view_ids`` + M2M\ [#notquitem2m]_ to view objects, defines the initial content of + ``views`` +``view_id`` + specific view added to the ``views`` list in case its type is part of the + ``view_mode`` list and not already filled by one of the views in + ``view_ids`` + +These are mostly used when defining actions from :ref:`reference/data`: + +.. code-block:: xml + + + A Test Action + some.model + graph + + + +will use the "my_specific_view" view even if that's not the default view for +the model. + +The server-side composition of the ``views`` sequence is the following: + +* get each ``(id, type)`` from ``view_ids`` (ordered by ``sequence``) +* if ``view_id`` is defined and its type isn't already filled, append its + ``(id, type)`` +* for each unfilled type in ``view_mode``, append ``(False, type)`` + +.. todo:: + + * ``src_model``, ``multi`` seem linked to "sidebar" actions? + * ``auto_refresh`` looks ignored/deprecated + * ``usage``? + * ``groups_id``? + * ``filter``? + +.. _reference/actions/url: + +URL Actions (``ir.actions.act_url``) +==================================== + +Allow opening a URL (website/web page) via an Odoo action. Can be customized +via two fields: + +``url`` + the address to open when activating the action +``target`` + opens the address in a new window/page if ``new``, replaces + the current content with the page if ``self``. Defaults to ``new`` + +:: + + { + "type": "ir.actions.act_url", + "url": "http://odoo.com", + "target": "self", + } + +will replace the current content section by the Odoo home page. + +.. _reference/actions/server: + +Server Actions (``ir.actions.server``) +====================================== + +Allow triggering complex server code from any valid action location. Only +two fields are relevant to clients: + +``id`` + the in-database identifier of the server action to run +``context`` (optional) + context data to use when running the server action + +In-database records are significantly richer and can perform a number of +specific or generic actions based on their ``state``. Some fields (and +corresponding behaviors) are shared between states: + +``model_id`` + Odoo model linked to the action, made available in + :ref:`evaluation contexts ` +``condition`` (optional) + evaluated as Python code using the server action's + :ref:`evaluation context `. If + ``False``, prevents the action from running. Default: ``True`` + +Valid action types (``state`` field) are extensible, the default types are: + +``code`` +-------- + +The default and most flexible server action type, executes arbitrary Python +code with the action's :ref:`evaluation context +`. Only uses one specific type-specific +field: + +``code`` + a piece of Python code to execute when the action is called + +.. code-block:: xml + + + + + print self, object + + + +.. note:: + + The code segment can define a variable called ``action``, which will be + returned to the client as the next action to execute: + + .. code-block:: xml + + + + + if object.some_condition(): + action = { + "type": "ir.actions.act_window", + "view_mode": "form", + "res_model": object._name, + "res_id": object.id, + } + + + + will ask the client to open a form for the record if it fullfils some + condition + +This tends to be the only action type created from :ref:`data files +`, other types aside from +:ref:`reference/actions/server/multi` are simpler than Python code to define +from the UI, but not from :ref:`data files `. + +.. _reference/actions/server/object_create: + +``object_create`` +----------------- + +Creates a new record, from scratch (via :meth:`~openerp.models.Model.create`) +or by copying an existing record (via :meth:`~openerp.models.Model.copy`) + +``use_create`` + the creation policy, one of: + + ``new`` + creates a record in the model specified by ``model_id`` + ``new_other`` + creates a record in the model specified by ``crud_model_id`` + ``copy_current`` + copies the record on which the action was invoked + ``copy_other`` + copies an other record, obtained via ``ref_object`` +``fields_lines`` + fields to override when creating or copying the record. + :class:`~openerp.fields.One2many` with the fields: + + ``col1`` + ``ir.model.fields`` to set in the model implied by ``use_create`` + ``value`` + value for the field, interpreted via ``type`` + ``type`` + If ``value``, the ``value`` field is interpreted as a literal value + (possibly converted), if ``equation`` the ``value`` field is + interpreted as a Python expression and evaluated +``crud_model_id`` + model in which to create a new record, if ``use_create`` is set to + ``new_other`` +``ref_object`` + :class:`~openerp.fields.Reference` to an arbitrary record to copy, used if + ``use_create`` is set to ``copy_other`` +``link_new_record`` + boolean flag linking the newly created record to the current one via a + many2one field specified through ``link_field_id``, defaults to ``False`` +``link_field_id`` + many2one to ``ir.model.fields``, specifies the current record's m2o field + on which the newly created record should be set (models should match) + +``object_write`` +---------------- + +Similar to :ref:`reference/actions/server/object_create` but alters an +existing records instead of creating one + +``use_write`` + write policy, one of: + + ``current`` + write to the current record + ``other`` + write to an other record selected via ``crud_model_id`` and + ``ref_object`` + ``expression`` + write to an other record whose model is selected via ``crud_model_id`` + and whose id is selected by evaluating ``write_expression`` +``write_expression`` + Python expression returning a record or an object id, used when + ``use_write`` is set to ``expression`` in order to decide which record + should be modified +``fields_lines`` + see :ref:`reference/actions/server/object_create` +``crud_model_id`` + see :ref:`reference/actions/server/object_create` +``ref_object`` + see :ref:`reference/actions/server/object_create` + +.. _reference/actions/server/multi: + +``multi`` +--------- + +Executes multiple actions one after the other. Actions to execute are defined +via the ``child_ids`` m2m. If sub-actions themselves return actions, the last +one will be returned to the client as the multi's own next action + +``trigger`` +----------- + +Sends a signal to a workflow. + +``wkf_transition_id`` + :class:`~openerp.fields.Many2one` to a ``workflow.transition`` to trigger +``use_relational_model`` + if ``base`` (the default), trigger the signal on behalf of the current + record. If ``relational``, trigger the signal on behalf of a field of the + current record selected through ``wkf_model_id`` and ``wkf_field_id`` + +``client_action`` +----------------- + +Indirection for directly returning an other action defined using +``action_id``. Simply returns that action to the client for execution. + +.. _reference/actions/server/context: + +Evaluation context +------------------ + +A number of keys are available in the evaluation context of or surrounding +server actions: + +``self`` + the model object linked to the action via ``model_id`` +``object``, ``obj`` + only available if ``active_model`` and ``active_id`` are provided (via + context) otherwise ``None``. The actual record selected by ``active_id`` +``pool`` + the current database registry +``datetime``, ``dateutil``, ``time`` + corresponding Python modules +``cr`` + the current cursor +``user`` + the current user record +``context`` + execution context +``Warning`` + constructor for the ``Warning`` exception + +.. ignored uid (available through ``user``), workflow (available through + workflow methods on models) + +.. _reference/actions/report: Report Actions ============== + +.. todo:: sle-odoo + +.. _reference/actions/client: + +Client Actions (``ir.actions.client``) +====================================== + +Triggers an action implemented entirely in the client. + +``tag`` + the client-side identifier of the action, an arbitrary string which + the client should know how to react to +``params`` (optional) + a Python dictionary of additional data to send to the client, alongside + the client action tag + +:: + + { + "type": "ir.actions.client", + "tag": "pos.ui" + } + +tells the client to start the Point of Sale interface, the server has no idea +how the POS interface works. + +.. [#notquitem2m] technically not an M2M: adds a sequence field and may be + composed of just a view type, without a view id.