1 Guidelines and Recommendations
2 ==============================
4 Web Module Recommendations
5 --------------------------
7 Identifiers (``id`` attribute) should be avoided
8 ''''''''''''''''''''''''''''''''''''''''''''''''
10 In generic applications and modules, ``@id`` limits the reusabily of
11 components and tends to make code more brittle.
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
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
25 Avoid predictable/common CSS class names
26 ''''''''''''''''''''''''''''''''''''''''
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
35 Global selectors should be avoided
36 ''''''''''''''''''''''''''''''''''
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.
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.$>`.
49 More generally, never assume your components own or controls anything
50 beyond its own personal DOM.
55 Deferreds, promises, futures, …
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.
61 OpenERP Web guidelines
62 ----------------------
64 * HTML templating/rendering should use :doc:`qweb` unless absolutely
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
72 * All css classes must be prefixed with *oe_* .
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