[MERGE] trunk

bzr revid: al@openerp.com-20140227161819-p9chmskfifo0rygs

5 files changed, 167 insertions, 35 deletions

diff --git a/doc/03_module_dev_01.rst b/doc/03_module_dev_01.rst
index 0fbca9d14b4..f35dab539a4 100644
--- a/doc/03_module_dev_01.rst
+++ b/doc/03_module_dev_01.rst
@@ -172,40 +172,80 @@ is as follows:
      </data>
    </openerp>
 
-Record Tag
-//////////
+``<record>``
+////////////
 
-**Description**
+Defines a new record in a specified OpenERP model.
 
-The addition of new data is made with the record tag. This one takes a
-mandatory attribute : model. Model is the object name where the insertion has
-to be done. The tag record can also take an optional attribute: id. If this
-attribute is given, a variable of this name can be used later on, in the same
-file, to make reference to the newly created resource ID.
+``@model`` (required)
 
-A record tag may contain field tags. They indicate the record's fields value.
-If a field is not specified the default value will be used.
+    Name of the model in which this record will be created/inserted.
 
-The Record Field tag
-////////////////////
+``@id`` (optional)
 
-The attributes for the field tag are the following:
+    :term:`external ID` for the record, also allows referring to this record in
+    the rest of this file or in other files (through ``field/@ref`` or the
+    :py:func:`ref() <openerp.tools.convert._ref>` function)
 
-name : mandatory
-  the field name
+A record tag generally contains multiple ``field`` tags specifying the values
+set on the record's fields when creating it. Fields left out will be set to
+their default value unless required.
+
+``<field>``
+///////////
+
+In its most basic use, the ``field`` tag will set its body (as a string) as
+the value of the corresponding ``record``'s ``@name`` field.
+
+Extra attributes can either preprocess the body or replace its use entirely:
+
+``@name`` (mandatory)
+
+    Name of the field in the containing ``record``'s model
+
+``@type`` (optional)
+
+    One of ``char``, ``int``, ``float``, ``list``, ``tuple``, ``xml`` or
+    ``html``, ``file`` or ``base64``. Converts the ``field``'s body to the
+    specified type (or validates the body's content)
+
+    * ``xml`` will join multiple XML nodes under a single ``<data>`` root
+    * in ``xml`` and ``html``, external ids can be referenced using
+      ``%(id_name)s``
+    * ``list`` and ``tuple``'s element are specified using ``<value>``
+      sub-nodes with the same attributes as ``field``.
+    * ``file`` expects a module-local path and will save the path prefixed with
+      the current module's name, separated by a ``,`` (comma). For use with
+      :py:func:`~openerp.modules.module.get_module_resource`.
+    * ``base64`` expects binary data, encodes it to base64 and sets it. Mostly
+      useful with ``@file``
+
+``@file``
+
+    Can be used with types ``char`` and ``base64``, sources the field's content
+    from the specified file instead of the field's text body.
+
+``@model``
+
+    Model used for ``@search``'s search, or registry object put in context for
+    ``@eval``. Required if ``@search`` but optional if ``@eval``.
+
+``@eval`` (optional)
+
+    A Python expression evaluated to obtain the value to set on the record
+
+``@ref`` (optional)
 
-eval : optional
-  python expression that indicating the value to add
-  
-ref
-  reference to an id defined in this file
+    Links to an other record through its :term:`external id`. The module prefix
+    may be ommitted to link to a record defined in the same module.
 
-model
-  model to be looked up in the search
+``@search`` (optional)
 
-search
-  a query
+    Search domain (evaluated Python expression) into ``@model`` to get the
+    records to set on the field.
 
+    Sets all the matches found for m2m fields, the first id for other field
+    types.
 
 **Example**
 
diff --git a/doc/06_ir_qweb.rst b/doc/06_ir_qweb.rst
new file mode 100644
index 00000000000..4f3284d913f
--- /dev/null
+++ b/doc/06_ir_qweb.rst
@@ -0,0 +1,98 @@
+.. _qweb:
+
+====
+QWeb
+====
+
+``t-field``
+===========
+
+The server version of qweb includes a directive dedicated specifically to
+formatting and rendering field values from
+:class:`~openerp.osv.orm.browse_record` objects.
+
+The directive is implemented through
+:meth:`~base.ir.ir_qweb.QWeb.render_tag_field` on the ``ir.qweb`` openerp
+object, and generally delegates to converters for rendering. These converters
+are obtained through :meth:`~base.ir.ir_qweb.QWeb.get_converter_for`.
+
+By default, the key for obtaining a converter is the type of the field's
+column, but this can be overridden by providing a ``widget`` as field option.
+
+Field options are specified through ``t-field-options``, which must be a JSON
+object (map). Custom widgets may define their own (possibly mandatory) options.
+
+Global options
+--------------
+
+A global option ``html-escape`` is provided. It defaults to ``True``, and for
+many (not all) fields it determines whether the field's output will be
+html-escaped before being output.
+
+Date and datetime converters
+----------------------------
+
+The default rendering for ``date`` and ``datetime`` fields. They render the
+field's value according to the current user's ``lang.date_format`` and
+``lang.time_format``. The ``datetime`` converter will also localize the value
+to the user's timezone (as defined by the ``tz`` context key, or the timezone
+in the user's profile if there is no ``tz`` key in the context).
+
+A custom format can be provided to use a non-default rendering. The custom
+format uses the ``format`` options key, and uses the
+`ldml date format patterns`_ [#ldml]_.
+
+For instance if one wanted a date field to be rendered as
+"(month) (day of month)" rather than whatever the default is, one could use:
+
+.. code-block:: xml
+
+    <span t-field="object.datefield" t-field-options='{"format": "MMMM d"}'/>
+
+Monetary converter (widget: ``monetary``)
+-----------------------------------------
+
+Used to format and render monetary value, requires a ``display_currency``
+options value which is a path from the rendering context to a ``res.currency``
+object. This object is used to set the right currency symbol, and set it at the
+right position relative to the formatted value.
+
+The field itself should be a float field.
+
+Relative Datetime (widget: ``relative``)
+----------------------------------------
+
+Used on a ``datetime`` field, formats it relatively to the current time
+(``datetime.now()``), e.g. if the field's value is 3 hours before now and the
+user's lang is english, it will render to *3 hours ago*.
+
+.. note:: this field uses babel's ``format_timedelta`` more or less directly
+          and will only display the biggest unit and round up at 85% e.g.
+          1 hour 15 minutes will be rendered as *1 hour*, and 55 minutes will
+          also be rendered as *1 hour*.
+
+.. warning:: this converter *requires* babel 1.0 or more recent.
+
+Duration (widget: ``duration``)
+-------------------------------
+
+Renders a duration defined as a ``float`` to a human-readable localized string,
+e.g. ``1.5`` as hours in an english locale will be rendered to
+*1 hour 30 minutes*.
+
+Requires a ``unit`` option which may be one of ``second``, ``minute``,
+``hour``, ``day``, ``week``, ``month`` or ``year``. This specifies the unit in
+which the value should be interpreted before formatting.
+
+The duration must be a positive number, and no rounding is applied.
+
+.. [#ldml] in part because `babel`_ is used for rendering, as ``strftime``
+           would require altering the process's locale on the fly in order to
+           get correctly localized date and time output. Babel uses the CLDR
+           as its core and thus uses LDML date format patterns.
+
+.. _babel: http://babel.pocoo.org
+
+.. _ldml date format patterns:
+    http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns
+
diff --git a/doc/06_misc.rst b/doc/06_misc.rst
index 5a4ae7e008a..d56b26fb018 100644
--- a/doc/06_misc.rst
+++ b/doc/06_misc.rst
@@ -11,3 +11,4 @@ Miscellanous
    06_misc_user_img_specs.rst
    06_misc_import.rst
    06_misc_auto_join.rst
+   06_ir_qweb.rst
diff --git a/doc/conf.py b/doc/conf.py
index 57edef310c9..19f2c9b727f 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -252,5 +252,4 @@ texinfo_documents = [
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('http://docs.python.org/', None),
-    'openerpweb': ('http://doc.openerp.com/trunk/developers/web', None),
 }
diff --git a/doc/ir_actions.rst b/doc/ir_actions.rst
index 31d22a7ead9..e54df3ce377 100644
--- a/doc/ir_actions.rst
+++ b/doc/ir_actions.rst
@@ -12,26 +12,20 @@ Server actions
 
 .. currentmodule:: openerp.addons.base.ir.ir_actions
 
-.. autoclass:: actions_server
-  :noindex:
+.. autoclass:: ir_actions_server
+    :members: run, _get_states
 
 Adding a new sever action
 -------------------------
 
 The ``state`` field holds the various available types of server action. In order
-to add a new server action, the first thing to do is to override the ``_get_states``
+to add a new server action, the first thing to do is to override the :meth:`~.ir_actions_server._get_states`
 method that returns the list of values available for the selection field.
 
-.. automethod:: actions_server._get_states
-  :noindex:
-
-The method called when executing the server action is the ``run`` method. This
+The method called when executing the server action is the :meth:`~.ir_actions_server.run` method. This
 method calls ``run_action_<STATE>``. When adding a new server action type, you
 have to define the related method that will be called upon execution.
 
-.. automethod:: actions_server.run
-  :noindex:
-
 Changelog
 ---------