diff --git a/addons/web/static/src/js/search.js b/addons/web/static/src/js/search.js
index 14378fb64dd..d083f2ffdd5 100644
--- a/addons/web/static/src/js/search.js
+++ b/addons/web/static/src/js/search.js
@@ -55,6 +55,14 @@ _.extend(VS.ui.SearchBox.prototype, {
renderSearchInput: SearchBox_renderSearchInput,
searchEvent: SearchBox_searchEvent
});
+_.extend(VS.model.SearchFacet.prototype, {
+ value: function () {
+ if (this.has('json')) {
+ return this.get('json');
+ }
+ return this.get('value');
+ }
+});
openerp.web.SearchView = openerp.web.Widget.extend(/** @lends openerp.web.SearchView# */{
template: "SearchView",
diff --git a/doc/search-view.rst b/doc/search-view.rst
index 1235572977d..762d1dd5a6c 100644
--- a/doc/search-view.rst
+++ b/doc/search-view.rst
@@ -1,19 +1,129 @@
Search View
===========
+OpenERP Web 6.2 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 faceted search is implemented through a monkey-patched
+`VisualSearch `_
+[#]_. VisualSearch is based on `Backbone
+`_ and makes significant
+use of Backbone's models and views. As a result, understanding the
+implementation of the OpenERP Web 6.2 search view also requires a
+basic understanding of Backbone.
+
+Interaction between the Search View and VisualSearch
+----------------------------------------------------
+
+The core data abstraction in VisualSearch is
+:js:class:`VS.model.SearchQuery`, a backbone Collection holding
+instances of the :js:class:`VS.model.SearchFacet` backbone Model.
+
+Backbone models can hold any number of informal properties interacted
+with through the :js:func:`~Backbone.Model.get` and
+:js:func:`~Backbone.Model.set` methods. VisualSearch reserves three
+such properties for its behavior, these properties *must* be correctly
+set on all search facets created programmatically:
+
+``app``
+ a reference to the VisualSearch instance using this facet. In the
+ search view, this instance is available as the
+ :js:attr:`~openerp.web.SearchView.vs` attribute to the searchview
+ instance.
+
+``category``
+ the *name* of the facet, displayed in the first section of a facet
+ view. The category *may* be ``null``.
+
+``value``
+ the *displayed value* of the facet, it is directly printed to the
+ right of the category.
+
+The search view uses additional keys to store state and data it needs
+to associate with facet objects:
+
+``field``
+ the search field instance which created the facet, optional. May or
+ may not be inferrable from ``category``.
+
+``json``
+ the "logical" value of the facet, can be absent if the logical and
+ "printable" values of the facet are the same (e.g. for a basic text
+ field).
+
+ This value may be a complex javascript object such as an array or an
+ object (the name stands for json-compatible value, it is not
+ JSON-encoded).
+
+.. note::
+
+ in order to simplify fetching an actual value from a search facet
+ model, :js:class:`VS.model.SearchFacet` has been extended with a
+ :js:func:`~VS.model.SearchFacet.value` method
+
+Extensions and patches to VisualSearch
+++++++++++++++++++++++++++++++++++++++
+
+.. js:function:: VS.model.SearchFacet.value()
+
+ Bundles the logic of selecting between ``json`` and ``value`` in
+ order to get the logical value of a facet.
+
+.. js:attribute:: VS.options.callbacks.make_facet
+
+ Called by :js:class:`VS.ui.SearchBox` when it needs to create a
+ new search facet *view*. By default this is not supported by
+ VisualSearch, and requires monkey-patching
+ :js:func:`VS.ui.SearchBox.renderFacet`.
+
+ This patch should not alter any behavior if
+ :js:attr:`~VS.options.callbacks.make_facet` is not used.
+
+.. js:attribute:: VS.options.callbacks.make_input
+
+ Similar to :js:attr:`~VS.options.callbacks.make_facet`, but called
+ when the :js:class:`~VS.ui.SearchBox` needs to create a search
+ input view. It requires monkey-patching
+ :js:func:`VS.ui.SearchBox.renderSearchInput`.
+
+Finally, :js:func:`VS.ui.SearchBox.searchEvent` is monkey-patched to
+get rid of its serialize/load round-tripping of facet data: the
+additional attributes needed by the search view don't round-trip (at
+all) so VisualSearch must not load any data from its (fairly
+simplistic) text-serialization format
+
+.. note::
+
+ a second issue is that — as of `commit 3fca87101d`_ — VisualSearch
+ correctly serializes facet categories containing spaces but is
+ unable to load them back in. It also does not handle facets with
+ *empty* categories correctly.
+
Loading Defaults
----------------
After loading the view data, the SearchView will call
-:js:func:`openerp.web.search.Input.facet_for_defaults` with the ``defaults``
-mapping of key:values (where each key corresponds to an input).
+:js:func:`openerp.web.search.Input.facet_for_defaults` with the
+``defaults`` mapping of key:values (where each key corresponds to an
+input).
-The default implementation is to check if there is a default value for the
-current input's name (via :js:attr:`openerp.web.search.Input.attrs.name`) and
-if there is to convert this value to a :js:class:`VS.models.SearchFacet` by
-calling :js:func:`openerp.web.search.Input.facet_for`.
+The default implementation is to check if there is a default value for
+the current input's name (via
+:js:attr:`openerp.web.search.Input.attrs.name`) and if there is to
+convert this value to a :js:class:`VS.models.SearchFacet` by calling
+:js:func:`openerp.web.search.Input.facet_for`.
-Both methods should return a ``jQuery.Deferred``.
+Both methods should return a
+``jQuery.Deferred``.
There is no built-in (default) implementation of
:js:func:`openerp.web.search.Input.facet_for`.
@@ -21,16 +131,17 @@ There is no built-in (default) implementation of
Providing auto-completion
-------------------------
-An important component of the unified search view is the faceted autocompletion
-pane. In order to provide good user and developer experiences, this pane is
-pluggable (value-wise): each and every control of the search view can check for
-(and provide) categorized auto-completions for a given value being typed by
-the user.
+An important component of the unified search view is the faceted
+autocompletion pane. In order to provide good user and developer
+experiences, this pane is pluggable (value-wise): each and every
+control of the search view can check for (and provide) categorized
+auto-completions for a given value being typed by the user.
-This is done by implementing :js:func:`openerp.web.search.Input.complete`: the
-method is provided with a value to complete, and the input must either return
-a ``jQuery.Deferred`` or fetch (by returning a ``jQuery.Deferred``) an
-array of completion values.
+This is done by implementing
+:js:func:`openerp.web.search.Input.complete`: the method is provided
+with a value to complete, and the input must either return a
+``jQuery.Deferred`` or fetch (by returning a
+``jQuery.Deferred``) an array of completion values.
.. todo:: describe the shape of "completion values"?
@@ -42,21 +153,20 @@ Changes
.. todo:: merge in changelog instead
-The displaying of the search view was significantly altered from OpenERP Web
-6.1 to OpenERP Web 6.2: it went form a form-like appearance (inherited from
-previous web client versions and ultimately from the GTK client) to a
-"universal" search input with facets.
+The displaying of the search view was significantly altered from
+OpenERP Web 6.1 to OpenERP Web 6.2.
-As a result, while the external API used to interact with the search view does
-not change the internal details — including the interaction between the search
-view and its widgets — is significantly altered:
+As a result, while the external API used to interact with the search
+view does not change the internal details — including the interaction
+between the search view and its widgets — is significantly altered:
Widgets API
+++++++++++
* :js:func:`openerp.web.search.Widget.render` has been removed
-* Search field objects are not openerp widgets anymore, their ``start`` is
- not generally called
+
+* Search field objects are not openerp widgets anymore, their
+ ``start`` is not generally called
Filters
+++++++
@@ -66,6 +176,14 @@ Filters
Many To One
+++++++++++
-* Because the autocompletion service is now provided by the search view
- itself, :js:func:`openerp.web.search.ManyToOneField.setup_autocomplete` has
+* Because the autocompletion service is now provided by the search
+ view itself,
+ :js:func:`openerp.web.search.ManyToOneField.setup_autocomplete` has
been removed.
+
+.. [#] the library code is untouched, all patching is performed in the
+ Search view's implementation module. Changes to the
+ VisualSearch code should only update the library to new
+ revisions or releases.
+.. _commit 3fca87101d:
+ https://github.com/documentcloud/visualsearch/commit/3fca87101d