The list view provides a few style hook classes for re-styling of list views in
various situations:
-``.oe-listview``
+``.oe_list``
The root element of the list view, styling rules should be rooted
on that class.
-``table.oe-listview-content``
+``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
The "alternative choice" for the list view, by default text
along the lines of "or import" with a link.
-``.oe-field-cell``
+``.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
Numeric cell types (integer and float)
- ``.oe-button``
+ ``.oe_button``
Action button (``button`` tag in the view) inside the cell
Readonly field cell
-``.oe-record-selector``
+ ``.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
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-listview`` and ``.oe_list_button`` (as the
+ 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.
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:
-
- ``defaults.editable``
+Editability status
+++++++++++++++++++
- ``null``, ``"top"`` or ``"bottom"``, generally broken and
- useless
+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.
- ``context.set_editable``
+The editability status is based on three flags:
- forces ``options.editable`` to ``"bottom"``
+``tree/@editable``
- ``view.arch.attrs.editable``
+ 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.
- same as ``defaults.editable``, but applied separately (after
- reloading the view), if absent delegates to
- ``options.editable`` which may have been set previously.
+``context.set_editable``
- ``options.read_only``
+ 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.
- force options.editable to false, or something?
+``defaults.editable``
- .. note:: can probably be replaced by cancelling ``edit:before``
+ Like ``tree/@editable``, one of absent (``null``)), ``"top"`` or
+ ``"bottom"``, fallback for the list view if none of the previous
+ two flags are set.
- 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.
: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
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
----------------
:js:func:`~openerp.web.ListView.List.row_clicked` is still
overridden.
- * A new method ``getRowFor(record) -> jQuery(tr) | null`` has been
+ * 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).
-* ``ListView#ensure_saved`` has been re-capitalized to
- :js:func:`~openerp.web.ListView.ensureSaved`
-
* :js:func:`~openerp.web.ListView.do_button_action`'s core behavior
has been split away to
- :js:func:`~openerp.web.ListView.handleButton`. This allows bypassing
+ :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.handleButton` should not be
+ Ideally, :js:func:`~openerp.web.ListView.handle_button` should not be
overridden.
* Modifiers handling has been improved (all modifiers information
projects / odoo / odoo.git / blobdiff