doc/changelog-6.2.rst

   1 API changes from OpenERP Web 6.1 to 6.2
   2 =======================================
   3
   4 DataSet -> Model
   5 ----------------
   6
   7 The 6.1 ``DataSet`` API has been deprecated in favor of the smaller
   8 and more orthogonal :doc:`Model </rpc>` API, which more closely
   9 matches the API in OpenERP Web's Python side and in OpenObject addons
  10 and removes most stateful behavior of DataSet.
  11
  12 Migration guide
  13 ~~~~~~~~~~~~~~~
  14
  15 * Actual arbitrary RPC calls can just be remapped on a
  16   :js:class:`~openerp.web.Model` instance:
  17
  18   .. code-block:: javascript
  19
  20       dataset.call(method, args)
  21
  22   or
  23
  24   .. code-block:: javascript
  25
  26       dataset.call_and_eval(method, args)
  27
  28   can be replaced by calls to :js:func:`openerp.web.Model.call`:
  29
  30   .. code-block:: javascript
  31
  32       model.call(method, args)
  33
  34   If callbacks are passed directly to the older methods, they need to
  35   be added to the new one via ``.then()``.
  36
  37   .. note::
  38
  39       The ``context_index`` and ``domain_index`` features were not
  40       ported, context and domain now need to be passed in "in full",
  41       they won't be automatically filled with the user's current
  42       context.
  43
  44 * Shorcut methods (``name_get``, ``name_search``, ``unlink``,
  45   ``write``, ...) should be ported to
  46   :js:func:`openerp.web.Model.call`, using the server's original
  47   signature. On the other hand, the non-shortcut equivalents can now
  48   use keyword arguments (see :js:func:`~openerp.web.Model.call`'s
  49   signature for details)
  50
  51 * ``read_slice``, which allowed a single round-trip to perform a
  52   search and a read, should be reimplemented via
  53   :js:class:`~openerp.web.Query` objects (see:
  54   :js:func:`~openerp.web.Model.query`) for clearer and simpler
  55   code. ``read_index`` should be replaced by a
  56   :js:class:`~openerp.web.Query` as well, combining
  57   :js:func:`~openerp.web.Query.offset` and
  58   :js:func:`~openerp.web.Query.first`.
  59
  60 Rationale
  61 ~~~~~~~~~
  62
  63 Renaming
  64
  65     The name *DataSet* exists in the CS community consciousness, and
  66     (as its name implies) it's a set of data (often fetched from a
  67     database, maybe lazily). OpenERP Web's dataset behaves very
  68     differently as it does not store (much) data (only a bunch of ids
  69     and just enough state to break things). The name "Model" matches
  70     the one used on the Python side for the task of building an RPC
  71     proxy to OpenERP objects.
  72
  73 API simplification
  74
  75     ``DataSet`` has a number of methods which serve as little more
  76     than shortcuts, or are there due to domain and context evaluation
  77     issues in 6.1.
  78
  79     The shortcuts really add little value, and OpenERP Web 6.2 embeds
  80     a restricted Python evaluator (in javascript) meaning most of the
  81     context and domain parsing & evaluation can be moved to the
  82     javascript code and does not require cooperative RPC bridging.
  83
  84 DataGroup -> also Model
  85 -----------------------
  86
  87 Alongside the deprecation of ``DataSet`` for
  88 :js:class:`~openerp.web.Model`, OpenERP Web 6.2 also deprecates
  89 ``DataGroup`` and its subtypes in favor of a single method on
  90 :js:class:`~openerp.web.Query`:
  91 :js:func:`~openerp.web.Query.group_by`.
  92
  93 Migration guide
  94 ~~~~~~~~~~~~~~~
  95
  96 Rationale
  97 ~~~~~~~~~
  98
  99 While the ``DataGroup`` API worked (mostly), it is quite odd and
 100 alien-looking, a bit too Smalltalk-inspired (behaves like a
 101 self-contained flow-control structure for reasons which may or may not
 102 have been good).
 103
 104 Because it is heavily related to ``DataSet`` (as it *yields*
 105 ``DataSet`` objects), deprecating ``DataSet`` automatically deprecates
 106 ``DataGroup`` (if we want to stay consistent), which is a good time to
 107 make the API more imperative and look more like what most developers
 108 are used to.