doc/list-view.rst

   1 List View
   2 =========
   3
   4 Style Hooks
   5 -----------
   6
   7 The list view provides a few style hook classes for re-styling of list views in
   8 various situations:
   9
  10 ``.oe_list``
  11
  12     The root element of the list view, styling rules should be rooted
  13     on that class.
  14
  15 ``table.oe_list_content``
  16
  17     The root table for the listview, accessory components may be
  18     generated or added outside this section, this is the list view
  19     "proper".
  20
  21 ``.oe_list_buttons``
  22
  23     The action buttons array for the list view, with its sub-elements
  24
  25     ``.oe_list_add``
  26
  27         The default "Create"/"Add" button of the list view
  28
  29     ``.oe_alternative``
  30
  31         The "alternative choice" for the list view, by default text
  32         along the lines of "or import" with a link.
  33
  34 ``.oe_list_field_cell``
  35
  36     The cell (``td``) for a given field of the list view, cells which
  37     are *not* fields (e.g. name of a group, or number of items in a
  38     group) will not have this class. The field cell can be further
  39     specified:
  40
  41     ``.oe_number``
  42
  43         Numeric cell types (integer and float)
  44
  45     ``.oe_button``
  46
  47         Action button (``button`` tag in the view) inside the cell
  48
  49     ``.oe_readonly``
  50
  51         Readonly field cell
  52
  53     ``.oe_list_field_$type``
  54
  55         Additional class for the precise type of the cell, ``$type``
  56         is the field's @widget if there is one, otherwise it's the
  57         field's type.
  58
  59 ``.oe_list_record_selector``
  60
  61     Selector cells
  62
  63 Editable list view
  64 ++++++++++++++++++
  65
  66 The editable list view module adds a few supplementary style hook
  67 classes, for edition situations:
  68
  69 ``.oe_editing``
  70
  71     Added to both ``.oe_list`` and ``.oe_list_button`` (as the
  72     buttons may be outside of the list view) when a row of the list is
  73     currently being edited.
  74
  75 ``tr.oe_edition``
  76
  77     Class set on the row being edited itself. Note that the edition
  78     form is *not* contained within the row, this allows for styling or
  79     modifying the row while it's being edited separately. Mostly for
  80     fields which can not be edited (e.g. read-only fields).
  81
  82
  83 Editable list view
  84 ------------------
  85
  86 List view edition is an extension to the base listview providing the
  87 capability of inline record edition by delegating to an embedded form
  88 view.
  89
  90 Editability status
  91 ++++++++++++++++++
  92
  93 The editability status of a list view can be queried through the
  94 :js:func:`~openerp.web.ListView.editable` method, will return a falsy
  95 value if the listview is not currently editable.
  96
  97 The editability status is based on three flags:
  98
  99 ``tree/@editable``
 100
 101     If present, can be either ``"top"`` or ``"bottom"``. Either will
 102     make the list view editable, with new records being respectively
 103     created at the top or at the bottom of the view.
 104
 105 ``context.set_editable``
 106
 107     Boolean flag extracted from a search context (during the
 108     :js:func:`~openerp.web.ListView.do_search`` handler), ``true``
 109     will make the view editable (from the top), ``false`` or the
 110     absence of the flag is a noop.
 111
 112 ``defaults.editable``
 113
 114     Like ``tree/@editable``, one of absent (``null``)), ``"top"`` or
 115     ``"bottom"``, fallback for the list view if none of the previous
 116     two flags are set.
 117
 118 These three flags can only *make* a listview editable, they can *not*
 119 override a previously set flag. To do that, a listview user should
 120 instead cancel :ref:`the edit:before event <listview-edit-before>`.
 121
 122 The editable list view module adds a number of methods to the list
 123 view, on top of implementing the :js:class:`EditorDelegate` protocol:
 124
 125 Interaction Methods
 126 +++++++++++++++++++
 127
 128 .. js:function:: openerp.web.ListView.ensure_saved
 129
 130     Attempts to resolve the pending edition, if any, by saving the
 131     edited row's current state.
 132
 133     :returns: delegate resolving to all editions having been saved, or
 134               rejected if a pending edition could not be saved
 135               (e.g. validation failure)
 136
 137 .. js:function:: openerp.web.ListView.start_edition([record][, options])
 138
 139     Starts editing the provided record inline, through an overlay form
 140     view of editable fields in the record.
 141
 142     If no record is provided, creates a new one according to the
 143     editability configuration of the list view.
 144
 145     This method resolves any pending edition when invoked, before
 146     starting a new edition.
 147
 148     :param record: record to edit, or null to create a new record
 149     :type record: :js:class:`~openerp.web.list.Record`
 150     :param EditOptions options:
 151     :returns: delegate to the form used for the edition
 152
 153 .. js:function:: openerp.web.ListView.save_edition
 154
 155     Resolves the pending edition.
 156
 157     :returns: delegate to the save being completed, resolves to an
 158               object with two attributes ``created`` (flag indicating
 159               whether the saved record was just created or was
 160               updated) and ``record`` the reloaded record having been
 161               edited.
 162
 163 .. js:function:: openerp.web.ListView.cancel_edition([force=false])
 164
 165     Cancels pending edition, cleans up the list view in case of
 166     creation (removes the empty record being created).
 167
 168     :param Boolean force: doesn't check if the user has added any
 169                           data, discards the edition unconditionally
 170
 171 Utility Methods
 172 +++++++++++++++
 173
 174 .. js:function:: openerp.web.ListView.get_cells_for(row)
 175
 176     Extracts the cells from a listview row, and puts them in a
 177     {fieldname: cell} mapping for analysis and manipulation.
 178
 179     :param jQuery row:
 180     :rtype: Object
 181
 182 .. js:function:: openerp.web.ListView.with_event(event_name, event, action[, args][, trigger_params])
 183
 184     Executes ``action`` in the context of the view's editor,
 185     bracketing it with cancellable event signals.
 186
 187     :param String event_name: base name for the bracketing event, will
 188                               be postfixed by ``:before`` and
 189                               ``:after`` before being called
 190                               (respectively before and after
 191                               ``action`` is executed)
 192     :param Object event: object passed to the ``:before`` event
 193                          handlers.
 194     :param Function action: function called with the view's editor as
 195                             its ``this``. May return a deferred.
 196     :param Array args: arguments passed to ``action``
 197     :param Array trigger_params: arguments passed to the ``:after``
 198                                  event handler alongside the results
 199                                  of ``action``
 200
 201 Behavioral Customizations
 202 +++++++++++++++++++++++++
 203
 204 .. js:function:: openerp.web.ListView.handle_onwrite(record)
 205
 206     Implements the handling of the ``onwrite`` listview attribute:
 207     calls the RPC methods specified by ``@onwrite``, and if that
 208     method returns an array of ids loads or reloads the records
 209     corresponding to those ids.
 210
 211     :param record: record being written having triggered the
 212                    ``onwrite`` callback
 213     :type record: openerp.web.list.Record
 214     :returns: deferred to all reloadings being done
 215
 216 Events
 217 ++++++
 218
 219 For simpler interactions by/with external users of the listview, the
 220 view provides a number of dedicated events to its lifecycle.
 221
 222 .. note:: if an event is defined as *cancellable*, it means its first
 223           parameter is an object on which the ``cancel`` attribute can
 224           be set. If the ``cancel`` attribute is set, the view will
 225           abort its current behavior as soon as possible, and rollback
 226           any state modification.
 227
 228           Generally speaking, an event should only be cancelled (by
 229           setting the ``cancel`` flag to ``true``), uncancelling an
 230           event is undefined as event handlers are executed on a
 231           first-come-first-serve basis and later handlers may
 232           re-cancel an uncancelled event.
 233
 234 .. _listview-edit-before:
 235
 236 ``edit:before`` *cancellable*
 237
 238     Invoked before the list view starts editing a record.
 239
 240     Provided with an event object with a single property ``record``,
 241     holding the attributes of the record being edited (``record`` is
 242     empty *but not null* for a new record)
 243
 244 ``edit:after``
 245
 246     Invoked after the list view has gone into an edition state,
 247     provided with the attributes of the record being edited (see
 248     ``edit:before``) as first parameter and the form used for the
 249     edition as second parameter.
 250
 251 ``save:before`` *cancellable*
 252
 253     Invoked right before saving a pending edition, provided with an
 254     event object holding the listview's editor (``editor``) and the
 255     edition form (``form``)
 256
 257 ``save:after``
 258
 259     Invoked after a save has been completed
 260
 261 ``cancel:before`` *cancellable*
 262
 263     Invoked before cancelling a pending edition, provided with the
 264     same information as ``save:before``.
 265
 266 ``cancel:after``
 267
 268     Invoked after a pending edition has been cancelled.
 269
 270 DOM events
 271 ++++++++++
 272
 273 The list view has grown hooks for the ``keyup`` event on its edition
 274 form (during edition): any such event bubbling out of the edition form
 275 will be forwarded to a method ``keyup_EVENTNAME``, where ``EVENTNAME``
 276 is the name of the key in ``$.ui.keyCode``.
 277
 278 The method will also get the event object (originally passed to the
 279 ``keyup`` handler) as its sole parameter.
 280
 281 The base editable list view has handlers for the ``ENTER`` and
 282 ``ESCAPE`` keys.
 283
 284 Editor
 285 ------
 286
 287 The list-edition modules does not generally interact with the embedded
 288 formview, delegating instead to its
 289 :js:class:`~openerp.web.list.Editor`.
 290
 291 .. js:class:: openerp.web.list.Editor(parent[, options])
 292
 293     The editor object provides a more convenient interface to form
 294     views, and simplifies the usage of form views for semi-arbitrary
 295     edition of stuff.
 296
 297     However, the editor does *not* task itself with being internally
 298     consistent at this point: calling
 299     e.g. :js:func:`~openerp.web.list.Editor.edit` multiple times in a
 300     row without saving or cancelling each edit is undefined.
 301
 302     :param parent:
 303     :type parent: :js:class:`~openerp.web.Widget`
 304     :param EditorOptions options:
 305
 306     .. js:function:: openerp.web.list.Editor.is_editing([record_state])
 307
 308         Indicates whether the editor is currently in the process of
 309         providing edition for a record.
 310
 311         Can be filtered by the state of the record being edited
 312         (whether it's a record being *created* or a record being
 313         *altered*), in which case it asserts both that an edition is
 314         underway and that the record being edited respectively does
 315         not yet exist in the database or already exists there.
 316
 317         :param record_state: state of the record being edited.
 318                              Either ``"new"`` or ``"edit"``.
 319         :type record_state: String
 320         :rtype: Boolean
 321
 322     .. js:function:: openerp.web.list.Editor.edit(record, configureField[, options])
 323
 324         Loads the provided record into the internal form view and
 325         displays the form view.
 326
 327         Will also attempt to focus the first visible field of the form
 328         view.
 329
 330         :param Object record: record to load into the form view
 331                               (key:value mapping similar to the result
 332                               of a ``read``)
 333         :param configureField: function called with each field of the
 334                                form view right after the form is
 335                                displayed, lets whoever called this
 336                                method do some last-minute
 337                                configuration of form fields.
 338         :type configureField: Function<String, openerp.web.form.Field>
 339         :param EditOptions options:
 340         :returns: jQuery delegate to the form object
 341
 342     .. js:function:: openerp.web.list.Editor.save
 343
 344         Attempts to save the internal form, then hide it
 345
 346         :returns: delegate to the record under edition (with ``id``
 347                   added for a creation). The record is not updated
 348                   from when it was passed in, aside from the ``id``
 349                   attribute.
 350
 351     .. js:function:: openerp.web.list.Editor.cancel([force=false])
 352
 353         Attemps to cancel the edition of the internal form, then hide
 354         the form
 355
 356         :param Boolean force: unconditionally cancels the edition of
 357                               the internal form, even if the user has
 358                               already entered data in it.
 359         :returns: delegate to the record under edition
 360
 361 .. js:class:: EditorOptions
 362
 363     .. js:attribute:: EditorOptions.formView
 364
 365         Form view (sub)-class to instantiate and delegate edition to.
 366
 367         By default, :js:class:`~openerp.web.FormView`
 368
 369     .. js:attribute:: EditorOptions.delegate
 370
 371         Object used to get various bits of information about how to
 372         display stuff.
 373
 374         By default, uses the editor's parent widget. See
 375         :js:class:`EditorDelegate` for the methods and attributes to
 376         provide.
 377
 378 .. js:class:: EditorDelegate
 379
 380     Informal protocol defining the methods and attributes expected of
 381     the :js:class:`~openerp.web.list.Editor`'s delegate.
 382
 383     .. js:attribute:: EditorDelegate.dataset
 384
 385         The dataset passed to the form view to synchronize the form
 386         view and the outer widget.
 387
 388     .. js:function:: EditorDelegate.edition_view(editor)
 389
 390         Called by the :js:class:`~openerp.web.list.Editor` object to
 391         get a form view (JSON) to pass along to the form view it
 392         created.
 393
 394         The result should be a valid form view, see :doc:`Form Notes
 395         <form-notes>` for various peculiarities of the form view
 396         format.
 397
 398         :param editor: editor object asking for the view
 399         :type editor: :js:class:`~openerp.web.list.Editor`
 400         :returns: form view
 401         :rtype: Object
 402
 403     .. js:function:: EditorDelegate.prepends_on_create
 404
 405         By default, the :js:class:`~openerp.web.list.Editor` will
 406         append the ids of newly created records to the
 407         :js:attr:`EditorDelegate.dataset`. If this method returns
 408         ``true``, it will prepend these ids instead.
 409
 410         :returns: whether new records should be prepended to the
 411                   dataset (instead of appended)
 412         :rtype: Boolean
 413
 414
 415 .. js:class:: EditOptions
 416
 417     Options object optionally passed into a method starting an edition
 418     to configure its setup and behavior
 419
 420     .. js:attribute:: focus_field
 421
 422         Name of the field to set focus on after setting up the edition
 423         of the record.
 424
 425         If this option is not provided, or the requested field can not
 426         be focused (invisible, readonly or not in the view), the first
 427         visible non-readonly field is focused.
 428
 429 Changes from 6.1
 430 ----------------
 431
 432 * The editable listview behavior has been rewritten pretty much from
 433   scratch, any code touching on editability will have to be modified
 434
 435   * The overloading of :js:class:`~openerp.web.ListView.Groups` and
 436     :js:class:`~openerp.web.ListView.List` for editability has been
 437     drastically simplified, and most of the behavior has been moved to
 438     the list view itself. Only
 439     :js:func:`~openerp.web.ListView.List.row_clicked` is still
 440     overridden.
 441
 442   * A new method ``get_row_for(record) -> jQuery(tr) | null`` has been
 443     added to both ListView.List and ListView.Group, it can be called
 444     from the list view to get the table row matching a record (if such
 445     a row exists).
 446
 447 * :js:func:`~openerp.web.ListView.do_button_action`'s core behavior
 448   has been split away to
 449   :js:func:`~openerp.web.ListView.handle_button`. This allows bypassing
 450   overrides of :js:func:`~openerp.web.ListView.do_button_action` in a
 451   parent class.
 452
 453   Ideally, :js:func:`~openerp.web.ListView.handle_button` should not be
 454   overridden.
 455
 456 * Modifiers handling has been improved (all modifiers information
 457   should now be available through :js:func:`~Column.modifiers_for`,
 458   not just ``invisible``)
 459
 460 * Changed some handling of the list view's record: a record may now
 461   have no id, and the listview will handle that correctly (for new
 462   records being created) as well as correctly handle the ``id`` being
 463   set.
 464
 465 * Extended the internal collections structure of the list view with
 466   `#find`_, `#succ`_ and `#pred`_.
 467
 468 .. _#find: http://underscorejs.org/#find
 469
 470 .. _#succ: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:succ
 471
 472 .. _#pred: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:pred