--- /dev/null
+Building an OpenERP Web module
+==============================
+
+There is no significant distinction between an OpenERP Web module and
+an OpenERP module, the web part is mostly additional data and code
+inside a regular OpenERP module. This allows providing more seamless
+features by integrating your module deeper into the web client.
+
+A Basic Module
+--------------
+
+A very basic OpenERP module structure will be our starting point:
+
+.. code-block:: text
+
+ web_example
+ ├── __init__.py
+ └── __openerp__.py
+
+.. literalinclude:: module/__openerp__.py
+ :language: python
+
+This is a sufficient minimal declaration of a valid OpenERP module.
+
+Web Declaration
+---------------
+
+There is no such thing as a "web module" declaration. An OpenERP
+module is automatically recognized as "web-enabled" if it contains a
+``static`` directory at its root, so:
+
+.. code-block:: text
+
+ web_example
+ ├── __init__.py
+ ├── __openerp__.py
+ └── static
+
+is the extent of it. You should also change the dependency to list
+``web``:
+
+.. literalinclude:: module/__openerp__.py.1.diff
+ :language: diff
+
+.. note::
+
+ This does not matter in normal operation so you may not realize
+ it's wrong (the web module does the loading of everything else, so
+ it can only be loaded), but when e.g. testing the loading process
+ is slightly different than normal, and incorrect dependency may
+ lead to broken code.
+
+This makes the "web" discovery system consider the module as having a
+"web part", and check if it has web controllers to mount or javascript
+files to load. The content of the ``static/`` folder is also
+automatically made available to web browser at the URL
+``$module-name/static/$file-path``. This is sufficient to provide
+pictures (of cats, usually) through your module. However there are
+still a few more steps to running javascript code.
+
+Getting Things Done
+-------------------
+
+The first one is to add javascript code. It's customary to put it in
+``static/src/js``, to have room for e.g. other file types, or
+third-party libraries.
+
+.. literalinclude:: module/static/src/js/first_module.js
+ :language: javascript
+
+The client won't load any file unless specified, thus the new file
+should be listed in the module's manifest file, under a new key ``js``
+(a list of file names, or glob patterns):
+
+.. literalinclude:: module/__openerp__.py.2.diff
+ :language: diff
+
+At this point, if the module is installed and the client reloaded the
+message should appear in your browser's development console.
+
+.. note::
+
+ Because the manifest file has been edited, you will have to
+ restart the OpenERP server itself for it to be taken in account.
+
+ You may also want to open your browser's console *before*
+ reloading, depending on the browser messages printed while the
+ console is closed may not work or may not appear after opening it.
+
+.. note::
+
+ If the message does not appear, try cleaning your browser's caches
+ and ensure the file is correctly loaded from the server logs or
+ the "resources" tab of your browser's developers tools.
+
+At this point the code runs, but it runs only once when the module is
+initialized, and it can't get access to the various APIs of the web
+client (such as making RPC requests to the server). This is done by
+providing a `javascript module`_:
+
+.. literalinclude:: module/static/src/js/first_module.js.1.diff
+ :language: diff
+
+If you reload the client, you'll see a message in the console exactly
+as previously. The differences, though invisible at this point, are:
+
+* All javascript files specified in the manifest (only this one so
+ far) have been fully loaded
+* An instance of the web client and a namespace inside that instance
+ (with the same name as the module) have been created and are
+ available for use
+
+The latter point is what the ``instance`` parameter to the function
+provides: an instance of the OpenERP Web client, with the contents of
+all the new module's dependencies loaded in and initialized. These are
+the entry points to the web client's APIs.
+
+To demonstrate, let's build a simple :doc:`client action
+<client_action>`: a stopwatch
+
+First, the action declaration:
+
+.. literalinclude:: module/__openerp__.py.3.diff
+ :language: diff
+
+.. literalinclude:: module/web_example.xml
+ :language: xml
+
+then set up the :doc:`client action hook <client_action>` to register
+a function (for now):
+
+.. literalinclude:: module/static/src/js/first_module.js.2.diff
+ :language: diff
+
+Updating the module (in order to load the XML description) and
+re-starting the server should display a new menu *Example Client
+Action* at the top-level. Opening said menu will make the message
+appear, as usual, in the browser's console.
+
+Paint it black
+--------------
+
+The next step is to take control of the page itself, rather than just
+print little messages in the console. This we can do by replacing our
+client action function by a :doc:`widget`. Our widget will simply use
+its :js:func:`~openerp.web.Widget.start` to add some content to its
+DOM:
+
+.. literalinclude:: module/static/src/js/first_module.js.3.diff
+ :language: diff
+
+after reloading the client (to update the javascript file), instead of
+printing to the console the menu item clears the whole screen and
+displays the specified message in the page.
+
+Since we've added a class on the widget's :ref:`DOM root
+<widget-dom_root>` we can now see how to add a stylesheet to a module:
+first create the stylesheet file:
+
+.. literalinclude:: module/static/src/css/web_example.css
+ :language: css
+
+then add a reference to the stylesheet in the module's manifest (which
+will require restarting the OpenERP Server to see the changes, as
+usual):
+
+.. literalinclude:: module/__openerp__.py.4.diff
+ :language: diff
+
+the text displayed by the menu item should now be huge, and
+white-on-black (instead of small and black-on-white). From there on,
+the world's your canvas.
+
+.. note::
+
+ Prefixing CSS rules with both ``.openerp`` (to ensure the rule
+ will apply only within the confines of the OpenERP Web client) and
+ a class at the root of your own hierarchy of widgets is strongly
+ recommended to avoid "leaking" styles in case the code is running
+ embedded in an other web page, and does not have the whole screen
+ to itself.
+
+So far we haven't built much (any, really) DOM content. It could all
+be done in :js:func:`~openerp.web.Widget.start` but that gets unwieldy
+and hard to maintain fast. It is also very difficult to extend by
+third parties (trying to add or change things in your widgets) unless
+broken up into multiple methods which each perform a little bit of the
+rendering.
+
+The first way to handle this method is to delegate the content to
+plenty of sub-widgets, which can be individually overridden. An other
+method [#DOM-building]_ is to use `a template
+<http://en.wikipedia.org/wiki/Web_template>`_ to render a widget's
+DOM.
+
+OpenERP Web's template language is :doc:`qweb`. Although any
+templating engine can be used (e.g. `mustache
+<http://mustache.github.com/>`_ or `_.template
+<http://underscorejs.org/#template>`_) QWeb has important features
+which other template engines may not provide, and has special
+integration to OpenERP Web widgets.
+
+Adding a template file is similar to adding a style sheet:
+
+.. literalinclude:: module/static/src/xml/web_example.xml
+ :language: xml
+
+.. literalinclude:: module/__openerp__.py.5.diff
+ :language: diff
+
+The template can then easily be hooked in the widget:
+
+.. literalinclude:: module/static/src/js/first_module.js.4.diff
+ :language: diff
+
+And finally the CSS can be altered to style the new (and more complex)
+template-generated DOM, rather than the code-generated one:
+
+.. literalinclude:: module/static/src/css/web_example.css.1.diff
+ :language: diff
+
+.. note::
+
+ The last section of the CSS change is an example of "state
+ classes": a CSS class (or set of classes) on the root of the
+ widget, which is toggled when the state of the widget changes and
+ can perform drastic alterations in rendering (usually
+ showing/hiding various elements).
+
+ This pattern is both fairly simple (to read and understand) and
+ efficient (because most of the hard work is pushed to the
+ browser's CSS engine, which is usually highly optimized, and done
+ in a single repaint after toggling the class).
+
+The last step (until the next one) is to add some behavior and make
+our stopwatch watch. First hook some events on the buttons to toggle
+the widget's state:
+
+.. literalinclude:: module/static/src/js/first_module.js.5.diff
+ :language: diff
+
+This demonstrates the use of the "events hash" and event delegation to
+declaratively handle events on the widget's DOM. And already changes
+the button displayed in the UI. Then comes some actual logic:
+
+.. literalinclude:: module/static/src/js/first_module.js.6.diff
+ :language: diff
+
+* An initializer (the ``init`` method) is introduced to set-up a few
+ internal variables: ``_start`` will hold the start of the timer (as
+ a javascript Date object), and ``_watch`` will hold a ticker to
+ update the interface regularly and display the "current time".
+
+* ``update_counter`` is in charge of taking the time difference
+ between "now" and ``_start``, formatting as ``HH:MM:SS`` and
+ displaying the result on screen.
+
+* ``watch_start`` is augmented to initialize ``_start`` with its value
+ and set-up the update of the counter display every 33ms.
+
+* ``watch_stop`` disables the updater, does a final update of the
+ counter display and resets everything.
+
+* Finally, because javascript Interval and Timeout objects execute
+ "outside" the widget, they will keep going even after the widget has
+ been destroyed (especially an issue with intervals as they repeat
+ indefinitely). So ``_watch`` *must* be cleared when the widget is
+ destroyed (then the ``_super`` must be called as well in order to
+ perform the "normal" widget cleanup).
+
+Starting and stopping the watch now works, and correctly tracks time
+since having started the watch, neatly formatted.
+
+.. [#DOM-building] they are not alternative solutions: they work very
+ well together. Templates are used to build "just
+ DOM", sub-widgets are used to build DOM subsections
+ *and* delegate part of the behavior (e.g. events
+ handling).
+
+.. _javascript module:
+ http://addyosmani.com/resources/essentialjsdesignpatterns/book/#modulepatternjavascript
--- /dev/null
+--- web_example/static/src/js/first_module.js
++++ web_example/static/src/js/first_module.js
+@@ -1,19 +1,52 @@
+ // static/src/js/first_module.js
+ openerp.web_example = function (instance) {
+ instance.web.client_actions.add('example.action', 'instance.web_example.Action');
+ instance.web_example.Action = instance.web.Widget.extend({
+ template: 'web_example.action',
+ events: {
+ 'click .oe_web_example_start button': 'watch_start',
+ 'click .oe_web_example_stop button': 'watch_stop'
+ },
++ init: function () {
++ this._super.apply(this, arguments);
++ this._start = null;
++ this._watch = null;
++ },
++ update_counter: function () {
++ var h, m, s;
++ // Subtracting javascript dates returns the difference in milliseconds
++ var diff = new Date() - this._start;
++ s = diff / 1000;
++ m = Math.floor(s / 60);
++ s -= 60*m;
++ h = Math.floor(m / 60);
++ m -= 60*h;
++ this.$('.oe_web_example_timer').text(
++ _.str.sprintf("%02d:%02d:%02d", h, m, s));
++ },
+ watch_start: function () {
+ this.$el.addClass('oe_web_example_started')
+ .removeClass('oe_web_example_stopped');
++ this._start = new Date();
++ // Update the UI to the current time
++ this.update_counter();
++ // Update the counter at 30 FPS (33ms/frame)
++ this._watch = setInterval(
++ this.proxy('update_counter'),
++ 33);
+ },
+ watch_stop: function () {
++ clearInterval(this._watch);
++ this.update_counter();
++ this._start = this._watch = null;
+ this.$el.removeClass('oe_web_example_started')
+ .addClass('oe_web_example_stopped');
+ },
++ destroy: function () {
++ if (this._watch) {
++ clearInterval(this._watch);
++ }
++ this._super();
++ }
+ });
+ };
projects / odoo / odoo.git / commitdiff