.. _module-dev-views:
Views and Events
================
Introduction to Views
---------------------
As all data of the program is stored in objects, as explained in the Objects
section, how are these objects exposed to the user ? We will try to answer this
question in this section.
First of all, let's note that every resource type uses its own interface. For
example, the screen to modify a partner's data is not the same as the one to
modify an invoice.
Then, you have to know that the OpenERP user interface is dynamic, it means
that it is not described "statically" by some code, but dynamically built from
XML descriptions of the client screens.
From now on, we will call these screen descriptions views.
A notable characteristic of these views is that they can be edited at any
moment (even during the program execution). After a modification to a displayed
view has occurred, you simply need to close the tab corresponding to that
'view' and re-open it for the changes to appear.
Views principles
++++++++++++++++
Views describe how each object (type of resource) is displayed. More precisely, for each object, we can define one (or several) view(s) to describe which fields should be drawn and how.
There are two types of views:
#. form views
#. tree views
.. note:: Since OpenERP 4.1, form views can also contain graphs.
Form views
----------
The field disposition in a form view always follows the same principle. Fields are distributed on the screen following the rules below:
* By default, each field is preceded by a label, with its name.
* Fields are placed on the screen from left to right, and from top to bottom, according to the order in which they are declared in the view.
* Every screen is divided into 4 columns, each column being able to contain either a label, or an "edition" field. As every edition field is preceded (by default) by a label with its name, there will be two fields (and their respective labels) on each line of the screen. The green and red zones on the screen-shot below, illustrate those 4 columns. They designate respectively the labels and their corresponding fields.
.. .. figure:: images/sale_order.png
.. :scale: 50
.. :align: center
Views also support more advanced placement options:
* A view field can use several columns. For example, on the screen-shot below, the zone in the blue frame is, in fact, the only field of a "one to many". We will come back later on this note, but let's note that it uses the whole width of the screen and not only one column.
.. .. figure:: images/sale_order_sale_order_lines.png
.. :scale: 50
.. :align: center
* We can also make the opposite operation: take a columns group and divide it in as many columns as desired. The surrounded green zones of the screen above are good examples. Precisely, the green framework up and on the right side takes the place of two columns, but contains 4 columns.
As we can see below in the purple zone of the screen, there is also a way to distribute the fields of an object on different tabs.
.. .. figure:: images/sale_order_notebook.png
.. :scale: 50
.. :align: center
On Change
+++++++++
The on_change attribute defines a method that is called when the content of a view field has changed.
This method takes at least arguments: cr, uid, ids, which are the three classical arguments and also the context dictionary. You can add parameters to the method. They must correspond to other fields defined in the view, and must also be defined in the XML with fields defined this way::
The example below is from the sale order view.
You can use the 'context' keyword to access data in the context that can be used as params of the function.::
.. code-block:: python
def onchange_shop_id(self, cr, uid, ids, shop_id):
v={}
if shop_id:
shop=self.pool.get('sale.shop').browse(cr,uid,shop_id)
v['project_id']=shop.project_id.id
if shop.pricelist_id.id:
v['pricelist_id']=shop.pricelist_id.id
v['payment_default_id']=shop.payment_default_id.id
return {'value':v}
When editing the shop_id form field, the onchange_shop_id method of the sale_order object is called and returns a dictionary where the 'value' key contains a dictionary of the new value to use in the 'project_id', 'pricelist_id' and 'payment_default_id' fields.
Note that it is possible to change more than just the values of
fields. For example, it is possible to change the value of some fields
and the domain of other fields by returning a value of the form:
return {'domain': d, 'value': value}
:returns: a dictionary with any mix of the following keys:
``domain``
A mapping of ``{field: domain}``.
The returned domains should be set on the fields instead of the
default ones.
``value``
A mapping of ``{field: value}}``, the values will be set on the
corresponding fields and may trigger new onchanges or attrs
changes
``warning`` A dict with the keys ``title`` and ``message``. Both
are mandatory. Indicate that an error message should be
displayed to the user.
Tree views
----------
These views are used when we work in list mode (in order to visualize several resources at once) and in the search screen. These views are simpler than the form views and thus have less options.
.. .. figure:: images/tree_view.png
.. :scale: 50
.. :align: center
Search views
--------------
Search views are a new feature of OpenERP supported as of version 6.0
It creates a customized search panel, and is declared quite similarly to a form view,
except that the view type and root element change to ``search`` instead of ``form``.
.. .. image:: images/search.png
.. :scale: 50
.. :align: center
Following is the list of new elements and features supported in search views.
Group tag
+++++++++
Unlike form group elements, search view groups support unlimited number of widget(fields or filters)
in a row (no automatic line wrapping), and only use the following attributes:
+ ``expand``: turns on the expander icon on the group (1 for expanded by default, 0 for collapsed)
+ ``string``: label for the group
.. code-block:: xml
In the screenshot above the green area is an expandable group.
Filter tag
+++++++++++
Filters are displayed as a toggle button on search panel
Filter elements can add new values in the current domain or context of the search view.
Filters can be added as a child element of field too, to indicate that they apply specifically
to that field (in this case the button's icon will smaller)
In the picture above the red area contains filters at the top of the form while
the blue area highlights a field and it's child filter.
.. code-block:: xml
Group By
++++++++
.. code-block:: xml
Above filters groups records sharing the same ``project_id`` value. Groups are loaded
lazily, so the inner records are only loaded when the group is expanded.
The group header lines contain the common values for all records in that group, and all numeric
fields currently displayed in the view are replaced by the sum of the values in that group.
It is also possible to group on multiple values by specifying a list of fields instead of a single string.
In this case nested groups will be displayed::
Fields
++++++
Field elements in search views are used to get user-provided values
for searches. As a result, as for group elements, they are quite
different than form view's fields:
* a search field can contain filters, which generally indicate that
both field and filter manage the same field and are related.
Those inner filters are rendered as smaller buttons, right next to
the field, and *must not* have a ``string`` attribute.
* a search field really builds a domain composed of ``[(field_name,
operator, field_value)]``. This domain can be overridden in two
ways:
* ``@operator`` replaces the default operator for the field (which
depends on its type)
* ``@filter_domain`` lets you provide a fully custom domain, which
will replace the default domain creation
* a search field does not create a context by default, but you can
provide an ``@context`` which will be evaluated and merged into the
wider context (as with a ``filter`` element).
To get the value of the field in your ``@context`` or
``@filter_domain``, you can use the variable ``self``:
.. code-block:: xml
or
.. code-block:: xml
Range fields (date, datetime, time)
"""""""""""""""""""""""""""""""""""
The range fields are composed of two input widgets (from and two)
instead of just one.
This leads to peculiarities (compared to non-range search fields):
* It is not possible to override the operator of a range field via
``@operator``, as the domain is built of two sections and each
section uses a different operator.
* Instead of being a simple value (integer, string, float) ``self``
for use in ``@filter_domain`` and ``@context`` is a ``dict``.
Because each input widget of a range field can be empty (and the
field itself will still be valid), care must be taken when using
``self``: it has two string keys ``"from"`` and ``"to"``, but any of
these keys can be either missing entirely or set to the value
``False``.
Actions for Search view
+++++++++++++++++++++++
After declaring a search view, it will be used automatically for all tree views on the same model.
If several search views exist for a single model, the one with the highest priority (lowest sequence) will
be used. Another option is to explicitly select the search view you want to use, by setting the
``search_view_id`` field of the action.
In addition to being able to pass default form values in the context of the action, OpenERP 6.0 now
supports passing initial values for search views too, via the context. The context keys need to match the
``search_default_XXX`` format. ``XXX`` may refer to the ``name`` of a ```` or ````
in the search view (as the ``name`` attribute is not required on filters, this only works for filters that have
an explicit ``name`` set). The value should be either the initial value for search fields, or
simply a boolean value for filters, to toggle them
.. code-block:: xml
Tasks
project.task
form
tree,form,calendar,gantt,graph
{"search_default_current":1,"search_default_user_id":uid}
Custom Filters
++++++++++++++
As of v6.0, all search views also features custom search filters, as show below.
Users can define their own custom filters using any of the fields available on the current model,
combining them with AND/OR operators. It is also possible to save any search context (the combination
of all currently applied domain and context values) as a personal filter, which can be recalled
at any time. Filters can also be turned into Shortcuts directly available in the User's homepage.
.. .. image:: images/filter.png
.. :scale: 50
.. :align: center
In above screenshot we filter Partner where Salesman = Demo user and Country = Belgium,
We can save this search criteria as a Shortcut or save as Filter.
Filters are user specific and can be modified via the Manage Filters option in the filters drop-down.
Graph views
-----------
A graph is a new mode of view for all views of type form. If, for example, a sale order line must be visible as list or as graph, define it like this in the action that open this sale order line. Do not set the view mode as "tree,form,graph" or "form,graph" - it must be "graph,tree" to show the graph first or "tree,graph" to show the list first. (This view mode is extra to your "form,tree" view and should have a separate menu item):
.. code-block:: xml
form
tree,graph
view_type::
tree = (tree with shortcuts at the left), form = (switchable view form/list)
view_mode::
tree,graph : sequences of the views when switching
Then, the user will be able to switch from one view to the other. Unlike forms and trees, OpenERP is not able to automatically create a view on demand for the graph type. So, you must define a view for this graph:
.. code-block:: xml
sale.order.line.graph
sale.order.line
graph
The graph view
A view of type graph is just a list of fields for the graph.
Graph tag
++++++++++
The default type of the graph is a pie chart - to change it to a barchart change **** to **** You also may change the orientation.
:Example :
.. code-block:: xml
Field tag
+++++++++
The first field is the X axis. The second one is the Y axis and the optional third one is the Z axis for 3 dimensional graphs. You can apply a few attributes to each field/axis:
* **group**: if set to true, the client will group all item of the same value for this field. For each other field, it will apply an operator
* **operator**: the operator to apply is another field is grouped. By default it's '+'. Allowed values are:
+ +: addition
+ \*: multiply
+ \**: exponent
+ min: minimum of the list
+ max: maximum of the list
:Defining real statistics on objects:
The easiest method to compute real statistics on objects is:
1. Define a statistic object which is a postgresql view
2. Create a tree view and a graph view on this object
You can get en example in all modules of the form: report\_.... Example: report_crm.
Controlling view actions
------------------------
When defining a view, the following attributes can be added on the
opening element of the view (i.e. ``