addons/web/doc/guidelines.rst

   1 Guidelines and Recommendations
   2 ==============================
   3
   4 Web Module Recommendations
   5 --------------------------
   6
   7 Identifiers (``id`` attribute) should be avoided
   8 ''''''''''''''''''''''''''''''''''''''''''''''''
   9
  10 In generic applications and modules, ``@id`` limits the reusabily of
  11 components and tends to make code more brittle.
  12
  13 Just about all the time, they can be replaced with nothing, with
  14 classes or with keeping a reference to a DOM node or a jQuery element
  15 around.
  16
  17 .. note::
  18
  19     If it is *absolutely necessary* to have an ``@id`` (because a
  20     third-party library requires one and can't take a DOM element), it
  21     should be generated with `_.uniqueId
  22     <http://underscorejs.org/#uniqueId>`_ or some other similar
  23     method.
  24
  25 Avoid predictable/common CSS class names
  26 ''''''''''''''''''''''''''''''''''''''''
  27
  28 Class names such as "content" or "navigation" might match the desired
  29 meaning/semantics, but it is likely an other developer will have the
  30 same need, creating a naming conflict and unintended behavior. Generic
  31 class names should be prefixed with e.g. the name of the component
  32 they belong to (creating "informal" namespaces, much as in C or
  33 Objective-C)
  34
  35 Global selectors should be avoided
  36 ''''''''''''''''''''''''''''''''''
  37
  38 Because a component may be used several times in a single page (an
  39 example in OpenERP is dashboards), queries should be restricted to a
  40 given component's scope. Unfiltered selections such as ``$(selector)``
  41 or ``document.querySelectorAll(selector)`` will generally lead to
  42 unintended or incorrect behavior.
  43
  44 OpenERP Web's :js:class:`~openerp.web.Widget` has an attribute
  45 providing its DOM root :js:attr:`Widget.$el <openerp.web.Widget.$el>`,
  46 and a shortcut to select nodes directly :js:attr:`Widget.$
  47 <openerp.web.Widget.$>`.
  48
  49 More generally, never assume your components own or controls anything
  50 beyond its own personal DOM.
  51
  52 Understand deferreds
  53 ''''''''''''''''''''
  54
  55 Deferreds, promises, futures, …
  56
  57 Known under many names, these objects are essential to and (in OpenERP
  58 Web) widely used for making :doc:`asynchronous javascript operations
  59 <async>` palatable and understandable.
  60
  61 OpenERP Web guidelines
  62 ----------------------
  63
  64 * HTML templating/rendering should use :doc:`qweb` unless absolutely
  65   trivial.
  66
  67 * All interactive components (components displaying information to the
  68   screen or intercepting DOM events) must inherit from
  69   :class:`~openerp.web.Widget` and correctly implement and use its API
  70   and lifecycle.
  71
  72 * All css classes must be prefixed with *oe_* .
  73
  74 * Asynchronous functions (functions which call :ref:`session.rpc
  75   <rpc_rpc>` directly or indirectly at the very least) *must* return
  76   deferreds, so that callers of overriders can correctly synchronize
  77   with them.