296 lines
9.8 KiB
ReStructuredText
296 lines
9.8 KiB
ReStructuredText
List View
|
|
=========
|
|
|
|
Editable list view
|
|
------------------
|
|
|
|
List view edition is an extension to the base listview providing the
|
|
capability of inline record edition by delegating to an embedded form
|
|
view.
|
|
|
|
.. todo::
|
|
|
|
cleanup options and settings for editability configuration. Right
|
|
now there are:
|
|
|
|
``defaults.editable``
|
|
|
|
``null``, ``"top"`` or ``"bottom"``, generally broken and
|
|
useless
|
|
|
|
``context.set_editable``
|
|
|
|
forces ``options.editable`` to ``"bottom"``
|
|
|
|
``view.arch.attrs.editable``
|
|
|
|
same as ``defaults.editable``, but applied separately (after
|
|
reloading the view), if absent delegates to
|
|
``options.editable`` which may have been set previously.
|
|
|
|
``options.read_only``
|
|
|
|
worthless shit added by niv in the listview directly (wtf?)
|
|
|
|
.. note:: can probably be replaced by cancelling ``edit:before``
|
|
|
|
and :js:func:`~openerp.web.ListView.set_editable` which
|
|
ultimately behaves weird-as-fuck-ly.
|
|
|
|
The editable list view module adds a number of methods to the list
|
|
view, on top of implementing the :js:class:`EditorDelegate` protocol:
|
|
|
|
Interaction Methods
|
|
+++++++++++++++++++
|
|
|
|
.. js:function:: openerp.web.ListView.ensureSaved
|
|
|
|
Attempts to resolve the pending edition, if any, by saving the
|
|
edited row's current state.
|
|
|
|
:returns: delegate resolving to all editions having been saved, or
|
|
rejected if a pending edition could not be saved
|
|
(e.g. validation failure)
|
|
|
|
.. js:function:: openerp.web.ListView.startEdition([record])
|
|
|
|
Starts editing the provided record inline, through an overlay form
|
|
view of editable fields in the record.
|
|
|
|
If no record is provided, creates a new one according to the
|
|
editability configuration of the list view.
|
|
|
|
This method resolves any pending edition when invoked, before
|
|
starting a new edition.
|
|
|
|
:type record: :js:class:`~openerp.web.list.Record`
|
|
:returns: delegate to the form used for the edition
|
|
|
|
.. js:function:: openerp.web.ListView.saveEdition
|
|
|
|
Resolves the pending edition.
|
|
|
|
:returns: delegate to the save being completed, resolves to an
|
|
object with two attributes ``created`` (flag indicating
|
|
whether the saved record was just created or was
|
|
updated) and ``record`` the reloaded record having been
|
|
edited.
|
|
|
|
.. js:function:: openerp.web.ListView.cancelEdition
|
|
|
|
Cancels pending edition, cleans up the list view in case of
|
|
creation (removes the empty record being created).
|
|
|
|
Utility Methods
|
|
+++++++++++++++
|
|
|
|
.. js:function:: openerp.web.ListView.getCellsFor(row)
|
|
|
|
Extracts the cells from a listview row, and puts them in a
|
|
{fieldname: cell} mapping for analysis and manipulation.
|
|
|
|
:param jQuery row:
|
|
:rtype: Object
|
|
|
|
.. js:function:: openerp.web.ListView.withEvent(event_name, event, action[, args][, trigger_params])
|
|
|
|
Executes ``action`` in the context of the view's editor,
|
|
bracketing it with cancellable event signals.
|
|
|
|
:param String event_name: base name for the bracketing event, will
|
|
be postfixed by ``:before`` and
|
|
``:after`` before being called
|
|
(respectively before and after
|
|
``action`` is executed)
|
|
:param Object event: object passed to the ``:before`` event
|
|
handlers.
|
|
:param Function action: function called with the view's editor as
|
|
its ``this``. May return a deferred.
|
|
:param Array args: arguments passed to ``action``
|
|
:param Array trigger_params: arguments passed to the ``:after``
|
|
event handler alongside the results
|
|
of ``action``
|
|
|
|
Behavioral Customizations
|
|
+++++++++++++++++++++++++
|
|
|
|
.. js:function:: openerp.web.ListView.handleOnWrite(record)
|
|
|
|
Implements the handling of the ``onwrite`` listview attribute:
|
|
calls the RPC methods specified by ``@onwrite``, and if that
|
|
method returns an array of ids loads or reloads the records
|
|
corresponding to those ids.
|
|
|
|
:param record: record being written having triggered the
|
|
``onwrite`` callback
|
|
:type record: openerp.web.list.Record
|
|
:returns: deferred to all reloadings being done
|
|
|
|
Events
|
|
++++++
|
|
|
|
For simpler interactions by/with external users of the listview, the
|
|
view provides a number of dedicated events to its lifecycle.
|
|
|
|
.. note:: if an event is defined as *cancellable*, it means its first
|
|
parameter is an object on which the ``cancel`` attribute can
|
|
be set. If the ``cancel`` attribute is set, the view will
|
|
abort its current behavior as soon as possible, and rollback
|
|
any state modification.
|
|
|
|
``edit:before`` *cancellable*
|
|
|
|
Invoked before the list view starts editing a record.
|
|
|
|
Provided with an event object with a single property ``record``,
|
|
holding the attributes of the record being edited (``record`` is
|
|
empty *but not null* for a new record)
|
|
|
|
``edit:after``
|
|
|
|
Invoked after the list view has gone into an edition state,
|
|
provided with the attributes of the record being edited (see
|
|
``edit:before``) as first parameter and the form used for the
|
|
edition as second parameter.
|
|
|
|
``save:before`` *cancellable*
|
|
|
|
Invoked right before saving a pending edition, provided with an
|
|
event object holding the listview's editor (``editor``) and the
|
|
edition form (``form``)
|
|
|
|
``save:after``
|
|
|
|
Invoked after a save has been completed
|
|
|
|
.. todo:: currently invoked before the record has reloaded, which
|
|
is kinda shitty
|
|
|
|
``cancel:before`` *cancellable*
|
|
|
|
Invoked before cancelling a pending edition, provided with the
|
|
same information as ``save:before``.
|
|
|
|
``cancel:after``
|
|
|
|
Invoked after a pending edition has been cancelled.
|
|
|
|
Editor
|
|
------
|
|
|
|
The list-edition modules does not generally interact with the embedded
|
|
formview, delegating instead to its
|
|
:js:class:`~openerp.web.list.Editor`.
|
|
|
|
.. js:class:: openerp.web.list.Editor(parent[, options])
|
|
|
|
The editor object provides a more convenient interface to form
|
|
views, and simplifies the usage of form views for semi-arbitrary
|
|
edition of stuff.
|
|
|
|
However, the editor does *not* task itself with being internally
|
|
consistent at this point: calling
|
|
e.g. :js:func:`~openerp.web.list.Editor.edit` multiple times in a
|
|
row without saving or cancelling each edit is undefined.
|
|
|
|
.. todo:: define this behavior
|
|
|
|
:param parent:
|
|
:type parent: :js:class:`~openerp.web.Widget`
|
|
:param EditorOptions options:
|
|
|
|
.. js:function:: openerp.web.list.Editor.isEditing
|
|
|
|
Indicates whether the editor is currently in the process of
|
|
providing edition for a field.
|
|
|
|
:rtype: Boolean
|
|
|
|
.. js:function:: openerp.web.list.Editor.edit(record, configureField)
|
|
|
|
Loads the provided record into the internal form view and
|
|
displays the form view.
|
|
|
|
Will also attempt to focus the first visible field of the form
|
|
view.
|
|
|
|
:param Object record: record to load into the form view
|
|
(key:value mapping similar to the result
|
|
of a ``read``)
|
|
:param configureField: function called with each field of the
|
|
form view right after the form is
|
|
displayed, lets whoever called this
|
|
method do some last-minute
|
|
configuration of form fields.
|
|
:type configureField: Function<String, openerp.web.form.Field>
|
|
:returns: jQuery delegate to the form object
|
|
|
|
.. js:function:: openerp.web.list.Editor.save
|
|
|
|
Attempts to save the internal form, then hide it
|
|
|
|
:returns: delegate to the record under edition (with ``id``
|
|
added for a creation). The record is not updated
|
|
from when it was passed in, aside from the ``id``
|
|
attribute.
|
|
|
|
.. js:function:: openerp.web.list.Editor.cancel
|
|
|
|
Attemps to cancel the edition of the internal form, then hide
|
|
the form
|
|
|
|
:returns: delegate to the record under edition
|
|
|
|
.. js:class:: EditorOptions
|
|
|
|
.. js:attribute:: EditorOptions.formView
|
|
|
|
Form view (sub)-class to instantiate and delegate edition to.
|
|
|
|
By default, :js:class:`~openerp.web.FormView`
|
|
|
|
.. js:attribute:: EditorOptions.delegate
|
|
|
|
Object used to get various bits of information about how to
|
|
display stuff.
|
|
|
|
By default, uses the editor's parent widget. See
|
|
:js:class:`EditorDelegate` for the methods and attributes to
|
|
provide.
|
|
|
|
.. js:class:: EditorDelegate
|
|
|
|
Informal protocol defining the methods and attributes expected of
|
|
the :js:class:`~openerp.web.list.Editor`'s delegate.
|
|
|
|
.. js:attribute:: EditorDelegate.dataset
|
|
|
|
The dataset passed to the form view to synchronize the form
|
|
view and the outer widget.
|
|
|
|
.. js:function:: EditorDelegate.editionView(editor)
|
|
|
|
Called by the :js:class:`~openerp.web.list.Editor` object to
|
|
get a form view (JSON) to pass along to the form view it
|
|
created.
|
|
|
|
The result should be a valid form view, see :doc:`Form Notes
|
|
<form-notes>` for various peculiarities of the form view
|
|
format.
|
|
|
|
:param editor: editor object asking for the view
|
|
:type editor: :js:class:`~openerp.web.list.Editor`
|
|
:returns: form view
|
|
:rtype: Object
|
|
|
|
.. js:function:: EditorDelegate.isPrependOnCreate
|
|
|
|
By default, the :js:class:`~openerp.web.list.Editor` will
|
|
append the ids of newly created records to the
|
|
:js:attr:`EditorDelegate.dataset`. If this method returns
|
|
``true``, it will prepend these ids instead.
|
|
|
|
:returns: whether new records should be prepended to the
|
|
dataset (instead of appended)
|
|
:rtype: Boolean
|