-: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 <reference/actions/client>` 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 <reference/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
+
+ <record model="ir.actions.act_window" id="test_action">
+ <field name="name">A Test Action</field>
+ <field name="res_model">some.model</field>
+ <field name="view_mode">graph</field>
+ <field name="view_id" ref="my_specific_view"/>
+ </record>
+
+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 <reference/actions/server/context>`
+``condition`` (optional)
+ evaluated as Python code using the server action's
+ :ref:`evaluation context <reference/actions/server/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
+<reference/actions/server/context>`. Only uses one specific type-specific
+field:
+
+``code``
+ a piece of Python code to execute when the action is called
+
+.. code-block:: xml
+
+ <record model="ir.actions.server" id="print_instance">
+ <field name="model_id" ref="model_res_partner"/>
+ <field name="code">
+ print self, object
+ </field>
+ </record>
+
+.. 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
+
+ <record model="ir.actions.server" id="print_instance">
+ <field name="model_id" ref="model_res_partner"/>
+ <field name="code">
+ if object.some_condition():
+ action = {
+ "type": "ir.actions.act_window",
+ "view_mode": "form",
+ "res_model": object._name,
+ "res_id": object.id,
+ }
+ </field>
+ </record>
+
+ 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
+<reference/data>`, 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/data>`.
+
+.. _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.
projects / odoo / odoo.git / commitdiff