List View
=========
+Style Hooks
+-----------
+
+The list view provides a few style hook classes for re-styling of list views in
+various situations:
+
+``.oe_list``
+
+ The root element of the list view, styling rules should be rooted
+ on that class.
+
+``table.oe_list_content``
+
+ The root table for the listview, accessory components may be
+ generated or added outside this section, this is the list view
+ "proper".
+
+``.oe_list_buttons``
+
+ The action buttons array for the list view, with its sub-elements
+
+ ``.oe_list_add``
+
+ The default "Create"/"Add" button of the list view
+
+ ``.oe_alternative``
+
+ The "alternative choice" for the list view, by default text
+ along the lines of "or import" with a link.
+
+``.oe_list_field_cell``
+
+ The cell (``td``) for a given field of the list view, cells which
+ are *not* fields (e.g. name of a group, or number of items in a
+ group) will not have this class. The field cell can be further
+ specified:
+
+ ``.oe_number``
+
+ Numeric cell types (integer and float)
+
+ ``.oe_button``
+
+ Action button (``button`` tag in the view) inside the cell
+
+ ``.oe_readonly``
+
+ Readonly field cell
+
+ ``.oe_list_field_$type``
+
+ Additional class for the precise type of the cell, ``$type``
+ is the field's @widget if there is one, otherwise it's the
+ field's type.
+
+``.oe_list_record_selector``
+
+ Selector cells
+
+Editable list view
+++++++++++++++++++
+
+The editable list view module adds a few supplementary style hook
+classes, for edition situations:
+
+``.oe_list_editable``
+
+ Added to the ``.oe_list`` when the list is editable (however that
+ was done). The class may be removed on-the-fly if the list becomes
+ non-editable.
+
+``.oe_editing``
+
+ Added to both ``.oe_list`` and ``.oe_list_button`` (as the
+ buttons may be outside of the list view) when a row of the list is
+ currently being edited.
+
+``tr.oe_edition``
+
+ Class set on the row being edited itself. Note that the edition
+ form is *not* contained within the row, this allows for styling or
+ modifying the row while it's being edited separately. Mostly for
+ fields which can not be edited (e.g. read-only fields).
+
+Columns display customization
+-----------------------------
+
+The list view provides a registry to
+:js:class:`openerp.web.list.Column` objects allowing for the
+customization of a column's display (e.g. so that a binary field is
+rendered as a link to the binary file directly in the list view).
+
+The registry is ``instance.web.list.columns``, the keys are of the
+form ``tag.type`` where ``tag`` can be ``field`` or ``button``, and
+``type`` can be either the field's type or the field's ``@widget`` (in
+the view).
+
+Most of the time, you'll want to define a ``tag.widget`` key
+(e.g. ``field.progressbar``).
+
+.. js:class:: openerp.web.list.Column(id, tag, attrs)
+
+ .. js:function:: openerp.web.list.Column.format(record_data, options)
+
+ Top-level formatting method, returns an empty string if the
+ column is invisible (unless the ``process_modifiers=false``
+ option is provided); returns ``options.value_if_empty`` or an
+ empty string if there is no value in the record for the
+ column.
+
+ Otherwise calls :js:func:`~openerp.web.list.Column._format`
+ and returns its result.
+
+ This method only needs to be overridden if the column has no
+ concept of values (and needs to bypass that check), for a
+ button for instance.
+
+ Otherwise, custom columns should generally override
+ :js:func:`~openerp.web.list.Column._format` instead.
+
+ :returns: String
+
+ .. js:function:: openerp.web.list.Column._format(record_data, options)
+
+ Never called directly, called if the column is visible and has
+ a value.
+
+ The default implementation calls
+ :js:func:`~openerp.web.format_value` and htmlescapes the
+ result (via ``_.escape``).
+
+ Note that the implementation of
+ :js:func:`~openerp.web.list.Column._format` *must* escape the
+ data provided to it, its output will *not* be escaped by
+ :js:func:`~openerp.web.list.Column.format`.
+
+ :returns: String
+
Editable list view
------------------
capability of inline record edition by delegating to an embedded form
view.
-.. todo::
-
- cleanup options and settings for editability configuration. Right
- now there are:
+Editability status
+++++++++++++++++++
- ``defaults.editable``
+The editability status of a list view can be queried through the
+:js:func:`~openerp.web.ListView.editable` method, will return a falsy
+value if the listview is not currently editable.
- ``null``, ``"top"`` or ``"bottom"``, generally broken and
- useless
+The editability status is based on three flags:
- ``context.set_editable``
+``tree/@editable``
- forces ``options.editable`` to ``"bottom"``
+ If present, can be either ``"top"`` or ``"bottom"``. Either will
+ make the list view editable, with new records being respectively
+ created at the top or at the bottom of the view.
- ``view.arch.attrs.editable``
+``context.set_editable``
- same as ``defaults.editable``, but applied separately (after
- reloading the view), if absent delegates to
- ``options.editable`` which may have been set previously.
+ Boolean flag extracted from a search context (during the
+ :js:func:`~openerp.web.ListView.do_search`` handler), ``true``
+ will make the view editable (from the top), ``false`` or the
+ absence of the flag is a noop.
- ``options.read_only``
+``defaults.editable``
- worthless shit added by niv in the listview directly (wtf?)
+ Like ``tree/@editable``, one of absent (``null``)), ``"top"`` or
+ ``"bottom"``, fallback for the list view if none of the previous
+ two flags are set.
- .. note:: can probably be replaced by cancelling ``edit:before``
-
- and :js:func:`~openerp.web.ListView.set_editable` which
- ultimately behaves weird-as-fuck-ly.
+These three flags can only *make* a listview editable, they can *not*
+override a previously set flag. To do that, a listview user should
+instead cancel :ref:`the edit:before event <listview-edit-before>`.
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
+.. js:function:: openerp.web.ListView.ensure_saved
Attempts to resolve the pending edition, if any, by saving the
edited row's current state.
rejected if a pending edition could not be saved
(e.g. validation failure)
-.. js:function:: openerp.web.ListView.startEdition([record])
+.. js:function:: openerp.web.ListView.start_edition([record][, options])
Starts editing the provided record inline, through an overlay form
view of editable fields in the record.
This method resolves any pending edition when invoked, before
starting a new edition.
+ :param record: record to edit, or null to create a new record
:type record: :js:class:`~openerp.web.list.Record`
+ :param EditOptions options:
:returns: delegate to the form used for the edition
-.. js:function:: openerp.web.ListView.saveEdition
+.. js:function:: openerp.web.ListView.save_edition
Resolves the pending edition.
updated) and ``record`` the reloaded record having been
edited.
-.. js:function:: openerp.web.ListView.cancelEdition
+.. js:function:: openerp.web.ListView.cancel_edition([force=false])
Cancels pending edition, cleans up the list view in case of
creation (removes the empty record being created).
+ :param Boolean force: doesn't check if the user has added any
+ data, discards the edition unconditionally
+
Utility Methods
+++++++++++++++
-.. js:function:: openerp.web.ListView.getCellsFor(row)
+.. js:function:: openerp.web.ListView.get_cells_for(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])
+.. js:function:: openerp.web.ListView.with_event(event_name, event, action[, args][, trigger_params])
Executes ``action`` in the context of the view's editor,
bracketing it with cancellable event signals.
Behavioral Customizations
+++++++++++++++++++++++++
-.. js:function:: openerp.web.ListView.handleOnWrite(record)
+.. js:function:: openerp.web.ListView.handle_onwrite(record)
Implements the handling of the ``onwrite`` listview attribute:
calls the RPC methods specified by ``@onwrite``, and if that
abort its current behavior as soon as possible, and rollback
any state modification.
+ Generally speaking, an event should only be cancelled (by
+ setting the ``cancel`` flag to ``true``), uncancelling an
+ event is undefined as event handlers are executed on a
+ first-come-first-serve basis and later handlers may
+ re-cancel an uncancelled event.
+
+.. _listview-edit-before:
+
``edit:before`` *cancellable*
Invoked before the list view starts editing a record.
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
Invoked after a pending edition has been cancelled.
+DOM events
+++++++++++
+
+The list view has grown hooks for the ``keyup`` event on its edition
+form (during edition): any such event bubbling out of the edition form
+will be forwarded to a method ``keyup_EVENTNAME``, where ``EVENTNAME``
+is the name of the key in ``$.ui.keyCode``.
+
+The method will also get the event object (originally passed to the
+``keyup`` handler) as its sole parameter.
+
+The base editable list view has handlers for the ``ENTER`` and
+``ESCAPE`` keys.
+
Editor
------
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
+ .. js:function:: openerp.web.list.Editor.is_editing([record_state])
Indicates whether the editor is currently in the process of
- providing edition for a field.
+ providing edition for a record.
+ Can be filtered by the state of the record being edited
+ (whether it's a record being *created* or a record being
+ *altered*), in which case it asserts both that an edition is
+ underway and that the record being edited respectively does
+ not yet exist in the database or already exists there.
+
+ :param record_state: state of the record being edited.
+ Either ``"new"`` or ``"edit"``.
+ :type record_state: String
:rtype: Boolean
- .. js:function:: openerp.web.list.Editor.edit(record, configureField)
+ .. js:function:: openerp.web.list.Editor.edit(record, configureField[, options])
Loads the provided record into the internal form view and
displays the form view.
method do some last-minute
configuration of form fields.
:type configureField: Function<String, openerp.web.form.Field>
+ :param EditOptions options:
:returns: jQuery delegate to the form object
.. js:function:: openerp.web.list.Editor.save
from when it was passed in, aside from the ``id``
attribute.
- .. js:function:: openerp.web.list.Editor.cancel
+ .. js:function:: openerp.web.list.Editor.cancel([force=false])
Attemps to cancel the edition of the internal form, then hide
the form
+ :param Boolean force: unconditionally cancels the edition of
+ the internal form, even if the user has
+ already entered data in it.
:returns: delegate to the record under edition
.. js:class:: EditorOptions
The dataset passed to the form view to synchronize the form
view and the outer widget.
- .. js:function:: EditorDelegate.editionView(editor)
+ .. js:function:: EditorDelegate.edition_view(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
:returns: form view
:rtype: Object
- .. js:function:: EditorDelegate.isPrependOnCreate
+ .. js:function:: EditorDelegate.prepends_on_create
By default, the :js:class:`~openerp.web.list.Editor` will
append the ids of newly created records to the
:returns: whether new records should be prepended to the
dataset (instead of appended)
:rtype: Boolean
+
+
+.. js:class:: EditOptions
+
+ Options object optionally passed into a method starting an edition
+ to configure its setup and behavior
+
+ .. js:attribute:: focus_field
+
+ Name of the field to set focus on after setting up the edition
+ of the record.
+
+ If this option is not provided, or the requested field can not
+ be focused (invisible, readonly or not in the view), the first
+ visible non-readonly field is focused.
+
+Changes from 6.1
+----------------
+
+* The editable listview behavior has been rewritten pretty much from
+ scratch, any code touching on editability will have to be modified
+
+ * The overloading of :js:class:`~openerp.web.ListView.Groups` and
+ :js:class:`~openerp.web.ListView.List` for editability has been
+ drastically simplified, and most of the behavior has been moved to
+ the list view itself. Only
+ :js:func:`~openerp.web.ListView.List.row_clicked` is still
+ overridden.
+
+ * A new method ``get_row_for(record) -> jQuery(tr) | null`` has been
+ added to both ListView.List and ListView.Group, it can be called
+ from the list view to get the table row matching a record (if such
+ a row exists).
+
+* :js:func:`~openerp.web.ListView.do_button_action`'s core behavior
+ has been split away to
+ :js:func:`~openerp.web.ListView.handle_button`. This allows bypassing
+ overrides of :js:func:`~openerp.web.ListView.do_button_action` in a
+ parent class.
+
+ Ideally, :js:func:`~openerp.web.ListView.handle_button` should not be
+ overridden.
+
+* Modifiers handling has been improved (all modifiers information
+ should now be available through :js:func:`~Column.modifiers_for`,
+ not just ``invisible``)
+
+* Changed some handling of the list view's record: a record may now
+ have no id, and the listview will handle that correctly (for new
+ records being created) as well as correctly handle the ``id`` being
+ set.
+
+* Extended the internal collections structure of the list view with
+ `#find`_, `#succ`_ and `#pred`_.
+
+.. _#find: http://underscorejs.org/#find
+
+.. _#succ: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:succ
+
+.. _#pred: http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#v:pred
projects / odoo / odoo.git / blobdiff