Toggle navigation
Free Trial

Search View

OpenERP Web 7.0 implements a unified facets-based search view instead of the previous form-like search view (composed of buttons and multiple fields). The goal for this change is twofold:

  • Avoid the common issue of users confusing the search view with a form view and trying to create their records through it (or entering all their data, hitting the Create button expecting their record to be created and losing everything).
  • Improve the looks and behaviors of the view, and the fit within OpenERP Web’s new design.

The internal structure of the faceted search is inspired by VisualSearch 1.

As does VisualSearch, the new search view is based on Backbone and makes significant use of Backbone’s models and collections (OpenERP Web’s widgets make a good replacement for Backbone’s own views). As a result, understanding the implementation details of the OpenERP Web 7 search view also requires a basic understanding of Backbone’s models, collections and events.

Working with the search view: creating new inputs

The primary component of search views, as with all other OpenERP views, are inputs. The search view has two types of inputs — filters and fields — but only one is easly customizable: fields.

The mapping from OpenERP field types (and widgets) to search view objects is stored in the openerp.web.search.fields Registry() where new field types and widgets can be added.

Search view inputs have four main roles:

Loading defaults

Once the search view has initialized all its inputs, it will call facet_for_defaults() on each input, passing it a mapping (a javascript object) of name:value extracted from the action’s context.

This method should fetch a Facet() (or an equivalent object) for the field’s default value if applicable (if a default value for the field is found in the defaults mapping).

A default implementation is provided which checks if defaults contains a non-falsy value for the field’s @name and calls openerp.web.search.Input.facet_for() with that value.

There is no default implementation of openerp.web.search.Input.facet_for() 2, but openerp.web.search.Field() provides one, which uses the value as-is to fetch a Facet().

Providing completions

An important component of the new search view is the auto-completion pane, and the task of providing completion items is delegated to inputs through the complete() method.

This method should take a single argument (the string being typed by the user) and should fetch an Array of possible completions 3.

A default implementation is provided which fetches nothing.

A completion item is a javascript object with two keys (technically it can have any number of keys, but only these two will be used by the search view):

label

The string which will be displayed in the completion pane. It may be formatted using HTML (inline only), as a result if value is interpolated into it it must be escaped. _.escape can be used for this.

facet

Either a Facet() object or (more commonly) the corresponding attributes object. This is the facet which will be inserted into the search query if the completion item is selected by the user.

If the facet is not provided (not present, null, undefined or any other falsy value), the completion item will not be selectable and will act as a section title of sort (the label will be formatted differently). If an input may fetch multiple completion items, it should prefix those with a section title using its own name. This has no technical consequence but is clearer for users.

Providing drawer/supplementary UI

For some inputs (fields or not), interaction via autocompletion may be awkward or even impossible.

These may opt to being rendered in a “drawer” as well or instead. In that case, they will undergo the normal widget lifecycle and be rendered inside the drawer.

Any input can note its desire to be rendered in the drawer by returning a truthy value from in_drawer().

By default, in_drawer() returns the value of _in_drawer, which is false. The behavior can be toggled either by redefining the attribute to true (either on the class or on the input), or by overriding in_drawer() itself.

The input will be rendered in the full width of the drawer, it will be started only once (per view).

Converting from facet objects

Ultimately, the point of the search view is to allow searching. In OpenERP this is done via domains. On the other hand, the OpenERP Web 7 search view’s state is modelled after a collection of Facet(), and each field of a search view may have special requirements when it comes to the domains it produces 5.

So there needs to be some way of mapping Facet() objects to OpenERP search data.

This is done via an input’s get_domain() and get_context(). Each takes a Facet() and returns whatever it’s supposed to generate (a domain or a context, respectively). Either can return null if the current value does not map to a domain or context, and can throw an Invalid() exception if the value is not valid at all for the field.

Programmatic interactions: internal model

This new searchview is built around an instance of SearchQuery() available as openerp.web.SearchView.query.

The query is a backbone collection of Facet() objects, which can be interacted with directly by external objects or search view controls (e.g. widgets displayed in the drawer).

class openerp.web.search.SearchQuery()

The current search query of the search view, provides convenience behaviors for manipulating Facet() on top of the usual backbone collection methods.

The query ensures all of its facets contain at least one FacetValue() instance. Otherwise, the facet is automatically removed from the query.

openerp.web.search.SearchQuery.openerp.web.search.SearchQuery.add(values, options)

Overridden from the base add method so that adding a facet which is already in the collection will merge the value of the new facet into the old one rather than add a second facet with different values.

Arguments
  • values – facet, facet attributes or array thereof
Returns
the collection itself
openerp.web.search.SearchQuery.openerp.web.search.SearchQuery.toggle(value, options)

Convenience method for toggling facet values in a query: removes the values (through the facet itself) if they are present, adds them if they are not. If the facet itself is not in the collection, adds it automatically.

A toggling is atomic: only one change event will be triggered on the facet regardless of the number of values added to or removed from the facet (if the facet already exists), and the facet is only removed from the query if it has no value at the end of the toggling.

Arguments
  • value – facet or facet attributes
Returns
the collection
class openerp.web.search.Facet()

A backbone model representing a single facet of the current search. May map to a search field, or to a more complex or fuzzier input (e.g. a custom filter or an advanced search).

openerp.web.search.Facet.category

The displayed name of the facet, as a String. This is a backbone model attribute.

openerp.web.search.Facet.field

The Input() instance which originally created the facet 4, used to delegate some operations (such as serializing the facet’s values to domains and contexts). This is a backbone model attribute.

openerp.web.search.Facet.values

FacetValues() as a javascript attribute, stores all the values for the facet and helps propagate their events to the facet. Is also available as a backbone attribute (via #get and #set) in which cases it serializes to and deserializes from javascript arrays (via Collection#toJSON and Collection#reset).

openerp.web.search.Facet.[icon]

optional, a single ASCII letter (a-z or A-Z) mapping to the bundled mnmliconsRegular icon font.

When a facet with an icon attribute is rendered, the icon is displayed (in the icon font) in the first section of the facet instead of the category.

By default, only filters make use of this facility.

class openerp.web.search.FacetValues()

Backbone collection of FacetValue() instances.

class openerp.web.search.FacetValue()

Backbone model representing a single value within a facet, represents a pair of (displayed name, logical value).

openerp.web.search.FacetValue.label

Backbone model attribute storing the “displayable” representation of the value, visually output to the user. Must be a string.

openerp.web.search.FacetValue.value

Backbone model attribute storing the logical/internal value (of itself), will be used by Input() to serialize to domains and contexts.

Can be of any type.

Field services

Field() provides a default implementation of get_domain() and get_context() taking care of most of the peculiarities pertaining to OpenERP’s handling of fields in search views. It also provides finer hooks to let developers of new fields and widgets customize the behavior they want without necessarily having to reimplement all of get_domain() or get_context():

openerp.web.search.Field.get_context(facet)

If the field has no @context, simply returns null. Otherwise, calls value_from() once for each FacetValue() of the current Facet() (in order to extract the basic javascript object from the FacetValue() then evaluates @context with each of these values set as self, and returns the union of all these contexts.

Arguments
Returns
a context (literal or compound)
openerp.web.search.Field.get_domain(facet)

If the field has no @filter_domain, calls make_domain() once with each FacetValue() of the current Facet() as well as the field’s @name and either its @operator or default_operator.

If the field has an @filter_value, calls value_from() once per FacetValue() and evaluates @filter_value with each of these values set as self.

In either case, “ors” all of the resulting domains (using |) if there is more than one FacetValue() and returns the union of the result.

Arguments
Returns
a domain (literal or compound)
openerp.web.search.Field.make_domain(name, operator, facetValue)

Builds a literal domain from the provided data. Calls value_from() on the FacetValue() and evaluates and sets it as the domain’s third value, uses the other two parameters as the first two values.

Can be overridden to build more complex default domains.

Arguments
  • name (String) – the field’s name
  • operator (String) – the operator to use in the field’s domain
  • facetValue (openerp.web.search.FacetValue) –
Returns
Array<(String, String, Object)>
openerp.web.search.Field.value_from(facetValue)

Extracts a “bare” javascript value from the provided FacetValue(), and returns it.

The default implementation will simply return the value backbone property of the argument.

Arguments
Returns
Object
openerp.web.search.Field.default_operator

Operator used to build a domain when a field has no @operator or @filter_domain. "=" for Field()

Arbitrary data storage

Facet() and FacetValue() objects (and structures) provided by your widgets should never be altered by the search view (or an other widget). This means you are free to add arbitrary fields in these structures if you need to (because you have more complex needs than the attributes described in this document).

Ideally this should be avoided, but the possibility remains.

Changes

The displaying of the search view was significantly altered from OpenERP Web 6.1 to OpenERP Web 7.

As a result, while the external API used to interact with the search view does not change many internal details — including the interaction between the search view and its widgets — were significantly altered:

Internal operations

  • openerp.web.SearchView.do_clear() has been removed
  • openerp.web.SearchView.do_toggle_filter() has been removed

Widgets API

  • openerp.web.search.Widget.render() has been removed
  • openerp.web.search.Widget.make_id() has been removed
  • Search field objects are not openerp widgets anymore, their start is not generally called
  • clear() has been removed since clearing the search view now simply consists of removing all search facets
  • get_domain() and get_context() now take a Facet() as parameter, from which it’s their job to get whatever value they want
  • get_groupby() has been added. It returns an Array() of context-like constructs. By default, it does not do anything in Field() and it returns the various contexts of its enabled filters in FilterGroup().

Filters

  • openerp.web.search.Filter.is_enabled() has been removed
  • FilterGroup() instances are still rendered (and started) in the “advanced search” drawer.

Fields

  • get_value has been replaced by value_from() as it now takes a FacetValue() argument (instead of no argument). It provides a default implementation returning the value property of its argument.
  • The third argument to make_domain() is now a FacetValue() so child classes have all the information they need to derive the “right” resulting domain.

Custom filters

Instead of being an intrinsic part of the search view, custom filters are now a special case of filter groups. They are treated specially still, but much less so than they used to be.

Many To One

  • Because the autocompletion service is now provided by the search view itself, openerp.web.search.ManyToOneField.setup_autocomplete() has been removed.