Guidelines and Recommendations

Web Module Recommendations

Identifiers (id attribute) should be avoided

In generic applications and modules, @id limits the reusabily of components and tends to make code more brittle.

Just about all the time, they can be replaced with nothing, with classes or with keeping a reference to a DOM node or a jQuery element around.

Note

If it is absolutely necessary to have an @id (because a third-party library requires one and can’t take a DOM element), it should be generated with _.uniqueId or some other similar method.

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 OpenERP 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.

OpenERP Web’s Widget() has an attribute providing its DOM root Widget.$el, and a shortcut to select nodes directly Widget.$.

More generally, never assume your components own or controls anything beyond its own personal DOM.

Understand deferreds

Deferreds, promises, futures, …

Known under many names, these objects are essential to and (in OpenERP Web) widely used for making asynchronous javascript operations palatable and understandable.

OpenERP Web guidelines

  • 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 Widget and correctly implement and use its API and lifecycle.
  • All css classes must be prefixed with oe_ .
  • Asynchronous functions (functions which call session.rpc directly or indirectly at the very least) must return deferreds, so that callers of overriders can correctly synchronize with them.