Apache mod_wsgi¶

NGinx mod_wsgi¶

uWSGI¶

Gunicorn¶

FastCGI, SCGI, or AJP¶

Apache mod_proxy¶

NGinx HttpProxy¶

Subclassing Widget¶

Widget() is subclassed in the standard manner (via the 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 = openerp.base.Widget.extend({
    // QWeb template to use when rendering the object
    template: "MyQWebTemplate",

    init: function(parent) {
        this._super(parent);
        // insert code to execute before rendering, for object
        // initialization
    },
    start: function() {
        this._super();
        // post-rendering initialization code, at this point
        // ``this.$element`` has been initialized
        this.$element.find(".my_button").click(/* an example of event binding * /);

        // if ``start`` is asynchronous, return a promise object so callers
        // know when the object is done initializing
        return 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 appendTo has been resolved if needed), the widget is ready to be used.

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

my_widget.stop();

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

Registering a view¶

This is the first task to perform when creating a view, and the simplest by far: simply call openerp.base.views.add(name, object_path) to register the object of path object_path as the view for the view name name.

The view name is the name you gave to your new view in the OpenERP server.

From that point onwards, OpenERP Web will be able to find your object and instantiate it.

Standard view behaviors¶

In the normal OpenERP Web flow, views have to implement a number of methods so view managers can correctly communicate with them:

start()

This method will always be called after creating the view (via its constructor), but not necessarily immediately.

It is called with no arguments and should handle the heavy setup work, including remote call (to load the view’s setup data from the server via e.g. fields_view_get, for instance).

start should return a promise object which must be resolved when the view’s setup is completed. This promise is used by view managers to know when they can start interacting with the view.

do_hide()

Called by the view manager when it wants to replace this view by an other one, but wants to keep this view around to re-activate it later.

Should put the view in some sort of hibernation mode, and must hide its DOM elements.

do_show()

Called when the view manager wants to re-display the view after having hidden it. The view should refresh its data display upon receiving this notification

do_search(domain: Array, context: Object, group_by: Array)

If the view is searchable, this method is called to notify it of a search against it.

It should use the provided query data to perform a search and refresh its internal content (and display).

All views are searchable by default, but they can be made non-searchable by setting the property searchable to false.

This can be done either on the view class itself (at the same level as defining e.g. the start method) or at the instance level (in the class’s init), though you should generally set it on the class.

QWeb¶

QWeb automatically marks all text nodes (any text which is not in an XML attribute and not part of an XML tag) as translatable, and handles the replacement for you. There is nothing special to do to mark template text as translatable

JavaScript¶

OpenERP Web provides two functions to translate human-readable strings in javascript code. These functions should be “imported” in your module by aliasing them to their bare name:

var _t = openerp.web._t,
   _tl = openerp.web._tl;

importing those functions under any other name is not guaranteed to work.

openerp.web._t(s)¶

Base translation function, eager, works much like gettext(3)

Return type:	String

openerp.web._lt(s)¶

Lazy equivalent to _t(), this function will postpone fetching the translation to its argument until the last possible moment.

To use in contexts evaluated before the translation database can be fetched, usually your module’s toplevel and the attributes of classes defined in it (class attributes, not instance attributes set in the constructor).

Return type:	LazyString

var translated_string = _.str.sprintf(
    _t("[%(first_record)d to %(last_record)d] of %(records_count)d"), {
        first_record: first + 1,
        last_record: last,
        records_count: total
    }));

Extracting strings¶

Once strings have been marked for translation, they need to be extracted into POT files, from which most translation tools can build a database.

This can be done via the provided gen_translations.sh.

It can be called either as gen_translations.sh -a or by providing two parameters, a path to the addons and the complete path in which to put the extracted POT file.

-a¶

Extracts translations from all standard OpenERP Web addons (addons bundled with OpenERP Web itself) and puts the extracted templates into the right directory for Rosetta to handle them

Events¶

on_loaded

Fires when the search view receives its view data (the result of fields_view_get). Hooking up before the event allows for altering view data before it can be used.

By the time on_loaded is done, the search view is guaranteed to be fully set up and ready to use.

on_search

Event triggered after a user asked for a search. The search view fires this event after collecting all input data (contexts, domains and group_by contexts). Note that the search view does not merge those (or otherwise evaluate them), they are returned as provided by the various inputs within the view.

on_clear

Triggered after a user asked for a form clearing.

Input management¶

An important concept in the search view is that of input. It is both an informal protocol and an abstract type that can be inherited from.

Inputs are widgets which can contain user data (a char widget for instance, or a selection box). They are capable of action and of reaction:

registration

This is an input action. Inputs have to register themselves to the main view (which they receive as a constructor argument). This is performed by pushing themselves on the openerp.base.SearchView.inputs array.

get_context

An input reaction. When it needs to collect contexts, the view calls get_context() on all its inputs.

Inputs can react in the following manners:

• Return a context (an object), this is the “normal” response if the input holds a value.

• Return a value that evaluates as false (generally null). This value indicates the input does not contain any value and will not affect the results of the search.

• Raise openerp.base.search.Invalid() to indicate that it holds a value but this value can not be used in the search (because it is incorrectly formatted or nonsensical). Raising Invalid() is guaranteed to cancel the search process.

  Invalid() takes three mandatory arguments: an identifier (a name for instance), the invalid value, and a validation message indicating the issue.

get_domain

The second input reaction, the possible behaviors of inputs are the same as for get_context.

The openerp.base.search.Input() type implements registration on its own, but its implementations of get_context and get_domain simply raise errors and must be overridden.

One last action is for filters, as an activation order has to be kept on them for some controls (to establish the correct grouping sequence, for instance).

To that end, filters can call openerp.base.Search.do_toggle_filter(), providing themselves as first argument.

Filters calling do_toggle_filter() also need to implement a method called is_enabled(), which the search view will use to know the current status of the filter.

The search view automatically triggers a search after calls to do_toggle_filter().

Life cycle¶

The search view has a pretty simple and linear life cycle, in three main steps:

init()

Nothing interesting happens here

start()

Called by the main view’s creator, this is the main initialization step for the list view.

It begins with a remote call to fetch the view’s descriptors (fields_view_get).

Once the remote call is complete, the on_loaded even happens, holding three main operations:

make_widgets()

Builds and returns the top-level widgets of the search view. Because it returns an array of widget lines (a 2-dimensional matrix of widgets) it should be called recursively by container widgets (openerp.base.search.Group() for instance).

render()

Called by the search view on all top-level widgets. Container widgets should recursively call this method on their own children widgets.

Widgets are provided with a mapping of {name: value} holding default values for the search view. They can freely pick their initial values from there, but must pass the mapping to their children widgets if they have any.

start()

The last operation of the search view startup is to initialize all its widgets in order. This is again done recursively (the search view starts its children, which have to start their own children).

stop()

Used before discarding a search view, allows the search view to disable its events and pass the message to its own widgets, gracefully shutting down the whole view.

Widgets¶

In a search view, the widget is simply a unit of display.

All widgets must be able to react to three events, which will be called in this order:

render()

Called with a map of default values. The widget must return a String, which is its HTML representation. That string can be empty (if the widget should not be represented).

Widgets are responsible for asking their children for rendering, and for passing along the default values.

start()

Called without arguments. At this point, the widget has been fully rendered and can set its events up, if any.

The widget is responsible for starting its children, if it has any.

stop()

Gives the widget the opportunity to unbind its events, remove itself from the DOM and perform any other cleanup task it may have.

Even if the widget does not do anything itself, it is responsible for shutting down its children.

An abstract type is available and can be inherited from, to simplify the implementation of those tasks:

Inputs¶

The search namespace (openerp.base.search) provides two more abstract types, used to implement input widgets:

• openerp.base.search.Input() is the most basic input type, it only implements input registration.

  If inherited from, descendant classes should not call its implementations of get_context() and get_domain().

• openerp.base.search.Field() is used to implement more “field” widgets (which allow the user to input potentially complex values).

  It provides various services for its subclasses:

  • Sets up the field attributes, using attributes from the field and the view node.

  • It fills the widget with Filter() if the field has any child filter.

  • It automatically generates an identifier based on the field type and the field name, using make_id().

  • It sets up a basic (overridable) template attribute, combined with the previous tasks, this makes subclasses of Field() render themselves “for free”.

  • It provides basic implementations of get_context and get_domain, both hinging on the subclasses implementing get_value() (which should return a correct, converted Javascript value):

    get_context()

    Checks if the field has a non-null and non-empty (String) value, and that the field has a context attr.

    If both conditions are fullfilled, returns the context.

    get_domain()

    Only requires that the field has a non-null and non-empty value.

    If the field has a filter_domain, returns it immediately. Otherwise, builds a context using the field’s name, the field operator and the field value, and returns it.

Creation and Initialization¶

As with most OpenERP Web views, the list view’s init() takes quite a number of arguments.

While most of them are the standard view constructor arguments (view_manager, session, element_id, dataset and an optional view_id), the list view adds a number of options for basic customization (without having to override methods or templates):

selectable (default: true)

Indicates that the list view should allow records to be selected individually. Displays selection check boxes to the left of all record rows, and allows for the triggering of the selection event.

deletable (default: true)

Indicates that the list view should allow records to be removed individually. Displays a deletion button to the right of all record rows, and allows for the triggering of the deletion event.

header (default: true)

Indicates that list columns should bear a header sporting their name (for non-action columns).

addable (default: "New")

Indicates that a record addition/creation button should be displayed in the list’s header, along with its label. Also allows for the triggering of the record addition event.

sortable (default: true)

Indicates that the list view can be sorted per-column (by clicking on its column headers).

reorderable (default: true)

Indicates that the list view records can be reordered (and re-sequenced) by drag and drop.

Events¶

Javascript coding¶

These are a number of guidelines for javascript code. More than coding conventions, these are warnings against potentially harmful or sub-par constructs.

Ideally, you should be able to configure your editor or IDE to warn you against these kinds of issues.

for (var i = 0; i < some_array.length; ++i) {
    // code here
}

foo = {
    'a': 1,
    'b': 2,
}

for(var key in ob) {
    if (!ob.hasOwnProperty(key)) {
        // comes from ob's class
        continue;
    }
    // do stuff with key
}

for (var key in ob) {
    if (!ob.hasOwnProperty(key)) { continue; }
    var value = ob[key];
    // Do stuff with key and value
}

_.each(ob, function (value, key) {
    // do stuff with key and value
});

Guides and main documentation¶

The meat and most important part of all documentation. Should be written in plain English, using reStructuredText and taking advantage of Sphinx’s extensions, especially cross-references.

Python API Documentation¶

All public objects in Python code should have a docstring written in RST, using Sphinx’s Python domain [3]:

• Functions and methods documentation should be in their own docstring, using Sphinx’s info fields

  For parameters types, built-in and stdlib types should be using the combined syntax:

  :param dict foo: what the purpose of foo is
  

  unless a more extensive explanation needs to be given (e.g. the specification that the input should be a list of 3-tuple needs to use :type: even though all types involved are built-ins). Any other type should be specified in full using the :type: field

  :param foo: what the purpose of foo is
  :type foo: some.addon.Class
  

  Mentions of other methods (including within the same class), modules or types in descriptions (of anything, including parameters) should be cross-referenced.

• Classes should likewise be documented using their own docstring, and should include the documentation of their construction (__init__ and __new__), using the info fields as well.

• Attributes (class and instance) should be documented in their class’s docstring via the .. attribute:: directive, following the class’s own documentation.

• The relation between modules and module-level attributes is similar: modules should be documented in their own docstring, public module attributes should be documented in the module’s docstring using the .. data:: directive.

Javascript API documentation¶

Javascript API documentation uses JsDoc, a javascript documentation toolkit with a syntax similar to (and inspired by) JavaDoc’s.

Due to limitations of JsDoc, the coding patterns in OpenERP Web and the Sphinx integration, there are a few peculiarities to be aware of when writing javascript API documentation:

• Namespaces and classes must be explicitly marked up even if they are not documented, or JsDoc will not understand what they are and will not generate documentation for their content.

  As a result, the bare minimum for a namespace is:

  /** @namespace */
  foo.bar.baz = {};
  

  while for a class it is:

  /** @class */
  foo.bar.baz.Qux = [...]
  

• Because the OpenERP Web project uses John Resig’s Class implementation instead of direct prototypal inheritance [4], JsDoc fails to infer class scopes (and constructors or super classes, for that matter) and has to be told explicitly.

  See Documenting a Class for the complete rundown.

• Much like the JavaDoc, JsDoc does not include a full markup language. Instead, comments are simply marked up in HTML.

  This has a number of inconvenients:

  • Complex documentation comments become nigh-unreadable to read in text editors (as opposed to IDEs, which may handle rendering documentation comments on the fly)
  • Though cross-references are supported by JsDoc (via @link and @see), they only work within the JsDoc
  • More general impossibility to integrate correctly with Sphinx, and e.g. reference JavaScript objects from a tutorial, or have all the documentation live at the same place.

  As a result, JsDoc comments should be marked up using RST, not HTML. They may use Sphinx’s cross-references as well.

/**
 * <Insert description here, not below>
 *
 * @class
 * @extends openerp.base.search.Field
 */
openerp.base.search.CharField = openerp.base.search.Field.extend(
    /** @lends openerp.base.search.CharField# */ {
        // methods here
});

openerp.base.search.Widget = openerp.base.Controller.extend(
    /** @lends openerp.base.search.Widget# */{
    /**
     * <Insert description here, not below>
     *
     * @constructs
     * @extends openerp.base.Controller
     *
     * @param view the ancestor view of this widget
     */
    init: function (view) {
        // construction of the instance
    },
    // bunch of other methods
});