← Back to branch summary

~tempo-openerp/+junk/loewert-report-name

« back to all changes in this revision

Viewing changes to addons/web/doc/guidelines.rst

  • Committer: jbe at tempo-consulting
  • Date: 2013-08-21 08:48:11 UTC
  • Revision ID: jbe@tempo-consulting.fr-20130821084811-913uo4l7b5ayxq8m
[NEW] Création de la branche trunk Loewert

Show diffs side-by-side

added added

removed removed

Lines of Context:
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.