:banner: banners/flectra_qweb.jpg .. highlight:: xml .. _reference/qweb: ==== QWeb ==== QWeb is the primary templating_ engine used by Flectra\ [#othertemplates]_. It is an XML templating engine\ [#genshif]_ and used mostly to generate HTML_ fragments and pages. Template directives are specified as XML attributes prefixed with ``t-``, for instance ``t-if`` for :ref:`reference/qweb/conditionals`, with elements and other attributes being rendered directly. To avoid element rendering, a placeholder element ```` is also available, which executes its directive but doesn't generate any output in and of itself::

Test

will result in::

Test

if ``condition`` is true, but::

Test

will result in::

Test

.. _reference/qweb/output: data output =========== QWeb has a primary output directive which automatically HTML-escape its content limiting XSS_ risks when displaying user-provided content: ``esc``. ``esc`` takes an expression, evaluates it and prints the content::

rendered with the value ``value`` set to ``42`` yields::

42

There is one other output directive ``raw`` which behaves the same as respectively ``esc`` but *does not HTML-escape its output*. It can be useful to display separately constructed markup (e.g. from functions) or already sanitized user-provided markup. .. _reference/qweb/conditionals: conditionals ============ QWeb has a conditional directive ``if``, which evaluates an expression given as attribute value::

ok

The element is rendered if the condition is true::

ok

but if the condition is false it is removed from the result::
The conditional rendering applies to the bearer of the directive, which does not have to be ````::

ok

will give the same results as the previous example. Extra conditional branching directives ``t-elif`` and ``t-else`` are also available::

Happy bithday!

Welcome master!

Welcome!

.. _reference/qweb/loops: loops ===== QWeb has an iteration directive ``foreach`` which take an expression returning the collection to iterate on, and a second parameter ``t-as`` providing the name to use for the "current item" of the iteration::

will be rendered as::

1

2

3

Like conditions, ``foreach`` applies to the element bearing the directive's attribute, and ::

is equivalent to the previous example. ``foreach`` can iterate on an array (the current item will be the current value), a mapping (the current item will be the current key) or an integer (equivalent to iterating on an array between 0 inclusive and the provided integer exclusive). In addition to the name passed via ``t-as``, ``foreach`` provides a few other variables for various data points: .. warning:: ``$as`` will be replaced by the name passed to ``t-as`` :samp:`{$as}_all` the object being iterated over :samp:`{$as}_value` the current iteration value, identical to ``$as`` for lists and integers, but for mappings it provides the value (where ``$as`` provides the key) :samp:`{$as}_index` the current iteration index (the first item of the iteration has index 0) :samp:`{$as}_size` the size of the collection if it is available :samp:`{$as}_first` whether the current item is the first of the iteration (equivalent to :samp:`{$as}_index == 0`) :samp:`{$as}_last` whether the current item is the last of the iteration (equivalent to :samp:`{$as}_index + 1 == {$as}_size`), requires the iteratee's size be available :samp:`{$as}_parity` either ``"even"`` or ``"odd"``, the parity of the current iteration round :samp:`{$as}_even` a boolean flag indicating that the current iteration round is on an even index :samp:`{$as}_odd` a boolean flag indicating that the current iteration round is on an odd index These extra variables provided and all new variables created into the ``foreach`` are only available in the scope of the``foreach``. If the variable exists outside the context of the ``foreach``, the value is copied at the end of the foreach into the global context. ::

.. _reference/qweb/attributes: attributes ========== QWeb can compute attributes on-the-fly and set the result of the computation on the output node. This is done via the ``t-att`` (attribute) directive which exists in 3 different forms: :samp:`t-att-{$name}` an attribute called ``$name`` is created, the attribute value is evaluated and the result is set as the attribute's value::
will be rendered as::
:samp:`t-attf-{$name}` same as previous, but the parameter is a :term:`format string` instead of just an expression, often useful to mix literal and non-literal string (e.g. classes)::
  • will be rendered as::
  • 1
  • 2
  • 3
  • :samp:`t-att=mapping` if the parameter is a mapping, each (key, value) pair generates a new attribute and its value::
    will be rendered as::
    :samp:`t-att=pair` if the parameter is a pair (tuple or array of 2 element), the first item of the pair is the name of the attribute and the second item is the value::
    will be rendered as::
    setting variables ================= QWeb allows creating variables from within the template, to memoize a computation (to use it multiple times), give a piece of data a clearer name, ... This is done via the ``set`` directive, which takes the name of the variable to create. The value to set can be provided in two ways: * a ``t-value`` attribute containing an expression, and the result of its evaluation will be set:: will print ``3`` * if there is no ``t-value`` attribute, the node's body is rendered and set as the variable's value::
  • ok
  • will generate ``<li>ok</li>`` (the content is escaped as we used the ``esc`` directive) .. note:: using the result of this operation is a significant use-case for the ``raw`` directive. calling sub-templates ===================== QWeb templates can be used for top-level rendering, but they can also be used from within another template (to avoid duplication or give names to parts of templates) using the ``t-call`` directive:: This calls the named template with the execution context of the parent, if ``other_template`` is defined as::

    the call above will be rendered as ``

    `` (no content), but:: will be rendered as ``

    1

    ``. However this has the problem of being visible from outside the ``t-call``. Alternatively, content set in the body of the ``call`` directive will be evaluated *before* calling the sub-template, and can alter a local context:: The body of the ``call`` directive can be arbitrarily complex (not just ``set`` directives), and its rendered form will be available within the called template as a magical ``0`` variable::
    This template was called with content:
    being called thus:: content will result in::
    This template was called with content: content
    Python ====== Exclusive directives -------------------- asset bundles ''''''''''''' .. todo:: have fme write these up because I've no idea how they work "smart records" fields formatting ''''''''''''''''''''''''''''''''' The ``t-field`` directive can only be used when performing field access (``a.b``) on a "smart" record (result of the ``browse`` method). It is able to automatically format based on field type, and is integrated in the website's rich text edition. ``t-options`` can be used to customize fields, the most common option is ``widget``, other options are field- or widget-dependent. debugging --------- ``t-debug`` invokes a debugger using PDB's ``set_trace`` API. The parameter should be the name of a module, on which a ``set_trace`` method is called:: is equivalent to ``importlib.import_module("pdb").set_trace()`` Helpers ------- Request-based ''''''''''''' Most Python-side uses of QWeb are in controllers (and during HTTP requests), in which case templates stored in the database (as :ref:`views `) can be trivially rendered by calling :meth:`flectra.http.HttpRequest.render`: .. code-block:: python response = http.request.render('my-template', { 'context_value': 42 }) This automatically creates a :class:`~flectra.http.Response` object which can be returned from the controller (or further customized to suit). View-based '''''''''' At a deeper level than the previous helper is the ``render`` method on ``ir.ui.view``: .. py:method:: render(cr, uid, id[, values][, engine='ir.qweb][, context]) Renders a QWeb view/template by database id or :term:`external id`. Templates are automatically loaded from ``ir.ui.view`` records. Sets up a number of default values in the rendering context: ``request`` the current :class:`~flectra.http.WebRequest` object, if any ``debug`` whether the current request (if any) is in ``debug`` mode :func:`quote_plus ` url-encoding utility function :mod:`json` the corresponding standard library module :mod:`time` the corresponding standard library module :mod:`datetime` the corresponding standard library module `relativedelta `_ see module ``keep_query`` the ``keep_query`` helper function :param values: context values to pass to QWeb for rendering :param str engine: name of the Flectra model to use for rendering, can be used to expand or customize QWeb locally (by creating a "new" qweb based on ``ir.qweb`` with alterations) .. _reference/qweb/javascript: .. todo:: the members below are no longer relevant, section to rewrite .. API .. --- .. It is also possible to use the ``ir.qweb`` model directly (and extend it, and .. inherit from it): .. .. automodule:: flectra.addons.base.ir.ir_qweb .. :members: QWeb, QWebContext, FieldConverter, QwebWidget Javascript ========== Exclusive directives -------------------- defining templates '''''''''''''''''' The ``t-name`` directive can only be placed at the top-level of a template file (direct children to the document root):: It takes no other parameter, but can be used with a ```` element or any other. With a ```` element, the ```` should have a single child. The template name is an arbitrary string, although when multiple templates are related (e.g. called sub-templates) it is customary to use dot-separated names to indicate hierarchical relationships. template inheritance '''''''''''''''''''' Template inheritance is used to alter existing templates in-place, e.g. to add information to templates created by an other modules. Template inheritance is performed via the ``t-extend`` directive which takes the name of the template to alter as parameter. The alteration is then performed with any number of ``t-jquery`` sub-directives::
  • new element
  • The ``t-jquery`` directives takes a `CSS selector`_. This selector is used on the extended template to select *context nodes* to which the specified ``t-operation`` is applied: ``append`` the node's body is appended at the end of the context node (after the context node's last child) ``prepend`` the node's body is prepended to the context node (inserted before the context node's first child) ``before`` the node's body is inserted right before the context node ``after`` the node's body is inserted right after the context node ``inner`` the node's body replaces the context node's children ``replace`` the node's body is used to replace the context node itself No operation if no ``t-operation`` is specified, the template body is interpreted as javascript code and executed with the context node as ``this`` .. warning:: while much more powerful than other operations, this mode is also much harder to debug and maintain, it is recommended to avoid it debugging --------- The javascript QWeb implementation provides a few debugging hooks: ``t-log`` takes an expression parameter, evaluates the expression during rendering and logs its result with ``console.log``:: will print ``42`` to the console ``t-debug`` triggers a debugger breakpoint during template rendering:: will stop execution if debugging is active (exact condition depend on the browser and its development tools) ``t-js`` the node's body is javascript code executed during template rendering. Takes a ``context`` parameter, which is the name under which the rendering context will be available in the ``t-js``'s body:: console.log("Foo is", ctx.foo); Helpers ------- .. js:attribute:: core.qweb (core is the ``web.core`` module) An instance of :js:class:`QWeb2.Engine` with all module-defined template files loaded, and references to standard helper objects ``_`` (underscore), ``_t`` (translation function) and JSON_. :js:func:`core.qweb.render ` can be used to easily render basic module templates API --- .. js:class:: QWeb2.Engine The QWeb "renderer", handles most of QWeb's logic (loading, parsing, compiling and rendering templates). OpenERP Web instantiates one for the user in the core module, and exports it to ``core.qweb``. It also loads all the template files of the various modules into that QWeb instance. A :js:class:`QWeb2.Engine` also serves as a "template namespace". .. js:function:: QWeb2.Engine.render(template[, context]) Renders a previously loaded template to a String, using ``context`` (if provided) to find the variables accessed during template rendering (e.g. strings to display). :param String template: the name of the template to render :param Object context: the basic namespace to use for template rendering :returns: String The engine exposes an other method which may be useful in some cases (e.g. if you need a separate template namespace with, in OpenERP Web, Kanban views get their own :js:class:`QWeb2.Engine` instance so their templates don't collide with more general "module" templates): .. js:function:: QWeb2.Engine.add_template(templates) Loads a template file (a collection of templates) in the QWeb instance. The templates can be specified as: An XML string QWeb will attempt to parse it to an XML document then load it. A URL QWeb will attempt to download the URL content, then load the resulting XML string. A ``Document`` or ``Node`` QWeb will traverse the first level of the document (the child nodes of the provided root) and load any named template or template override. :type templates: String | Document | Node A :js:class:`QWeb2.Engine` also exposes various attributes for behavior customization: .. js:attribute:: QWeb2.Engine.prefix Prefix used to recognize directives during parsing. A string. By default, ``t``. .. js:attribute:: QWeb2.Engine.debug Boolean flag putting the engine in "debug mode". Normally, QWeb intercepts any error raised during template execution. In debug mode, it leaves all exceptions go through without intercepting them. .. js:attribute:: QWeb2.Engine.jQuery The jQuery instance used during template inheritance processing. Defaults to ``window.jQuery``. .. js:attribute:: QWeb2.Engine.preprocess_node A ``Function``. If present, called before compiling each DOM node to template code. In OpenERP Web, this is used to automatically translate text content and some attributes in templates. Defaults to ``null``. .. [#genshif] it is similar in that to Genshi_, although it does not use (and has no support for) `XML namespaces`_ .. [#othertemplates] although it uses a few others, either for historical reasons or because they remain better fits for the use case. Flectra 9.0 still depends on Jinja_ and Mako_. .. _templating: http://en.wikipedia.org/wiki/Template_processor .. _Jinja: http://jinja.pocoo.org .. _Mako: http://www.makotemplates.org .. _Genshi: http://genshi.edgewall.org .. _XML namespaces: http://en.wikipedia.org/wiki/XML_namespace .. _HTML: http://en.wikipedia.org/wiki/HTML .. _XSS: http://en.wikipedia.org/wiki/Cross-site_scripting .. _JSON: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON .. _CSS selector: http://api.jquery.com/category/selectors/