flectra/doc/reference/javascript.rst

:banner: banners/flectra_javascript.jpg

.. highlight:: javascript

.. default-domain:: js

==========
Javascript
==========

.. automodule:: *
    :members:

=======
Widgets
=======

:class:`~Widget`

    Exported in ``web.Widget``, the base class for all visual components.
    It corresponds to an MVC view, and provides a number of service to
    simplify handling of a section of a page:

    * Handles parent/child relationships between widgets
    * Provides extensive lifecycle management with safety features (e.g.
      automatically destroying children widgets during the destruction of a
      parent)
    * Automatic rendering with :ref:`qweb <reference/qweb>`
    * Backbone-compatible shortcuts

DOM Root
--------

A :class:`~Widget` is responsible for a section of the page
materialized by the DOM root of the widget.

A widget's DOM root is available via two attributes:

.. attribute:: Widget.el

    raw DOM element set as root to the widget

.. attribute:: Widget.$el

    jQuery wrapper around :attr:`~Widget.el`

There are two main ways to define and generate this DOM root:

.. attribute:: Widget.template

    Should be set to the name of a :ref:`QWeb template <reference/qweb>`.
    If set, the template will be rendered after the widget has been
    initialized but before it has been started. The root element generated by
    the template will be set as the DOM root of the widget.

.. attribute:: Widget.tagName

    Used if the widget has no template defined. Defaults to ``div``,
    will be used as the tag name to create the DOM element to set as
    the widget's DOM root. It is possible to further customize this
    generated DOM root with the following attributes:

    .. attribute:: Widget.id

        Used to generate an ``id`` attribute on the generated DOM
        root.

    .. attribute:: Widget.className

        Used to generate a ``class`` attribute on the generated DOM root.

    .. attribute:: Widget.attributes

        Mapping (object literal) of attribute names to attribute
        values. Each of these k:v pairs will be set as a DOM attribute
        on the generated DOM root.

    None of these is used in case a template is specified on the widget.

The DOM root can also be defined programmatically by overridding

.. function:: Widget.renderElement

    Renders the widget's DOM root and sets it. The default
    implementation will render a set template or generate an element
    as described above, and will call
    :func:`~Widget.setElement` on the result.

    Any override to :func:`~Widget.renderElement` which
    does not call its ``_super`` **must** call
    :func:`~Widget.setElement` with whatever it
    generated or the widget's behavior is undefined.

    .. note::

        The default :func:`~Widget.renderElement` can
        be called repeatedly, it will *replace* the previous DOM root
        (using ``replaceWith``). However, this requires that the
        widget correctly sets and unsets its events (and children
        widgets). Generally, :func:`~Widget.renderElement` should
        not be called repeatedly unless the widget advertizes this feature.

Using a widget
''''''''''''''

A widget's lifecycle has 3 main phases:

* creation and initialization of the widget instance

  .. function:: Widget.init(parent)

       initialization method of widgets, synchronous, can be overridden to
       take more parameters from the widget's creator/parent

       :param parent: the new widget's parent, used to handle automatic
                      destruction and event propagation. Can be ``null`` for
                      the widget to have no parent.
       :type parent: :class:`~Widget`

* DOM injection and startup, this is done by calling one of:

  .. function:: Widget.appendTo(element)

    Renders the widget and inserts it as the last child of the target, uses
    `.appendTo()`_

  .. function:: Widget.prependTo(element)

    Renders the widget and inserts it as the first child of the target, uses
    `.prependTo()`_

  .. function:: Widget.insertAfter(element)

    Renders the widget and inserts it as the preceding sibling of the target,
    uses `.insertAfter()`_

  .. function:: Widget.insertBefore(element)

    Renders the widget and inserts it as the following sibling of the target,
    uses `.insertBefore()`_

  All of these methods accept whatever the corresponding jQuery method accepts
  (CSS selectors, DOM nodes or jQuery objects). They all return a deferred_
  and are charged with three tasks:

  * rendering the widget's root element via
    :func:`~Widget.renderElement`
  * inserting the widget's root element in the DOM using whichever jQuery
    method they match
  * starting the widget, and returning the result of starting it

    .. function:: Widget.start()

        asynchronous startup of the widget once it's been injected in the DOM,
        generally used to perform asynchronous RPC calls to fetch whatever
        remote data is necessary for the widget to do its work.

        Must return a deferred_ to indicate when its work is done.

        A widget is *not guaranteed* to work correctly until its
        :func:`~Widget.start` method has finished executing. The
        widget's parent/creator must wait for a widget to be fully started
        before interacting with it

        :returns: deferred_ object

* widget destruction and cleanup

  .. function:: Widget.destroy()

    destroys the widget's children, unbinds its events and removes its root
    from the DOM. Automatically called when the widget's parent is destroyed,
    must be called explicitly if the widget has no parents or if it is
    removed but its parent remains.

    A widget being destroyed is automatically unlinked from its parent.

Related to widget destruction is an important utility method:

.. function:: Widget.alive(deferred[, reject=false])

    A significant issue with RPC and destruction is that an RPC call may take
    a long time to execute and return while a widget is being destroyed or
    after it has been destroyed, trying to execute its operations on a widget
    in a broken/invalid state.

    This is a frequent source of errors or strange behaviors.

    :func:`~Widget.alive` can be used to wrap an RPC call,
    ensuring that whatever operations should be executed when the call ends
    are only executed if the widget is still alive::

        this.alive(this.model.query().all()).then(function (records) {
            // would break if executed after the widget is destroyed, wrapping
            // rpc in alive() prevents execution
            _.each(records, function (record) {
                self.$el.append(self.format(record));
            });
        });

    :param deferred: a deferred_ object to wrap
    :param reject: by default, if the RPC call returns after the widget has
                   been destroyed the returned deferred_ is left in limbo
                   (neither resolved nor rejected). If ``reject`` is set to
                   ``true``, the deferred_ will be rejected instead.
    :returns: deferred_ object

.. function:: Widget.isDestroyed()

    :returns: ``true`` if the widget is being or has been destroyed, ``false``
              otherwise

Accessing DOM content
'''''''''''''''''''''

Because a widget is only responsible for the content below its DOM root, there
 is a shortcut for selecting sub-sections of a widget's DOM:

.. function:: Widget.$(selector)

    Applies the CSS selector specified as parameter to the widget's
    DOM root::

        this.$(selector);

    is functionally identical to::

        this.$el.find(selector);

    :param String selector: CSS selector
    :returns: jQuery object

    .. note:: this helper method is similar to ``Backbone.View.$``

Resetting the DOM root
''''''''''''''''''''''

.. function:: Widget.setElement(element)

    Re-sets the widget's DOM root to the provided element, also
    handles re-setting the various aliases of the DOM root as well as
    unsetting and re-setting delegated events.

    :param Element element: a DOM element or jQuery object to set as
                            the widget's DOM root

    .. note:: should be mostly compatible with `Backbone's
              setElement`_

DOM events handling
-------------------

A widget will generally need to respond to user action within its
section of the page. This entails binding events to DOM elements.

To this end, :class:`~Widget` provides a shortcut:

.. attribute:: Widget.events

    Events are a mapping of an event selector (an event name and an optional
    CSS selector separated by a space) to a callback. The callback can
    be the name of a widget's method or a function object. In either case, the
    ``this`` will be set to the widget::

        events: {
            'click p.oe_some_class a': 'some_method',
            'change input': function (e) {
                e.stopPropagation();
            }
        },

    The selector is used for jQuery's `event delegation`_, the
    callback will only be triggered for descendants of the DOM root
    matching the selector\ [#eventsdelegation]_. If the selector is left out
    (only an event name is specified), the event will be set directly on the
    widget's DOM root.

.. function:: Widget.delegateEvents

    This method is in charge of binding :attr:`~Widget.events` to the
    DOM. It is automatically called after setting the widget's DOM root.

    It can be overridden to set up more complex events than the
    :attr:`~Widget.events` map allows, but the parent should always be
    called (or :attr:`~Widget.events` won't be handled correctly).

.. function:: Widget.undelegateEvents

    This method is in charge of unbinding :attr:`~Widget.events` from
    the DOM root when the widget is destroyed or the DOM root is reset, in
    order to avoid leaving "phantom" events.

    It should be overridden to un-set any event set in an override of
    :func:`~Widget.delegateEvents`.

.. note:: this behavior should be compatible with `Backbone's
          delegateEvents`_, apart from not accepting any argument.

Subclassing Widget
------------------

:class:`~Widget` is subclassed in the standard manner (via the
:func:`~Class.extend` method), and provides a number of
abstract properties and concrete methods (which you may or may not want to
override). Creating a subclass looks like this::

    var MyWidget = Widget.extend({
        // QWeb template to use when rendering the object
        template: "MyQWebTemplate",
        events: {
            // events binding example
            'click .my-button': 'handle_click',
        },

        init: function(parent) {
            this._super(parent);
            // insert code to execute before rendering, for object
            // initialization
        },
        start: function() {
            var sup = this._super();
            // post-rendering initialization code, at this point

            // allows multiplexing deferred objects
            return $.when(
                // propagate asynchronous signal from parent class
                sup,
                // return own's asynchronous signal
                this.rpc(/* … */))
        }
    });

The new class can then be used in the following manner::

    // Create the instance
    var my_widget = new MyWidget(this);
    // Render and insert into DOM
    my_widget.appendTo(".some-div");

After these two lines have executed (and any promise returned by
:func:`~Widget.appendTo` has been resolved if needed), the widget is
ready to be used.

.. note:: the insertion methods will start the widget themselves, and will
          return the result of :func:`~Widget.start()`.

          If for some reason you do not want to call these methods, you will
          have to first call :func:`~Widget.render()` on the
          widget, then insert it into your DOM and start it.

If the widget is not needed anymore (because it's transient), simply terminate
it::

    my_widget.destroy();

will unbind all DOM events, remove the widget's content from the DOM and
destroy all widget data.

Development Guidelines
----------------------

* Identifiers (``id`` attribute) should be avoided. In generic applications
  and modules, ``id`` limits the re-usability of components and tends to make
  code more brittle. Most of the time, they can be replaced with nothing,
  classes or keeping a reference to a DOM node or jQuery element.

  If an ``id`` is absolutely necessary (because a third-party library requires
  one), the id should be partially generated using ``_.uniqueId()`` e.g.::

      this.id = _.uniqueId('my-widget-')
* Avoid predictable/common CSS class names. Class names such as "content" or
  "navigation" might match the desired meaning/semantics, but it is likely an
  other developer will have the same need, creating a naming conflict and
  unintended behavior. Generic class names should be prefixed with e.g. the
  name of the component they belong to (creating "informal" namespaces, much
  as in C or Objective-C).
* Global selectors should be avoided. Because a component may be used several
  times in a single page (an example in Flectra is dashboards), queries should be
  restricted to a given component's scope. Unfiltered selections such as
  ``$(selector)`` or ``document.querySelectorAll(selector)`` will generally
  lead to unintended or incorrect behavior.  Flectra Web's
  :class:`~Widget` has an attribute providing its DOM root
  (:attr:`~Widget.$el`), and a shortcut to select nodes directly
  (:func:`~Widget.$`).
* More generally, never assume your components own or controls anything beyond
  its own personal :attr:`~Widget.$el`
* html templating/rendering should use QWeb unless absolutely trivial.
* All interactive components (components displaying information to the screen
  or intercepting DOM events) must inherit from :class:`~Widget`
  and correctly implement and use its API and life cycle.

.. _.appendTo():
    http://api.jquery.com/appendTo/

.. _.prependTo():
    http://api.jquery.com/prependTo/

.. _.insertAfter():
    http://api.jquery.com/insertAfter/

.. _.insertBefore():
    http://api.jquery.com/insertBefore/

.. _event delegation:
    http://api.jquery.com/delegate/

.. _Backbone's setElement:
    http://backbonejs.org/#View-setElement

.. _Backbone's delegateEvents:
    http://backbonejs.org/#View-delegateEvents

.. _deferred: http://api.jquery.com/category/deferred-object/

====
RPC
====


To display and interact with data, calls to the Flectra server are necessary.
This is performed using :abbr:`RPC <Remote Procedure Call>`.

Flectra Web provides two primary APIs to handle this: a low-level
JSON-RPC based API communicating with the Python section of Flectra
Web (and of your module, if you have a Python part) and a high-level
API above that allowing your code to talk directly to high-level Flectra models.

All networking APIs are :ref:`asynchronous <reference/async>`. As a result,
all of them will return Deferred_ objects (whether they resolve those with
values or not). Understanding how those work before before moving on is
probably necessary.

High-level API: calling into Flectra models
-------------------------------------------

Access to Flectra object methods (made available through XML-RPC from the server)
is done via :class:`Model`. It maps onto the Flectra server objects via two primary
methods, :func:`~Model.call` (exported in ``web.Model``) and :func:`~Model.query`
(exported in ``web.DataModel``, only available in the backend client).

:func:`~Model.call` is a direct mapping to the corresponding method of
the Flectra server object. Its usage is similar to that of the Flectra Model API,
with three differences:

* The interface is :ref:`asynchronous <reference/async>`, so instead of
  returning results directly RPC method calls will return
  Deferred_ instances, which will themselves resolve to the
  result of the matching RPC call.

* Because ECMAScript 3/Javascript 1.5 doesnt feature any equivalent to
  ``__getattr__`` or ``method_missing``, there needs to be an explicit
  method to dispatch RPC methods.

* No notion of pooler, the model proxy is instantiated where needed,
  not fetched from an other (somewhat global) object::

    var Users = new Model('res.users');

    Users.call('change_password', ['oldpassword', 'newpassword'],
                      {context: some_context}).then(function (result) {
        // do something with change_password result
    });

:func:`~Model.query` is a shortcut for a builder-style
interface to searches (``search`` + ``read`` in Flectra RPC terms). It
returns a :class:`~flectra.web.Query` object which is immutable but
allows building new :class:`~flectra.web.Query` instances from the
first one, adding new properties or modifiying the parent object's::

    Users.query(['name', 'login', 'user_email', 'signature'])
         .filter([['active', '=', true], ['company_id', '=', main_company]])
         .limit(15)
         .all().then(function (users) {
        // do work with users records
    });

The query is only actually performed when calling one of the query
serialization methods, :func:`~flectra.web.Query.all` and
:func:`~flectra.web.Query.first`. These methods will perform a new
RPC call every time they are called.

For that reason, it's actually possible to keep "intermediate" queries
around and use them differently/add new specifications on them.

.. class:: Model(name)

    .. attribute:: Model.name

        name of the model this object is bound to

    .. function:: Model.call(method[, args][, kwargs])

         Calls the ``method`` method of the current model, with the
         provided positional and keyword arguments.

         :param String method: method to call over rpc on the
                               :attr:`~Model.name`
         :param Array<> args: positional arguments to pass to the
                              method, optional
         :param Object<> kwargs: keyword arguments to pass to the
                                 method, optional
         :rtype: Deferred<>

    .. function:: Model.query(fields)

         :param Array<String> fields: list of fields to fetch during
                                      the search
         :returns: a :class:`~flectra.web.Query` object
                   representing the search to perform

.. class:: flectra.web.Query(fields)

    The first set of methods is the "fetching" methods. They perform
    RPC queries using the internal data of the object they're called
    on.

    .. function:: flectra.web.Query.all()

        Fetches the result of the current :class:`~flectra.web.Query` object's
        search.

        :rtype: Deferred<Array<>>

    .. function:: flectra.web.Query.first()

       Fetches the **first** result of the current
       :class:`~flectra.web.Query`, or ``null`` if the current
       :class:`~flectra.web.Query` does have any result.

       :rtype: Deferred<Object | null>

    .. function:: flectra.web.Query.count()

       Fetches the number of records the current
       :class:`~flectra.web.Query` would retrieve.

       :rtype: Deferred<Number>

    .. function:: flectra.web.Query.group_by(grouping...)

       Fetches the groups for the query, using the first specified
       grouping parameter

       :param Array<String> grouping: Lists the levels of grouping
                                      asked of the server. Grouping
                                      can actually be an array or
                                      varargs.
       :rtype: Deferred<Array<flectra.web.QueryGroup>> | null

    The second set of methods is the "mutator" methods, they create a
    **new** :class:`~flectra.web.Query` object with the relevant
    (internal) attribute either augmented or replaced.

    .. function:: flectra.web.Query.context(ctx)

       Adds the provided ``ctx`` to the query, on top of any existing
       context

    .. function:: flectra.web.Query.filter(domain)

       Adds the provided domain to the query, this domain is
       ``AND``-ed to the existing query domain.

    .. function:: opeenrp.web.Query.offset(offset)

       Sets the provided offset on the query. The new offset
       *replaces* the old one.

    .. function:: flectra.web.Query.limit(limit)

       Sets the provided limit on the query. The new limit *replaces*
       the old one.

    .. function:: flectra.web.Query.order_by(fields…)

       Overrides the model's natural order with the provided field
       specifications. Behaves much like Django's :py:meth:`QuerySet.order_by
       <django.db.models.query.QuerySet.order_by>`:

       * Takes 1..n field names, in order of most to least importance
         (the first field is the first sorting key). Fields are
         provided as strings.

       * A field specifies an ascending order, unless it is prefixed
         with the minus sign "``-``" in which case the field is used
         in the descending order

       Divergences from Django's sorting include a lack of random sort
       (``?`` field) and the inability to "drill down" into relations
       for sorting.

Aggregation (grouping)
''''''''''''''''''''''

Flectra has powerful grouping capacities, but they are kind-of strange
in that they're recursive, and level n+1 relies on data provided
directly by the grouping at level n. As a result, while
:py:meth:`flectra.models.Model.read_group` works it's not a very intuitive
API.

Flectra Web eschews direct calls to :py:meth:`~flectra.models.Model.read_group`
in favor of calling a method of :class:`~flectra.web.Query`, :py:meth:`much
in the way it is done in SQLAlchemy <sqlalchemy.orm.query.Query.group_by>`
[#terminal]_::

    some_query.group_by(['field1', 'field2']).then(function (groups) {
        // do things with the fetched groups
    });

This method is asynchronous when provided with 1..n fields (to group
on) as argument, but it can also be called without any field (empty
fields collection or nothing at all). In this case, instead of
returning a Deferred object it will return ``null``.

When grouping criterion come from a third-party and may or may not
list fields (e.g. could be an empty list), this provides two ways to
test the presence of actual subgroups (versus the need to perform a
regular query for records):

* A check on ``group_by``'s result and two completely separate code
  paths::

      var groups;
      if (groups = some_query.group_by(gby)) {
          groups.then(function (gs) {
              // groups
          });
      }
      // no groups

* Or a more coherent code path using :func:`when`'s ability to
  coerce values into deferreds::

      $.when(some_query.group_by(gby)).then(function (groups) {
          if (!groups) {
              // No grouping
          } else {
              // grouping, even if there are no groups (groups
              // itself could be an empty array)
          }
      });

The result of a (successful) :func:`~flectra.web.Query.group_by` is
an array of :class:`~flectra.web.QueryGroup`:

.. class:: flectra.web.QueryGroup

    .. function:: flectra.web.QueryGroup.get(key)

        returns the group's attribute ``key``. Known attributes are:

        ``grouped_on``
            which grouping field resulted from this group
        ``value``
            ``grouped_on``'s value for this group
        ``length``
            the number of records in the group
        ``aggregates``
            a {field: value} mapping of aggregations for the group

    .. function:: flectra.web.QueryGroup.query([fields...])

        equivalent to :func:`Model.query` but pre-filtered to
        only include the records within this group. Returns a
        :class:`~flectra.web.Query` which can be further manipulated as
        usual.

    .. function:: flectra.web.QueryGroup.subgroups()

        returns a deferred to an array of :class:`~flectra.web.QueryGroup`
        below this one

Low-level API: RPC calls to Python side
---------------------------------------

While the previous section is great for calling core OpenERP code
(models code), it does not work if you want to call the Python side of
Flectra Web.

For this, a lower-level API exists on on
:class:`~Session` objects (the class is exported in ``web.Session``, but
an instance isusually available through ``web.session``): the ``rpc`` method.

This method simply takes an absolute path (the absolute URL of the JSON
:ref:`route <reference/http/routing>` to call) and a mapping of attributes to
values (passed as keyword arguments to the Python method). This function
fetches the return value of the Python methods, converted to JSON.

For instance, to call the ``resequence`` of the
:class:`~web.controllers.main.DataSet` controller::

    session.rpc('/web/dataset/resequence', {
        model: some_model,
        ids: array_of_ids,
        offset: 42
    }).then(function (result) {
        // resequence didn't error out
    }, function () {
        // an error occured during during call
    });

.. _reference/javascript/client:

===========
Web Client
===========

Javascript module system overview
---------------------------------

A new module system (inspired from requirejs) has now been deployed.
It has many advantages over the Flectra version 8 system.

* loading order: dependencies are guaranteed to be loaded first, even if
  files are not loaded in the correct order in the bundle files.
* easier to split a file into smaller logical units.
* no global variables: easier to reason.
* it is possible to examine every dependencies and dependants.  This
  makes refactoring much simpler, and less risky.

It has also some disadvantages:

* files are required to use the module system if they want to interact 
  with flectra, since the various objects are only available in the module
  system, and not in global variables
* circular dependencies are not supported.  It makes sense, but it means
  that one needs to be careful.

This is obviously a very large change and will require everyone to
adopt new habits.  For example, the variable flectra does not exist
anymore.  The new way of doing things is to import explicitely the module 
you need, and declaring explicitely the objects you export.  Here is a
simple example::

    flectra.define('addon_name.service', function (require) {
        var utils = require('web.utils');
        var Model = require('web.Model');

        // do things with utils and Model
        var something_useful = 15;
        return  {
            something_useful: something_useful,
        };
    });

This snippet shows a module named ``addon_name.service``.  It is defined
with the ``flectra.define`` function.  ``flectra.define`` takes a name and a
function for arguments:

* The name is the concatenation of the name of the addon it is defined in
  and a name describing its purpose.
* The function is the place where the javascript module is actually
  defined.  It takes a function ``require`` as first argument, and
  returns something (or not, depending if it needs to export something).
  The ``require`` function is used to get a handle on the dependencies.
  In this case, it gives a handle on two javascript modules from the 
  ``web`` addon, namely ``web.utils`` and ``web.Model``.

The idea is that you define what you need to import (by using the
``require`` function) and declare what you export (by returning
something).  The web client will then make sure that your code is loaded
properly.

Modules are contained in a file, but a file can define several modules 
(however, it is better to keep them in separate files).

Each module can return a deferred. In that case, the module is marked as loaded
only when the deferred is resolved, and its value is equal to the resolved value.
The module can be rejected (unloaded). This will be logged in the console as info.

* ``Missing dependencies``:
  These modules do not appear in the page. It is possible that the JavaScript 
  file is not in the page or that the module name is wrong
* ``Failed modules``:
  A javascript error is detected
* ``Rejected modules``:
  The module returns a rejected deferred. It (and its dependent modules) is not 
  loaded.
* ``Rejected linked modules``:
  Modules who depend on a rejected module
* ``Non loaded modules``:
  Modules who depend on a missing or a failed module


Web client structure
--------------------

The web client files have been refactored into smaller and simpler files.
Here is a description of the current file structure:

* the ``framework/`` folder contains all basic low level modules.  The
  modules here are supposed to be generic.  Some of them are:

  * ``web.ajax`` implements rpc calls
  * ``web.core`` is a generic modules.  It exports various useful
    objects and functions, such as ``qweb``, ``_t`` or the main bus.
  * ``web.Widget`` contains the widget class
  * ``web.Model`` is an abstraction over ``web.ajax`` to make
    calls to the server model methods
  * ``web.session`` is the former ``flectra.session``
  * ``web.utils`` for useful code snippets
  * ``web.time`` for every time-related generic functions
* the ``views/`` folder contains all view definitions
* ``widgets/`` is for standalone widgets

The ``js/`` folder also contains some important files:

* ``action_manager.js`` is the ActionManager class
* ``boot.js`` is the file actually implementing the module system
* ``menu.js`` is the definition of the top menu
* ``web_client.js`` is for the root widget WebClient
* ``view_manager.js`` contains the ViewManager

The two other files are ``tour.js`` for the tours and ``compatibility.js``.
The latter file is a compatibility layer bridging the old system to the
new module system.  This is where every module names are exported to the
global variable ``flectra``.  In theory, our addons should work without
ever using the variable ``flectra``, and the compatibility module can be
disabled safely.

Javascript conventions
----------------------

Here are some basic conventions for the javascript code:

* declare all your dependencies at the top of the module.  Also, they
  should be sorted alphabetically by module name.  This makes it
  easier to understand your module.
* declare all exports at the end.
* add the ``use strict`` statement at the beginning of every module
* always name your module properly: ``addon_name.description``.
* use capital letters for classes (for example, ``ActionManager`` is
  defined in the module ``web.ActionManager``), and lowercase for
  everything else (for example, ``ajax`` is defined in ``web.ajax``).
* declare one module per file




=============================
Testing in Flectra Web Client
=============================

Javascript Unit Testing
-----------------------

Flectra Web includes means to unit-test both the core code of
Flectra Web and your own javascript modules. On the javascript side,
unit-testing is based on QUnit_ with a number of helpers and
extensions for better integration with Flectra.

To see what the runner looks like, find (or start) an Flectra server
with the web client enabled, and navigate to ``/web/tests``
This will show the runner selector, which lists all modules with javascript
unit tests, and allows starting any of them (or all javascript tests in all
modules at once).

.. image:: ./images/runner.png
    :align: center

Clicking any runner button will launch the corresponding tests in the
bundled QUnit_ runner:

.. image:: ./images/tests.png
    :align: center

Writing a test case
-------------------

The first step is to list the test file(s). This is done through the
``test`` key of the Flectra manifest, by adding javascript files to it:

.. code-block:: python

    {
        'name': "Demonstration of web/javascript tests",
        'category': 'Hidden',
        'depends': ['web'],
        'test': ['static/tests/demo.js'],
    }

and to create the corresponding test file(s)

.. note::

    Test files which do not exist will be ignored, if all test files
    of a module are ignored (can not be found), the test runner will
    consider that the module has no javascript tests.

After that, refreshing the runner selector will display the new module
and allow running all of its (0 so far) tests:

.. image:: ./images/runner2.png
    :align: center

The next step is to create a test case::

    flectra.testing.section('basic section', function (test) {
        test('my first test', function () {
            ok(false, "this test has run");
        });
    });

All testing helpers and structures live in the ``flectra.testing``
module. Flectra tests live in a :func:`~flectra.testing.section`,
which is itself part of a module. The first argument to a section is
the name of the section, the second one is the section body.

:func:`test <flectra.testing.case>`, provided by the
:func:`~flectra.testing.section` to the callback, is used to
register a given test case which will be run whenever the test runner
actually does its job. Flectra Web test case use standard `QUnit
assertions`_ within them.

Launching the test runner at this point will run the test and display
the corresponding assertion message, with red colors indicating the
test failed:

.. image:: ./images/tests2.png
    :align: center

Fixing the test (by replacing ``false`` to ``true`` in the assertion)
will make it pass:

.. image:: ./images/tests3.png
    :align: center

Assertions
----------

As noted above, Flectra Web's tests use `qunit assertions`_. They are
available globally (so they can just be called without references to
anything). The following list is available:

.. function:: ok(state[, message])

    checks that ``state`` is truthy (in the javascript sense)

.. function:: strictEqual(actual, expected[, message])

    checks that the actual (produced by a method being tested) and
    expected values are identical (roughly equivalent to ``ok(actual
    === expected, message)``)

.. function:: notStrictEqual(actual, expected[, message])

    checks that the actual and expected values are *not* identical
    (roughly equivalent to ``ok(actual !== expected, message)``)

.. function:: deepEqual(actual, expected[, message])

    deep comparison between actual and expected: recurse into
    containers (objects and arrays) to ensure that they have the same
    keys/number of elements, and the values match.

.. function:: notDeepEqual(actual, expected[, message])

    inverse operation to :func:`deepEqual`

.. function:: throws(block[, expected][, message])

    checks that, when called, the ``block`` throws an
    error. Optionally validates that error against ``expected``.

    :param Function block:
    :param expected: if a regexp, checks that the thrown error's
                     message matches the regular expression. If an
                     error type, checks that the thrown error is of
                     that type.
    :type expected: Error | RegExp

.. function:: equal(actual, expected[, message])

    checks that ``actual`` and ``expected`` are loosely equal, using
    the ``==`` operator and its coercion rules.

.. function:: notEqual(actual, expected[, message])

    inverse operation to :func:`equal`

Getting an Flectra instance
---------------------------

The Flectra instance is the base through which most Flectra Web
modules behaviors (functions, objects, …) are accessed. As a result,
the test framework automatically builds one, and loads the module
being tested and all of its dependencies inside it. This new instance
is provided as the first positional parameter to your test
cases. Let's observe by adding javascript code (not test code) to the
test module:

.. code-block:: python

    {
        'name': "Demonstration of web/javascript tests",
        'category': 'Hidden',
        'depends': ['web'],
        'js': ['static/src/js/demo.js'],
        'test': ['static/tests/demo.js'],
    }

::

    // src/js/demo.js
    flectra.web_tests_demo = function (instance) {
        instance.web_tests_demo = {
            value_true: true,
            SomeType: instance.web.Class.extend({
                init: function (value) {
                    this.value = value;
                }
            })
        };
    };

and then adding a new test case, which simply checks that the
``instance`` contains all the expected stuff we created in the
module::

    // test/demo.js
    test('module content', function (instance) {
        ok(instance.web_tests_demo.value_true, "should have a true value");
        var type_instance = new instance.web_tests_demo.SomeType(42);
        strictEqual(type_instance.value, 42, "should have provided value");
    });

DOM Scratchpad
--------------

As in the wider client, arbitrarily accessing document content is
strongly discouraged during tests. But DOM access is still needed to
e.g. fully initialize :class:`widgets <~flectra.Widget>` before
testing them.

Thus, a test case gets a DOM scratchpad as its second positional
parameter, in a jQuery instance. That scratchpad is fully cleaned up
before each test, and as long as it doesn't do anything outside the
scratchpad your code can do whatever it wants::

    // test/demo.js
    test('DOM content', function (instance, $scratchpad) {
        $scratchpad.html('<div><span class="foo bar">ok</span></div>');
        ok($scratchpad.find('span').hasClass('foo'),
           "should have provided class");
    });
    test('clean scratchpad', function (instance, $scratchpad) {
        ok(!$scratchpad.children().length, "should have no content");
        ok(!$scratchpad.text(), "should have no text");
    });

.. note::

    The top-level element of the scratchpad is not cleaned up, test
    cases can add text or DOM children but shoud not alter
    ``$scratchpad`` itself.

Loading templates
-----------------

To avoid the corresponding processing costs, by default templates are
not loaded into QWeb. If you need to render e.g. widgets making use of
QWeb templates, you can request their loading through the
:attr:`~TestOptions.templates` option to the :func:`test case
function <flectra.testing.case>`.

This will automatically load all relevant templates in the instance's
qweb before running the test case:

.. code-block:: python

    {
        'name': "Demonstration of web/javascript tests",
        'category': 'Hidden',
        'depends': ['web'],
        'js': ['static/src/js/demo.js'],
        'test': ['static/tests/demo.js'],
        'qweb': ['static/src/xml/demo.xml'],
    }

.. code-block:: xml

    <!-- src/xml/demo.xml -->
    <templates id="template" xml:space="preserve">
        <t t-name="DemoTemplate">
            <t t-foreach="5" t-as="value">
                <p><t t-esc="value"/></p>
            </t>
        </t>
    </templates>

::

    // test/demo.js
    test('templates', {templates: true}, function (instance) {
        var s = instance.web.qweb.render('DemoTemplate');
        var texts = $(s).find('p').map(function () {
            return $(this).text();
        }).get();

        deepEqual(texts, ['0', '1', '2', '3', '4']);
    });

Asynchronous cases
------------------

The test case examples so far are all synchronous, they execute from
the first to the last line and once the last line has executed the
test is done. But the web client is full of :ref:`asynchronous code
<reference/async>`, and thus test cases need to be async-aware.

This is done by returning a :class:`deferred <Deferred>` from the
case callback::

    // test/demo.js
    test('asynchronous', {
        asserts: 1
    }, function () {
        var d = $.Deferred();
        setTimeout(function () {
            ok(true);
            d.resolve();
        }, 100);
        return d;
    });

This example also uses the :class:`options parameter <TestOptions>`
to specify the number of assertions the case should expect, if less or
more assertions are specified the case will count as failed.

Asynchronous test cases *must* specify the number of assertions they
will run. This allows more easily catching situations where e.g. the
test architecture was not warned about asynchronous operations.

.. note::

    Asynchronous test cases also have a 2 seconds timeout: if the test
    does not finish within 2 seconds, it will be considered
    failed. This pretty much always means the test will not
    resolve. This timeout *only* applies to the test itself, not to
    the setup and teardown processes.

.. note::

    If the returned deferred is rejected, the test will be failed
    unless :attr:`~TestOptions.fail_on_rejection` is set to
    ``false``.

RPC
---

An important subset of asynchronous test cases is test cases which
need to perform (and chain, to an extent) RPC calls.

.. note::

    Because they are a subset of asynchronous cases, RPC cases must
    also provide a valid :attr:`assertions count
    <TestOptions.asserts>`.

To enable mock RPC, set the :attr:`rpc option <TestOptions.rpc>` to
``mock``. This will add a third parameter to the test case callback:

.. function:: mock(rpc_spec, handler)

    Can be used in two different ways depending on the shape of the
    first parameter:

    * If it matches the pattern ``model:method`` (if it contains a
      colon, essentially) the call will set up the mocking of an RPC
      call straight to the Flectra server (through XMLRPC) as
      performed via e.g. :func:`flectra.web.Model.call`.

      In that case, ``handler`` should be a function taking two
      arguments ``args`` and ``kwargs``, matching the corresponding
      arguments on the server side and should simply return the value
      as if it were returned by the Python XMLRPC handler::

          test('XML-RPC', {rpc: 'mock', asserts: 3}, function (instance, $s, mock) {
              // set up mocking
              mock('people.famous:name_search', function (args, kwargs) {
                  strictEqual(kwargs.name, 'bob');
                  return [
                      [1, "Microsoft Bob"],
                      [2, "Bob the Builder"],
                      [3, "Silent Bob"]
                  ];
              });

              // actual test code
              return new instance.web.Model('people.famous')
                  .call('name_search', {name: 'bob'}).then(function (result) {
                      strictEqual(result.length, 3, "shoud return 3 people");
                      strictEqual(result[0][1], "Microsoft Bob",
                          "the most famous bob should be Microsoft Bob");
                  });
          });

    * Otherwise, if it matches an absolute path (e.g. ``/a/b/c``) it
      will mock a JSON-RPC call to a web client controller, such as
      ``/web/webclient/translations``. In that case, the handler takes
      a single ``params`` argument holding all of the parameters
      provided over JSON-RPC.

      As previously, the handler should simply return the result value
      as if returned by the original JSON-RPC handler::

          test('JSON-RPC', {rpc: 'mock', asserts: 3, templates: true}, function (instance, $s, mock) {
              var fetched_dbs = false, fetched_langs = false;
              mock('/web/database/get_list', function () {
                  fetched_dbs = true;
                  return ['foo', 'bar', 'baz'];
              });
              mock('/web/session/get_lang_list', function () {
                  fetched_langs = true;
                  return [['vo_IS', 'Hopelandic / Vonlenska']];
              });

              // widget needs that or it blows up
              instance.webclient = {toggle_bars: flectra.testing.noop};
              var dbm = new instance.web.DatabaseManager({});
              return dbm.appendTo($s).then(function () {
                  ok(fetched_dbs, "should have fetched databases");
                  ok(fetched_langs, "should have fetched languages");
                  deepEqual(dbm.db_list, ['foo', 'bar', 'baz']);
              });
          });

.. note::

    Mock handlers can contain assertions, these assertions should be
    part of the assertions count (and if multiple calls are made to a
    handler containing assertions, it multiplies the effective number
    of assertions).

Testing API
-----------

.. function:: flectra.testing.section(name[, options], body)

    A test section, serves as shared namespace for related tests (for
    constants or values to only set up once). The ``body`` function
    should contain the tests themselves.

    Note that the order in which tests are run is essentially
    undefined, do *not* rely on it.

    :param String name:
    :param TestOptions options:
    :param body:
    :type body: Function<:func:`~flectra.testing.case`, void>

.. function:: flectra.testing.case(name[, options], callback)

    Registers a test case callback in the test runner, the callback
    will only be run once the runner is started (or maybe not at all,
    if the test is filtered out).

    :param String name:
    :param TestOptions options:
    :param callback:
    :type callback: Function<instance, $, Function<String, Function, void>>

.. class:: TestOptions

    the various options which can be passed to
    :func:`~flectra.testing.section` or
    :func:`~flectra.testing.case`. Except for
    :attr:`~TestOptions.setup` and
    :attr:`~TestOptions.teardown`, an option on
    :func:`~flectra.testing.case` will overwrite the corresponding
    option on :func:`~flectra.testing.section` so
    e.g. :attr:`~TestOptions.rpc` can be set for a
    :func:`~flectra.testing.section` and then differently set for
    some :func:`~flectra.testing.case` of that
    :func:`~flectra.testing.section`

    .. attribute:: TestOptions.asserts

        An integer, the number of assertions which should run during a
        normal execution of the test. Mandatory for asynchronous tests.

    .. attribute:: TestOptions.setup

        Test case setup, run right before each test case. A section's
        :func:`~TestOptions.setup` is run before the case's own, if
        both are specified.

    .. attribute:: TestOptions.teardown

        Test case teardown, a case's :func:`~TestOptions.teardown`
        is run before the corresponding section if both are present.

    .. attribute:: TestOptions.fail_on_rejection

        If the test is asynchronous and its resulting promise is
        rejected, fail the test. Defaults to ``true``, set to
        ``false`` to not fail the test in case of rejection::

            // test/demo.js
            test('unfail rejection', {
                asserts: 1,
                fail_on_rejection: false
            }, function () {
                var d = $.Deferred();
                setTimeout(function () {
                    ok(true);
                    d.reject();
                }, 100);
                return d;
            });

    .. attribute:: TestOptions.rpc

        RPC method to use during tests, one of ``"mock"`` or
        ``"rpc"``. Any other value will disable RPC for the test (if
        they were enabled by the suite for instance).

    .. attribute:: TestOptions.templates

        Whether the current module (and its dependencies)'s templates
        should be loaded into QWeb before starting the test. A
        boolean, ``false`` by default.

The test runner can also use two global configuration values set
directly on the ``window`` object:

* ``oe_all_dependencies`` is an ``Array`` of all modules with a web
  component, ordered by dependency (for a module ``A`` with
  dependencies ``A'``, any module of ``A'`` must come before ``A`` in
  the array)

Running through Python
----------------------

The web client includes the means to run these tests on the
command-line (or in a CI system), but while actually running it is
pretty simple the setup of the pre-requisite parts has some
complexities.

#. Install PhantomJS_. It is a headless
   browser which allows automating running and testing web
   pages. QUnitSuite_ uses it to actually run the qunit_ test suite.

   The PhantomJS_ website provides pre-built binaries for some
   platforms, and your OS's package management probably provides it as
   well.

   If you're building PhantomJS_ from source, I recommend preparing
   for some knitting time as it's not exactly fast (it needs to
   compile both `Qt <http://qt-project.org/>`_ and `Webkit
   <http://www.webkit.org/>`_, both being pretty big projects).

   .. note::

       Because PhantomJS_ is webkit-based, it will not be able to test
       if Firefox, Opera or Internet Explorer can correctly run the
       test suite (and it is only an approximation for Safari and
       Chrome). It is therefore recommended to *also* run the test
       suites in actual browsers once in a while.

   .. note::

       The version of PhantomJS_ this was build through is 1.7,
       previous versions *should* work but are not actually supported
       (and tend to just segfault when something goes wrong in
       PhantomJS_ itself so they're a pain to debug).

#. Install a new database with all relevant modules (all modules with
   a web component at least), then restart the server

   .. note::

       For some tests, a source database needs to be duplicated. This
       operation requires that there be no connection to the database
       being duplicated, but Flectra doesn't currently break
       existing/outstanding connections, so restarting the server is
       the simplest way to ensure everything is in the right state.

#. Launch ``oe run-tests -d $DATABASE -mweb`` with the correct
   addons-path specified (and replacing ``$DATABASE`` by the source
   database you created above)

   .. note::

       If you leave out ``-mweb``, the runner will attempt to run all
       the tests in all the modules, which may or may not work.

If everything went correctly, you should now see a list of tests with
(hopefully) ``ok`` next to their names, closing with a report of the
number of tests run and the time it took:

.. literalinclude:: test-report.txt
    :language: text

Congratulation, you have just performed a successful "offline" run of
the OpenERP Web test suite.

.. note::

    Note that this runs all the Python tests for the ``web`` module,
    but all the web tests for all of Flectra. This can be surprising.

.. _qunit: http://qunitjs.com/

.. _qunit assertions: http://api.qunitjs.com/category/assert/

.. _QUnitSuite: http://pypi.python.org/pypi/QUnitSuite/

.. _PhantomJS: http://phantomjs.org/

.. [#eventsdelegation] not all DOM events are compatible with events delegation

.. [#terminal]
    with a small twist: :py:meth:`sqlalchemy.orm.query.Query.group_by` is not
    terminal, it returns a query which can still be altered.