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
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
).
-
class
openerp.web.list.
Column
(id, tag, attrs)¶ -
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); returnsoptions.value_if_empty
or an empty string if there is no value in the record for the column.Otherwise calls
_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
_format()
instead.Returns: String
-
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
format_value()
and htmlescapes the result (via_.escape
).Note that the implementation of
_format()
must escape the data provided to it, its output will not be escaped byformat()
.Returns: String
-
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.
Editability status¶
The editability status of a list view can be queried through the
editable()
method, will return a falsy
value if the listview is not currently editable.
The editability status is based on three flags:
tree/@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.
context.set_editable
Boolean flag extracted from a search context (during thedo_search`()
handler),true
will make the view editable (from the top),false
or the absence of the flag is a noop.
defaults.editable
Liketree/@editable
, one of absent (null
)),"top"
or"bottom"
, fallback for the list view if none of the previous two flags are set.
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 the edit:before event.
The editable list view module adds a number of methods to the list
view, on top of implementing the EditorDelegate()
protocol:
Interaction Methods¶
-
openerp.web.ListView.
ensure_saved
()¶ 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)
-
openerp.web.ListView.
start_edition
([record][, options])¶ 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.
Arguments: - record (
Record()
) – record to edit, or null to create a new record - options (EditOptions) –
Returns: delegate to the form used for the edition
- record (
-
openerp.web.ListView.
save_edition
()¶ 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) andrecord
the reloaded record having been edited.
-
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).
Arguments: - force (Boolean) – doesn’t check if the user has added any data, discards the edition unconditionally
Utility Methods¶
-
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.
Arguments: - row (jQuery) –
Return type: Object
-
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.Arguments: - event_name (String) – base name for the bracketing event, will
be postfixed by
:before
and:after
before being called (respectively before and afteraction
is executed) - event (Object) – object passed to the
:before
event handlers. - action (Function) – function called with the view’s editor as
its
this
. May return a deferred. - args (Array) – arguments passed to
action
- trigger_params (Array) – arguments passed to the
:after
event handler alongside the results ofaction
- event_name (String) – base name for the bracketing event, will
be postfixed by
Behavioral Customizations¶
-
openerp.web.ListView.
handle_onwrite
(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.Arguments: - record (openerp.web.list.Record) – record being written having triggered the
onwrite
callback
Returns: deferred to all reloadings being done
- record (openerp.web.list.Record) – record being written having triggered the
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.
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.
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 (seeedit: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
cancel:before
cancellable
Invoked before cancelling a pending edition, provided with the same information assave:before
.
cancel:after
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¶
The list-edition modules does not generally interact with the embedded
formview, delegating instead to its
Editor()
.
-
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.
edit()
multiple times in a row without saving or cancelling each edit is undefined.Arguments: - parent (
Widget()
) – - options (EditorOptions) –
-
openerp.web.list.Editor.
is_editing
([record_state])¶ Indicates whether the editor is currently in the process of 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.
Arguments: - record_state (String) – state of the record being edited.
Either
"new"
or"edit"
.
Return type: Boolean
- record_state (String) – state of the record being edited.
Either
-
openerp.web.list.Editor.
edit
(record, configureField[, options])¶ 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.
Arguments: - record (Object) – record to load into the form view
(key:value mapping similar to the result
of a
read
) - configureField (Function<String, openerp.web.form.Field>) – 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.
- options (EditOptions) –
Returns: jQuery delegate to the form object
- record (Object) – record to load into the form view
(key:value mapping similar to the result
of a
-
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 theid
attribute.
-
openerp.web.list.Editor.
cancel
([force=false])¶ Attemps to cancel the edition of the internal form, then hide the form
Arguments: - force (Boolean) – 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
- parent (
-
class
EditorOptions
()¶ -
EditorOptions.
formView
¶ Form view (sub)-class to instantiate and delegate edition to.
By default,
FormView()
-
EditorOptions.
delegate
¶ Object used to get various bits of information about how to display stuff.
By default, uses the editor’s parent widget. See
EditorDelegate()
for the methods and attributes to provide.
-
-
class
EditorDelegate
()¶ Informal protocol defining the methods and attributes expected of the
Editor()
‘s delegate.-
EditorDelegate.
dataset
¶ The dataset passed to the form view to synchronize the form view and the outer widget.
-
EditorDelegate.
edition_view
(editor)¶ Called by the
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 Form Notes for various peculiarities of the form view format.
Arguments: - editor (
Editor()
) – editor object asking for the view
Returns: form view
Return type: Object
- editor (
-
EditorDelegate.
prepends_on_create
()¶ By default, the
Editor()
will append the ids of newly created records to theEditorDelegate.dataset
. If this method returnstrue
, it will prepend these ids instead.Returns: whether new records should be prepended to the dataset (instead of appended) Return type: Boolean
-
-
class
EditOptions
()¶ Options object optionally passed into a method starting an edition to configure its setup and behavior
-
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
Groups()
andList()
for editability has been drastically simplified, and most of the behavior has been moved to the list view itself. Onlyrow_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).
- The overloading of
do_button_action()
‘s core behavior has been split away tohandle_button()
. This allows bypassing overrides ofdo_button_action()
in a parent class.Ideally,
handle_button()
should not be overridden.Modifiers handling has been improved (all modifiers information should now be available through
modifiers_for()
, not justinvisible
)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.