doc/guides/sidebar-protocol.rst

   1 Adding a sidebar to a view
   2 ==========================
   3
   4 Initialization
   5 --------------
   6
   7 Each view has the responsibility to create its sidebar (or not) if and only if
   8 the ``sidebar`` flag is set in its options.
   9
  10 In that case, it should use the ``sidebar_id`` value (from its options) to
  11 initialize the sidebar at the right position in the DOM:
  12
  13 .. code-block:: javascript
  14
  15     if (this.options.sidebar && this.options.sidebar_id) {
  16         this.sidebar = new openerp.web.Sidebar(this, this.options.sidebar_id);
  17         this.sidebar.start();
  18     }
  19
  20 Because the sidebar is an old-style widget, it must be started after being
  21 initialized.
  22
  23 Sidebar communication protocol
  24 ------------------------------
  25
  26 In order to behave correctly, a sidebar needs informations from its parent
  27 view.
  28
  29 This information is extracted via a very basic protocol consisting of a
  30 property and two methods:
  31
  32 .. js:attribute:: dataset
  33
  34     the view's dataset, used to fetch the currently active model and provide it
  35     to remote action handlers as part of the basic context
  36
  37 .. js:function:: get_selected_ids()
  38
  39     Used to query the parent view for the set of currently available record
  40     identifiers. Used to setup the basic context's ``active_id`` and
  41     ``active_ids`` keys.
  42
  43     .. warning::
  44
  45         :js:func:`get_selected_ids` must return at least one id
  46
  47     :returns: an array of at least one id
  48     :rtype: Array<Number>
  49
  50 .. js:function:: sidebar_context()
  51
  52     Queries the view for additional context data to provide to the sidebar.
  53
  54     :js:class:`~openerp.base.View` provides a default NOOP implementation,
  55     which simply resolves to an empty object.
  56
  57     :returns: a promise yielding an object on success, this object is mergeed
  58               into the sidebar's own context
  59     :rtype: $.Deferred<Object>
  60
  61 Programmatic folding and unfolding
  62 ----------------------------------
  63
  64 The sidebar object starts folded. It provides three methods to handle its
  65 folding status:
  66
  67 .. js:function:: do_toggle
  68
  69     Toggles the status of the sidebar
  70
  71 .. js:function:: do_fold
  72
  73     Forces the sidebar closed if it's currently open
  74
  75 .. js:function:: do_unfold
  76
  77     Forces the sidebar open if it's currently closed
  78