diff --git a/addons/web/doc/async.rst b/addons/web/doc/async.rst index bd23d5a31d3..d597df0ddb0 100644 --- a/addons/web/doc/async.rst +++ b/addons/web/doc/async.rst @@ -1,6 +1,9 @@ Asynchronous Operations ======================= +This documentation is outdated as then() is now pipe. Please never copy api +from other libraries just link to it. + As a language (and runtime), javascript is fundamentally single-threaded. This means any blocking request or computation will blocks the whole page (and, in older browsers, the software itself @@ -26,8 +29,7 @@ Deferreds --------- Deferreds are a form of `promises`_. OpenERP Web currently uses -`jQuery's deferred`_, but any `CommonJS Promises/A`_ implementation -should work. +`jQuery's deferred`_. The core idea of deferreds is that potentially asynchronous methods will return a :js:class:`Deferred` object instead of an arbitrary @@ -44,9 +46,8 @@ directly to asynchronous methods is the ability to :ref:`compose them Using deferreds ~~~~~~~~~~~~~~~ -`CommonJS Promises/A`_ deferreds have only one method of importance: -:js:func:`Deferred.then`. This method is used to attach new callbacks -to the deferred object. +deferreds have only one method of importance: :js:func:`Deferred.then`. This +method is used to attach new callbacks to the deferred object. * the first parameter attaches a success callback, called when the deferred object is successfully resolved and provided with the @@ -248,103 +249,6 @@ promise-based APIs, in order to filter their resolution value counts for instance (to take advantage of :js:func:`when` 's special treatment of single-value promises). -jQuery.Deferred API -~~~~~~~~~~~~~~~~~~~ - -.. js:function:: when(deferreds…) - - :param deferreds: deferred objects to multiplex - :returns: a multiplexed deferred - :rtype: :js:class:`Deferred` - -.. js:class:: Deferred - - .. js:function:: Deferred.then(doneCallback[, failCallback]) - - Attaches new callbacks to the resolution or rejection of the - deferred object. Callbacks are executed in the order they are - attached to the deferred. - - To provide only a failure callback, pass ``null`` as the - ``doneCallback``, to provide only a success callback the - second argument can just be ignored (and not passed at all). - - :param doneCallback: function called when the deferred is resolved - :type doneCallback: Function - :param failCallback: function called when the deferred is rejected - :type failCallback: Function - :returns: the deferred object on which it was called - :rtype: :js:class:`Deferred` - - .. js:function:: Deferred.done(doneCallback) - - Attaches a new success callback to the deferred, shortcut for - ``deferred.then(doneCallback)``. - - This is a jQuery extension to `CommonJS Promises/A`_ providing - little value over calling :js:func:`~Deferred.then` directly, - it should be avoided. - - :param doneCallback: function called when the deferred is resolved - :type doneCallback: Function - :returns: the deferred object on which it was called - :rtype: :js:class:`Deferred` - - .. js:function:: Deferred.fail(failCallback) - - Attaches a new failure callback to the deferred, shortcut for - ``deferred.then(null, failCallback)``. - - A second jQuery extension to `Promises/A `_. Although it provides more value than - :js:func:`~Deferred.done`, it still is not much and should be - avoided as well. - - :param failCallback: function called when the deferred is rejected - :type failCallback: Function - :returns: the deferred object on which it was called - :rtype: :js:class:`Deferred` - - .. js:function:: Deferred.promise() - - Returns a read-only view of the deferred object, with all - mutators (resolve and reject) methods removed. - - .. js:function:: Deferred.resolve(value…) - - Called to resolve a deferred, any value provided will be - passed onto the success handlers of the deferred object. - - Resolving a deferred which has already been resolved or - rejected has no effect. - - .. js:function:: Deferred.reject(value…) - - Called to reject (fail) a deferred, any value provided will be - passed onto the failure handler of the deferred object. - - Rejecting a deferred which has already been resolved or - rejected has no effect. - - .. js:function:: Deferred.pipe(doneFilter[, failFilter]) - - Filters the result of a deferred, able to transform a success - into failure and a failure into success, or to delay - resolution further. - -.. [#] or simply calling :js:class:`Deferred` as a function, the - result is the same - -.. [#] or not-promises, the `CommonJS Promises/B`_ role of - :js:func:`when` is to be able to treat values and promises - uniformly: :js:func:`when` will pass promises through directly, - but non-promise values and objects will be transformed into a - resolved promise (resolving themselves with the value itself). - - jQuery's :js:func:`when` keeps this behavior making deferreds - easy to build from "static" values, or allowing defensive code - where expected promises are wrapped in :js:func:`when` just in - case. .. _promises: http://en.wikipedia.org/wiki/Promise_(programming) .. _jQuery's deferred: http://api.jquery.com/category/deferred-object/ diff --git a/addons/web/doc/changelog-7.0.rst b/addons/web/doc/changelog-7.0.rst index b801c11b945..96ed1ae18a2 100644 --- a/addons/web/doc/changelog-7.0.rst +++ b/addons/web/doc/changelog-7.0.rst @@ -15,7 +15,7 @@ DataSet -> Model ---------------- The 6.1 ``DataSet`` API has been deprecated in favor of the smaller -and more orthogonal :doc:`Model ` API, which more closely +and more orthogonal :doc:`Model ` API, which more closely matches the API in OpenERP Web's Python side and in OpenObject addons and removes most stateful behavior of DataSet. diff --git a/addons/web/doc/guides/client-action.rst b/addons/web/doc/dev_client_action.rst similarity index 98% rename from addons/web/doc/guides/client-action.rst rename to addons/web/doc/dev_client_action.rst index 30f0c7eeb27..af48fff08a7 100644 --- a/addons/web/doc/guides/client-action.rst +++ b/addons/web/doc/dev_client_action.rst @@ -1,7 +1,7 @@ .. highlight:: javascript -Creating a new client action -============================ +Client actions +============== Client actions are the client-side version of OpenERP's "Server Actions": instead of allowing for semi-arbitrary code to be executed diff --git a/addons/web/doc/qweb.rst b/addons/web/doc/dev_qweb.rst similarity index 99% rename from addons/web/doc/qweb.rst rename to addons/web/doc/dev_qweb.rst index 85719c6742d..7ad1e20d57a 100644 --- a/addons/web/doc/qweb.rst +++ b/addons/web/doc/dev_qweb.rst @@ -1,6 +1,6 @@ -QWeb Cookbook -============= +QWeb +==== QWeb is the template engine used by the OpenERP Web Client. It is a home made engine create by OpenERP developers. There are a few things to note about it: diff --git a/addons/web/doc/rpc.rst b/addons/web/doc/dev_rpc.rst similarity index 100% rename from addons/web/doc/rpc.rst rename to addons/web/doc/dev_rpc.rst diff --git a/addons/web/doc/widget.rst b/addons/web/doc/dev_widget.rst similarity index 99% rename from addons/web/doc/widget.rst rename to addons/web/doc/dev_widget.rst index ddfe525227d..7466ebaf3e8 100644 --- a/addons/web/doc/widget.rst +++ b/addons/web/doc/dev_widget.rst @@ -1,5 +1,5 @@ -User Interaction: Widget -======================== +Widget +====== This is the base class for all visual components. It corresponds to an MVC view. It provides a number of services to handle a section of a page: diff --git a/addons/web/doc/index.rst b/addons/web/doc/index.rst index 99edd1156e0..b79762431fa 100644 --- a/addons/web/doc/index.rst +++ b/addons/web/doc/index.rst @@ -12,20 +12,19 @@ Contents: :maxdepth: 1 presentation + async + + dev_rpc + dev_widget + dev_qweb + dev_client_action + + internal_form + internal_list + internal_search changelog-7.0 - async - rpc - - widget - qweb - search-view - - list-view - form-notes - - guides/client-action Indices and tables ================== diff --git a/addons/web/doc/form-notes.rst b/addons/web/doc/internal_form.rst similarity index 100% rename from addons/web/doc/form-notes.rst rename to addons/web/doc/internal_form.rst diff --git a/addons/web/doc/list-view.rst b/addons/web/doc/internal_list.rst similarity index 99% rename from addons/web/doc/list-view.rst rename to addons/web/doc/internal_list.rst index b7cdc1cd039..c1ed4dcde89 100644 --- a/addons/web/doc/list-view.rst +++ b/addons/web/doc/internal_list.rst @@ -451,7 +451,7 @@ formview, delegating instead to its created. The result should be a valid form view, see :doc:`Form Notes - ` for various peculiarities of the form view + ` for various peculiarities of the form view format. :param editor: editor object asking for the view diff --git a/addons/web/doc/search-view.rst b/addons/web/doc/internal_search.rst similarity index 100% rename from addons/web/doc/search-view.rst rename to addons/web/doc/internal_search.rst diff --git a/addons/web/doc/presentation.rst b/addons/web/doc/presentation.rst index c249b540513..26328b44e48 100644 --- a/addons/web/doc/presentation.rst +++ b/addons/web/doc/presentation.rst @@ -7,17 +7,17 @@ Prerequisites Prerequisites to code addons for the OpenERP Web Client: -- Html -- Css -- Javascript +- HTML5 +- CSS +- Javascript (Ecmascript 5) - jQuery Once you know all this, that's only the beginning. Most usages of Javascript/jQuery are small hacks to make a web page nicer. The OpenERP Client Web is different: it's a web application, not a web site. It doesn't have multiple pages generated by a server side code. Only one unique empty page is loaded and all the html is generated by Javascript code, the page is never reloaded. If you never developed that kind of application you still have lot of good practices to learn. -Recommendations ---------------- +Generic Guidelines +------------------ -First, here are the 5 golden rules when you create web 2.0 applications: +First, here are some generic recommandations about web 2.0 applications: * **Do not use ids**. Html ids are evil, the key anti-feature that makes your components non-reusable. You want to identify a dom part? Save a jQuery object over that dom element. If you really need to use ids, use _.uniqueId(), but 99% of the time you don't need to, classes are sufficient. * **Do not use predictable css class names** like "content" or "navigation", ten other developers will have the same idea than you and there will be clashes. A simple way to avoid this is to use prefixes. For example, if you need a css class for the button named "new" that is contained in the form view which is itself contained in the OpenERP application, name it "oe-form-view-new-button". @@ -25,12 +25,18 @@ First, here are the 5 golden rules when you create web 2.0 applications: * As a general advice, **Never assume you own the page**. When you create a component, it is never unique and is always surrounded by a bunch of crazy html. You have to do with it. * **Learn how to use jQuery's deferreds** [1]_. That concept may seem over-complicated, but the experience tell us that it is nearly impossible to create big-size javascript applications without that. +OpenERP guidelines +------------------ More recommendations related to the specific case of the OpenERP Web Client: -* Your components should inherit from the *Widget* class. +* The code should conform to EcmasScript 5 without the "use strict" mode as we support IE9. + +* Your components should inherit from the *Widget* class. And use *Widget* 's methods (*appendTo*, *replace*,...) to insert your component and its content into the dom. + * Use QWeb templates for html rendering. -* Use *Widget* 's methods (*appendTo*, *replace*,...) to insert your component and its content into the dom. + * All css classes should have the prefix *oe-* . + * Functions that call rpc() should return a deferred, even if it calls it indirectly. So a function that calls a function that calls a function that calls rpc() should return a deferred too. .. [1] http://api.jquery.com/category/deferred-object/