[IMP] docdocdoc

start some documentation on VisualSearch and the interaction between the search view and VS

bzr revid: xmo@openerp.com-20120320144738-9jkdw78os1gect1e

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",

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 <http://documentcloud.github.com/visualsearch/>`_
+[#]_. VisualSearch is based on `Backbone
+<http://documentcloud.github.com/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``
+:js:func:`openerp.web.search.Input.facet_for_defaults` with the
-mapping of key:values (where each key corresponds to an input).
+``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
+The default implementation is to check if there is a default value for
-current input's name (via :js:attr:`openerp.web.search.Input.attrs.name`) and
+the current input's name (via
-if there is to convert this value to a :js:class:`VS.models.SearchFacet` by
+:js:attr:`openerp.web.search.Input.attrs.name`) and if there is to
-calling :js:func:`openerp.web.search.Input.facet_for`.
+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<Null|VS.model.SearchFacet>``.
+Both methods should return a
+``jQuery.Deferred<Null|VS.model.SearchFacet>``.
 
 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
+An important component of the unified search view is the faceted
-pane. In order to provide good user and developer experiences, this pane is
+autocompletion pane. In order to provide good user and developer
-pluggable (value-wise): each and every control of the search view can check for
+experiences, this pane is pluggable (value-wise): each and every
-(and provide) categorized auto-completions for a given value being typed by
+control of the search view can check for (and provide) categorized
-the user.
+auto-completions for a given value being typed by the user.
 
-This is done by implementing :js:func:`openerp.web.search.Input.complete`: the
+This is done by implementing
-method is provided with a value to complete, and the input must either return
+:js:func:`openerp.web.search.Input.complete`: the method is provided
-a ``jQuery.Deferred<Null>`` or fetch (by returning a ``jQuery.Deferred``) an
+with a value to complete, and the input must either return a
-array of completion values.
+``jQuery.Deferred<Null>`` 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
+The displaying of the search view was significantly altered from
-6.1 to OpenERP Web 6.2: it went form a form-like appearance (inherited from
+OpenERP Web 6.1 to OpenERP Web 6.2.
-previous web client versions and ultimately from the GTK client) to a
-"universal" search input with facets.
 
-As a result, while the external API used to interact with the search view does
+As a result, while the external API used to interact with the search
-not change the internal details — including the interaction between the search
+view does not change the internal details — including the interaction
-view and its widgets — is significantly altered:
+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
+* Because the autocompletion service is now provided by the search
-  itself, :js:func:`openerp.web.search.ManyToOneField.setup_autocomplete` has
+  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