DOM Root

Using a widget

• creation and initialization of the widget instance
  

  openerp.Widget.init(parent)

  initialization method of widgets, synchronous, can be overridden to take more parameters from the widget's creator/parent
  

  Arguments

  • parent (Widget()) -- the new widget's parent, used to handle automatic destruction and event propagation. Can be null for the widget to have no parent.
• DOM injection and startup, this is done by calling one of:
  

  openerp.Widget.appendTo(element)

  Renders the widget and inserts it as the last child of the target, uses .appendTo()

  openerp.Widget.prependTo(element)

  Renders the widget and inserts it as the first child of the target, uses .prependTo()

  openerp.Widget.insertAfter(element)

  Renders the widget and inserts it as the preceding sibling of the target, uses .insertAfter()

  openerp.Widget.insertBefore(element)

  Renders the widget and inserts it as the following sibling of the target, uses .insertBefore()
  All of these methods accept whatever the corresponding jQuery method accepts (CSS selectors, DOM nodes or jQuery objects). They all return a deferred and are charged with three tasks:
  
  • rendering the widget's root element via renderElement()
  • inserting the widget's root element in the DOM using whichever jQuery method they match
  • starting the widget, and returning the result of starting it
    

    openerp.Widget.start()

    asynchronous startup of the widget once it's been injected in the DOM, generally used to perform asynchronous RPC calls to fetch whatever remote data is necessary for the widget to do its work.
    Must return a deferred to indicate when its work is done.
    A widget is not guaranteed to work correctly until its start() method has finished executing. The widget's parent/creator must wait for a widget to be fully started before interacting with it
    

    Returns

    deferred object
• widget destruction and cleanup
  

  openerp.Widget.destroy()

  destroys the widget's children, unbinds its events and removes its root from the DOM. Automatically called when the widget's parent is destroyed, must be called explicitly if the widget has no parents or if it is removed but its parent remains.
  A widget being destroyed is automatically unlinked from its parent.

this.alive(this.model.query().all()).then(function (records) {
    // would break if executed after the widget is destroyed, wrapping
    // rpc in alive() prevents execution
    _.each(records, function (record) {
        self.$el.append(self.format(record));
    });
});

Accessing DOM content

Because a widget is only responsible for the content below its DOM root, there

is a shortcut for selecting sub-sections of a widget's DOM:

this.$(selector);

this.$el.find(selector);

Resetting the DOM root

DOM events handling

events: {
    'click p.oe_some_class a': 'some_method',
    'change input': function (e) {
        e.stopPropagation();
    }
},

Subclassing Widget

var MyWidget = openerp.Widget.extend({
    // QWeb template to use when rendering the object
    template: "MyQWebTemplate",
    events: {
        // events binding example
        'click .my-button': 'handle_click',
    },

    init: function(parent) {
        this._super(parent);
        // insert code to execute before rendering, for object
        // initialization
    },
    start: function() {
        var sup = this._super();
        // post-rendering initialization code, at this point

        // allows multiplexing deferred objects
        return $.when(
            // propagate asynchronous signal from parent class
            sup,
            // return own's asynchronous signal
            this.rpc(/* … */))
    }
});

// Create the instance
var my_widget = new MyWidget(this);
// Render and insert into DOM
my_widget.appendTo(".some-div");

my_widget.destroy();

Development Guidelines

• Identifiers (id attribute) should be avoided. In generic applications and modules, id limits the re-usability of components and tends to make code more brittle. Most of the time, they can be replaced with nothing, classes or keeping a reference to a DOM node or jQuery element.
  If an id is absolutely necessary (because a third-party library requires one), the id should be partially generated using _.uniqueId() e.g.:
  

  this.id = _.uniqueId('my-widget-')
  

• 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 Odoo 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. Odoo Web's Widget() has an attribute providing its DOM root ($el), and a shortcut to select nodes directly ($()).
• More generally, never assume your components own or controls anything beyond its own personal $el
• 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 life cycle.

RPC

High-level API: calling into Odoo models

• The interface is asynchronous, so instead of returning results directly RPC method calls will return Deferred instances, which will themselves resolve to the result of the matching RPC call.
• Because ECMAScript 3/Javascript 1.5 doesnt feature any equivalent to __getattr__ or method_missing, there needs to be an explicit method to dispatch RPC methods.
• No notion of pooler, the model proxy is instantiated where needed, not fetched from an other (somewhat global) object:
  

  var Users = new openerp.Model('res.users');
  
  Users.call('change_password', ['oldpassword', 'newpassword'],
                    {context: some_context}).then(function (result) {
      // do something with change_password result
  });
  

Users.query(['name', 'login', 'user_email', 'signature'])
     .filter([['active', '=', true], ['company_id', '=', main_company]])
     .limit(15)
     .all().then(function (users) {
    // do work with users records
});

Aggregation (grouping)

some_query.group_by(['field1', 'field2']).then(function (groups) {
    // do things with the fetched groups
});

• A check on group_by's result and two completely separate code paths:
  

  var groups;
  if (groups = some_query.group_by(gby)) {
      groups.then(function (gs) {
          // groups
      });
  }
  // no groups
  

• Or a more coherent code path using when()'s ability to coerce values into deferreds:
  

  $.when(some_query.group_by(gby)).then(function (groups) {
      if (!groups) {
          // No grouping
      } else {
          // grouping, even if there are no groups (groups
          // itself could be an empty array)
      }
  });
  

Low-level API: RPC calls to Python side

openerp.session.rpc('/web/dataset/resequence', {
    model: some_model,
    ids: array_of_ids,
    offset: 42
}).then(function (result) {
    // resequence didn't error out
}, function () {
    // an error occured during during call
});

Web Client

Testing in Odoo Web Client

Javascript Unit Testing

Writing a test case

{
    'name': "Demonstration of web/javascript tests",
    'category': 'Hidden',
    'depends': ['web'],
    'test': ['static/test/demo.js'],
}

openerp.testing.section('basic section', function (test) {
    test('my first test', function () {
        ok(false, "this test has run");
    });
});

Assertions

Getting an Odoo instance

{
    'name': "Demonstration of web/javascript tests",
    'category': 'Hidden',
    'depends': ['web'],
    'js': ['static/src/js/demo.js'],
    'test': ['static/test/demo.js'],
}

// src/js/demo.js
openerp.web_tests_demo = function (instance) {
    instance.web_tests_demo = {
        value_true: true,
        SomeType: instance.web.Class.extend({
            init: function (value) {
                this.value = value;
            }
        })
    };
};

// test/demo.js
test('module content', function (instance) {
    ok(instance.web_tests_demo.value_true, "should have a true value");
    var type_instance = new instance.web_tests_demo.SomeType(42);
    strictEqual(type_instance.value, 42, "should have provided value");
});

DOM Scratchpad

// test/demo.js
test('DOM content', function (instance, $scratchpad) {
    $scratchpad.html('

ok
');
    ok($scratchpad.find('span').hasClass('foo'),
       "should have provided class");
});
test('clean scratchpad', function (instance, $scratchpad) {
    ok(!$scratchpad.children().length, "should have no content");
    ok(!$scratchpad.text(), "should have no text");
});

Loading templates

{
    'name': "Demonstration of web/javascript tests",
    'category': 'Hidden',
    'depends': ['web'],
    'js': ['static/src/js/demo.js'],
    'test': ['static/test/demo.js'],
    'qweb': ['static/src/xml/demo.xml'],
}

 id="template" xml:space="preserve">
     t-name="DemoTemplate">
         t-foreach="5" t-as="value">
             t-esc="value"/>
        
    

// test/demo.js
test('templates', {templates: true}, function (instance) {
    var s = instance.web.qweb.render('DemoTemplate');
    var texts = $(s).find('p').map(function () {
        return $(this).text();
    }).get();

    deepEqual(texts, ['0', '1', '2', '3', '4']);
});

Asynchronous cases

// test/demo.js
test('asynchronous', {
    asserts: 1
}, function () {
    var d = $.Deferred();
    setTimeout(function () {
        ok(true);
        d.resolve();
    }, 100);
    return d;
});

Testing API

// test/demo.js
test('unfail rejection', {
    asserts: 1,
    fail_on_rejection: false
}, function () {
    var d = $.Deferred();
    setTimeout(function () {
        ok(true);
        d.reject();
    }, 100);
    return d;
});

• oe_all_dependencies is an Array of all modules with a web component, ordered by dependency (for a module A with dependencies A', any module of A' must come before A in the array)

Running through Python

1. Install unittest2 in your Python environment. Both can trivially be installed via pip or easy_install.
2. Install PhantomJS. It is a headless browser which allows automating running and testing web pages. QUnitSuite uses it to actually run the qunit test suite.
   The PhantomJS website provides pre-built binaries for some platforms, and your OS's package management probably provides it as well.
   If you're building PhantomJS from source, I recommend preparing for some knitting time as it's not exactly fast (it needs to compile both Qt and Webkit, both being pretty big projects).
   
   Note

   Because PhantomJS is webkit-based, it will not be able to test if Firefox, Opera or Internet Explorer can correctly run the test suite (and it is only an approximation for Safari and Chrome). It is therefore recommended to also run the test suites in actual browsers once in a while.
   Note

   The version of PhantomJS this was build through is 1.7, previous versions should work but are not actually supported (and tend to just segfault when something goes wrong in PhantomJS itself so they're a pain to debug).
3. Install a new database with all relevant modules (all modules with a web component at least), then restart the server
   
   Note

   For some tests, a source database needs to be duplicated. This operation requires that there be no connection to the database being duplicated, but Odoo doesn't currently break existing/outstanding connections, so restarting the server is the simplest way to ensure everything is in the right state.
4. Launch oe run-tests -d $DATABASE -mweb with the correct addons-path specified (and replacing $DATABASE by the source database you created above)
   
   Note

   If you leave out -mweb, the runner will attempt to run all the tests in all the modules, which may or may not work.

test_empty_find (openerp.addons.web.tests.test_dataset.TestDataSetController) ... ok
test_ids_shortcut (openerp.addons.web.tests.test_dataset.TestDataSetController) ... ok
test_regular_find (openerp.addons.web.tests.test_dataset.TestDataSetController) ... ok
web.testing.stack: direct, value, success ... ok
web.testing.stack: direct, deferred, success ... ok
web.testing.stack: direct, value, error ... ok
web.testing.stack: direct, deferred, failure ... ok
web.testing.stack: successful setup ... ok
web.testing.stack: successful teardown ... ok
web.testing.stack: successful setup and teardown ... ok

[snip ~150 lines]

test_convert_complex_context (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok
test_convert_complex_domain (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok
test_convert_literal_context (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok
test_convert_literal_domain (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok
test_retrieve_nonliteral_context (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok
test_retrieve_nonliteral_domain (openerp.addons.web.tests.test_view.DomainsAndContextsTest) ... ok

----------------------------------------------------------------------
Ran 181 tests in 15.706s

OK

@http.route('/hello', type="http", auth="admin")
  def hello(self):
    return "<div>Hello unknown user!</div>"

 import openerp.addons.web.controllers.main as main

 class Home2(main.Home):
    @http.route('/', type="http", auth="db")
    def index(self):
    return "<div>This is my new home page.</div>"