7 The list view provides a few style hook classes for re-styling of list views in
12 The root element of the list view, styling rules should be rooted
15 ``table.oe_list_content``
17 The root table for the listview, accessory components may be
18 generated or added outside this section, this is the list view
23 The action buttons array for the list view, with its sub-elements
27 The default "Create"/"Add" button of the list view
31 The "alternative choice" for the list view, by default text
32 along the lines of "or import" with a link.
34 ``.oe_list_field_cell``
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
43 Numeric cell types (integer and float)
47 Action button (``button`` tag in the view) inside the cell
53 ``.oe_list_field_$type``
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
59 ``.oe_list_record_selector``
66 The editable list view module adds a few supplementary style hook
67 classes, for edition situations:
71 Added to the ``.oe_list`` when the list is editable (however that
72 was done). The class may be removed on-the-fly if the list becomes
77 Added to both ``.oe_list`` and ``.oe_list_button`` (as the
78 buttons may be outside of the list view) when a row of the list is
79 currently being edited.
83 Class set on the row being edited itself. Note that the edition
84 form is *not* contained within the row, this allows for styling or
85 modifying the row while it's being edited separately. Mostly for
86 fields which can not be edited (e.g. read-only fields).
88 Columns display customization
89 -----------------------------
91 The list view provides a registry to
92 :js:class:`openerp.web.list.Column` objects allowing for the
93 customization of a column's display (e.g. so that a binary field is
94 rendered as a link to the binary file directly in the list view).
96 The registry is ``instance.web.list.columns``, the keys are of the
97 form ``tag.type`` where ``tag`` can be ``field`` or ``button``, and
98 ``type`` can be either the field's type or the field's ``@widget`` (in
101 Most of the time, you'll want to define a ``tag.widget`` key
102 (e.g. ``field.progressbar``).
104 .. js:class:: openerp.web.list.Column(id, tag, attrs)
106 .. js:function:: openerp.web.list.Column.format(record_data, options)
108 Top-level formatting method, returns an empty string if the
109 column is invisible (unless the ``process_modifiers=false``
110 option is provided); returns ``options.value_if_empty`` or an
111 empty string if there is no value in the record for the
114 Otherwise calls :js:func:`~openerp.web.list.Column._format`
115 and returns its result.
117 This method only needs to be overridden if the column has no
118 concept of values (and needs to bypass that check), for a
121 Otherwise, custom columns should generally override
122 :js:func:`~openerp.web.list.Column._format` instead.
126 .. js:function:: openerp.web.list.Column._format(record_data, options)
128 Never called directly, called if the column is visible and has
131 The default implementation calls
132 :js:func:`~openerp.web.format_value` and htmlescapes the
133 result (via ``_.escape``).
135 Note that the implementation of
136 :js:func:`~openerp.web.list.Column._format` *must* escape the
137 data provided to it, its output will *not* be escaped by
138 :js:func:`~openerp.web.list.Column.format`.
145 List view edition is an extension to the base listview providing the
146 capability of inline record edition by delegating to an embedded form
152 The editability status of a list view can be queried through the
153 :js:func:`~openerp.web.ListView.editable` method, will return a falsy
154 value if the listview is not currently editable.
156 The editability status is based on three flags:
160 If present, can be either ``"top"`` or ``"bottom"``. Either will
161 make the list view editable, with new records being respectively
162 created at the top or at the bottom of the view.
164 ``context.set_editable``
166 Boolean flag extracted from a search context (during the
167 :js:func:`~openerp.web.ListView.do_search`` handler), ``true``
168 will make the view editable (from the top), ``false`` or the
169 absence of the flag is a noop.
171 ``defaults.editable``
173 Like ``tree/@editable``, one of absent (``null``)), ``"top"`` or
174 ``"bottom"``, fallback for the list view if none of the previous
177 These three flags can only *make* a listview editable, they can *not*
178 override a previously set flag. To do that, a listview user should
179 instead cancel :ref:`the edit:before event <listview-edit-before>`.
181 The editable list view module adds a number of methods to the list
182 view, on top of implementing the :js:class:`EditorDelegate` protocol:
187 .. js:function:: openerp.web.ListView.ensure_saved
189 Attempts to resolve the pending edition, if any, by saving the
190 edited row's current state.
192 :returns: delegate resolving to all editions having been saved, or
193 rejected if a pending edition could not be saved
194 (e.g. validation failure)
196 .. js:function:: openerp.web.ListView.start_edition([record][, options])
198 Starts editing the provided record inline, through an overlay form
199 view of editable fields in the record.
201 If no record is provided, creates a new one according to the
202 editability configuration of the list view.
204 This method resolves any pending edition when invoked, before
205 starting a new edition.
207 :param record: record to edit, or null to create a new record
208 :type record: :js:class:`~openerp.web.list.Record`
209 :param EditOptions options:
210 :returns: delegate to the form used for the edition
212 .. js:function:: openerp.web.ListView.save_edition
214 Resolves the pending edition.
216 :returns: delegate to the save being completed, resolves to an
217 object with two attributes ``created`` (flag indicating
218 whether the saved record was just created or was
219 updated) and ``record`` the reloaded record having been
222 .. js:function:: openerp.web.ListView.cancel_edition([force=false])
224 Cancels pending edition, cleans up the list view in case of
225 creation (removes the empty record being created).
227 :param Boolean force: doesn't check if the user has added any
228 data, discards the edition unconditionally
233 .. js:function:: openerp.web.ListView.get_cells_for(row)
235 Extracts the cells from a listview row, and puts them in a
236 {fieldname: cell} mapping for analysis and manipulation.
241 .. js:function:: openerp.web.ListView.with_event(event_name, event, action[, args][, trigger_params])
243 Executes ``action`` in the context of the view's editor,
244 bracketing it with cancellable event signals.
246 :param String event_name: base name for the bracketing event, will
247 be postfixed by ``:before`` and
248 ``:after`` before being called
249 (respectively before and after
250 ``action`` is executed)
251 :param Object event: object passed to the ``:before`` event
253 :param Function action: function called with the view's editor as
254 its ``this``. May return a deferred.
255 :param Array args: arguments passed to ``action``
256 :param Array trigger_params: arguments passed to the ``:after``
257 event handler alongside the results
260 Behavioral Customizations
261 +++++++++++++++++++++++++
263 .. js:function:: openerp.web.ListView.handle_onwrite(record)
265 Implements the handling of the ``onwrite`` listview attribute:
266 calls the RPC methods specified by ``@onwrite``, and if that
267 method returns an array of ids loads or reloads the records
268 corresponding to those ids.
270 :param record: record being written having triggered the
272 :type record: openerp.web.list.Record
273 :returns: deferred to all reloadings being done
278 For simpler interactions by/with external users of the listview, the
279 view provides a number of dedicated events to its lifecycle.
281 .. note:: if an event is defined as *cancellable*, it means its first
282 parameter is an object on which the ``cancel`` attribute can
283 be set. If the ``cancel`` attribute is set, the view will
284 abort its current behavior as soon as possible, and rollback
285 any state modification.
287 Generally speaking, an event should only be cancelled (by
288 setting the ``cancel`` flag to ``true``), uncancelling an
289 event is undefined as event handlers are executed on a
290 first-come-first-serve basis and later handlers may
291 re-cancel an uncancelled event.
293 .. _listview-edit-before:
295 ``edit:before`` *cancellable*
297 Invoked before the list view starts editing a record.
299 Provided with an event object with a single property ``record``,
300 holding the attributes of the record being edited (``record`` is
301 empty *but not null* for a new record)
305 Invoked after the list view has gone into an edition state,
306 provided with the attributes of the record being edited (see
307 ``edit:before``) as first parameter and the form used for the
308 edition as second parameter.
310 ``save:before`` *cancellable*
312 Invoked right before saving a pending edition, provided with an
313 event object holding the listview's editor (``editor``) and the
314 edition form (``form``)
318 Invoked after a save has been completed
320 ``cancel:before`` *cancellable*
322 Invoked before cancelling a pending edition, provided with the
323 same information as ``save:before``.
327 Invoked after a pending edition has been cancelled.
332 The list view has grown hooks for the ``keyup`` event on its edition
333 form (during edition): any such event bubbling out of the edition form
334 will be forwarded to a method ``keyup_EVENTNAME``, where ``EVENTNAME``
335 is the name of the key in ``$.ui.keyCode``.
337 The method will also get the event object (originally passed to the
338 ``keyup`` handler) as its sole parameter.
340 The base editable list view has handlers for the ``ENTER`` and
346 The list-edition modules does not generally interact with the embedded
347 formview, delegating instead to its
348 :js:class:`~openerp.web.list.Editor`.
350 .. js:class:: openerp.web.list.Editor(parent[, options])
352 The editor object provides a more convenient interface to form
353 views, and simplifies the usage of form views for semi-arbitrary
356 However, the editor does *not* task itself with being internally
357 consistent at this point: calling
358 e.g. :js:func:`~openerp.web.list.Editor.edit` multiple times in a
359 row without saving or cancelling each edit is undefined.
362 :type parent: :js:class:`~openerp.web.Widget`
363 :param EditorOptions options:
365 .. js:function:: openerp.web.list.Editor.is_editing([record_state])
367 Indicates whether the editor is currently in the process of
368 providing edition for a record.
370 Can be filtered by the state of the record being edited
371 (whether it's a record being *created* or a record being
372 *altered*), in which case it asserts both that an edition is
373 underway and that the record being edited respectively does
374 not yet exist in the database or already exists there.
376 :param record_state: state of the record being edited.
377 Either ``"new"`` or ``"edit"``.
378 :type record_state: String
381 .. js:function:: openerp.web.list.Editor.edit(record, configureField[, options])
383 Loads the provided record into the internal form view and
384 displays the form view.
386 Will also attempt to focus the first visible field of the form
389 :param Object record: record to load into the form view
390 (key:value mapping similar to the result
392 :param configureField: function called with each field of the
393 form view right after the form is
394 displayed, lets whoever called this
395 method do some last-minute
396 configuration of form fields.
397 :type configureField: Function<String, openerp.web.form.Field>
398 :param EditOptions options:
399 :returns: jQuery delegate to the form object
401 .. js:function:: openerp.web.list.Editor.save
403 Attempts to save the internal form, then hide it
405 :returns: delegate to the record under edition (with ``id``
406 added for a creation). The record is not updated
407 from when it was passed in, aside from the ``id``
410 .. js:function:: openerp.web.list.Editor.cancel([force=false])
412 Attemps to cancel the edition of the internal form, then hide
415 :param Boolean force: unconditionally cancels the edition of
416 the internal form, even if the user has
417 already entered data in it.
418 :returns: delegate to the record under edition
420 .. js:class:: EditorOptions
422 .. js:attribute:: EditorOptions.formView
424 Form view (sub)-class to instantiate and delegate edition to.
426 By default, :js:class:`~openerp.web.FormView`
428 .. js:attribute:: EditorOptions.delegate
430 Object used to get various bits of information about how to
433 By default, uses the editor's parent widget. See
434 :js:class:`EditorDelegate` for the methods and attributes to
437 .. js:class:: EditorDelegate
439 Informal protocol defining the methods and attributes expected of
440 the :js:class:`~openerp.web.list.Editor`'s delegate.
442 .. js:attribute:: EditorDelegate.dataset
444 The dataset passed to the form view to synchronize the form
445 view and the outer widget.
447 .. js:function:: EditorDelegate.edition_view(editor)
449 Called by the :js:class:`~openerp.web.list.Editor` object to
450 get a form view (JSON) to pass along to the form view it
453 The result should be a valid form view, see :doc:`Form Notes
454 <form_view>` for various peculiarities of the form view
457 :param editor: editor object asking for the view
458 :type editor: :js:class:`~openerp.web.list.Editor`
462 .. js:function:: EditorDelegate.prepends_on_create
464 By default, the :js:class:`~openerp.web.list.Editor` will
465 append the ids of newly created records to the
466 :js:attr:`EditorDelegate.dataset`. If this method returns
467 ``true``, it will prepend these ids instead.
469 :returns: whether new records should be prepended to the
470 dataset (instead of appended)
474 .. js:class:: EditOptions
476 Options object optionally passed into a method starting an edition
477 to configure its setup and behavior
479 .. js:attribute:: focus_field
481 Name of the field to set focus on after setting up the edition
484 If this option is not provided, or the requested field can not
485 be focused (invisible, readonly or not in the view), the first
486 visible non-readonly field is focused.
491 * The editable listview behavior has been rewritten pretty much from
492 scratch, any code touching on editability will have to be modified
494 * The overloading of :js:class:`~openerp.web.ListView.Groups` and
495 :js:class:`~openerp.web.ListView.List` for editability has been
496 drastically simplified, and most of the behavior has been moved to
497 the list view itself. Only
498 :js:func:`~openerp.web.ListView.List.row_clicked` is still
501 * A new method ``get_row_for(record) -> jQuery(tr) | null`` has been
502 added to both ListView.List and ListView.Group, it can be called
503 from the list view to get the table row matching a record (if such
506 * :js:func:`~openerp.web.ListView.do_button_action`'s core behavior
507 has been split away to
508 :js:func:`~openerp.web.ListView.handle_button`. This allows bypassing
509 overrides of :js:func:`~openerp.web.ListView.do_button_action` in a
512 Ideally, :js:func:`~openerp.web.ListView.handle_button` should not be
515 * Modifiers handling has been improved (all modifiers information
516 should now be available through :js:func:`~Column.modifiers_for`,
517 not just ``invisible``)
519 * Changed some handling of the list view's record: a record may now
520 have no id, and the listview will handle that correctly (for new
521 records being created) as well as correctly handle the ``id`` being
524 * Extended the internal collections structure of the list view with
525 `#find`_, `#succ`_ and `#pred`_.
527 .. _#find: http://underscorejs.org/#find
529 .. _#succ: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:succ
531 .. _#pred: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:pred