[FIX] replace references to parent in editor with delegate, write some basic APIDoc
bzr revid: xmo@openerp.com-20120703133210-kgrj7y10cr3c8hai
This commit is contained in:
Xavier Morel
parent
336443d604
commit
895dfe2448
|
|
@ -139,7 +139,7 @@ openerp.web.list_editable = function (instance) {
|
|||
if (!record) {
|
||||
record = new instance.web.list.Record();
|
||||
this.records.add(record, {
|
||||
at: this.options.editable === 'top' ? 0 : null});
|
||||
at: this.isPrependOnCreate() ? 0 : null});
|
||||
}
|
||||
var $recordRow = this.groups.getRowFor(record);
|
||||
var cells = this.getCellsFor($recordRow);
|
||||
|
|
@ -293,6 +293,9 @@ openerp.web.list_editable = function (instance) {
|
|||
}));
|
||||
});
|
||||
},
|
||||
isPrependOnCreate: function () {
|
||||
return this.options.editable === 'top';
|
||||
}
|
||||
});
|
||||
|
||||
instance.web.list.Editor = instance.web.Widget.extend({
|
||||
|
|
@ -305,18 +308,21 @@ openerp.web.list_editable = function (instance) {
|
|||
* @param {instance.web.Widget} parent
|
||||
* @param {Object} options
|
||||
* @param {instance.web.FormView} [options.formView=instance.web.FormView]
|
||||
* @param {Object} [options.delegate]
|
||||
*/
|
||||
init: function (parent, options) {
|
||||
this._super(parent);
|
||||
this.options = options || {};
|
||||
_.defaults(this.options, {
|
||||
formView: instance.web.FormView
|
||||
formView: instance.web.FormView,
|
||||
delegate: this.getParent()
|
||||
});
|
||||
this.delegate = this.options.delegate;
|
||||
|
||||
this.record = null;
|
||||
|
||||
this.form = new (this.options.formView)(
|
||||
this, this.getParent().dataset, false, {
|
||||
this, this.delegate.dataset, false, {
|
||||
initial_mode: 'edit',
|
||||
$buttons: $(),
|
||||
$pager: $()
|
||||
|
|
@ -325,8 +331,7 @@ openerp.web.list_editable = function (instance) {
|
|||
start: function () {
|
||||
var self = this;
|
||||
var _super = this._super();
|
||||
// TODO: getParent() should be delegate defaulting to getParent()
|
||||
this.form.embedded_view = this.getParent().editionView(this);
|
||||
this.form.embedded_view = this.delegate.editionView(this);
|
||||
var form_ready = this.form.appendTo(this.$element).then(
|
||||
self.form.proxy('do_hide'));
|
||||
return $.when(_super, form_ready);
|
||||
|
|
@ -363,7 +368,7 @@ openerp.web.list_editable = function (instance) {
|
|||
save: function () {
|
||||
var self = this;
|
||||
return this.form
|
||||
.do_save(null, this.getParent().options.editable === 'top')
|
||||
.do_save(null, this.delegate.isPrependOnCreate())
|
||||
.pipe(function (result) {
|
||||
var created = result.created && !self.record.id;
|
||||
if (created) {
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ Contents:
|
|||
|
||||
search-view
|
||||
|
||||
list-view
|
||||
form-notes
|
||||
|
||||
Older stuff
|
||||
|
|
|
|||
|
|
@ -0,0 +1,295 @@
|
|||
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
|
||||
Loading…
Reference in New Issue