[REM] older searchview doc (deprecated/replaced)
bzr revid: xmo@openerp.com-20120425122056-bdvsfjbtc7bmhsuw
This commit is contained in:
Xavier Morel
parent
6754110eb7
commit
611adc838f
|
|
@ -16,13 +16,12 @@ multiple fields). The goal for this change is twofold:
|
||||||
The internal structure of the faceted search is inspired by
|
The internal structure of the faceted search is inspired by
|
||||||
`VisualSearch <http://documentcloud.github.com/visualsearch/>`_ [#]_.
|
`VisualSearch <http://documentcloud.github.com/visualsearch/>`_ [#]_.
|
||||||
|
|
||||||
As does VisualSearch, the new search view is based on `Backbone
|
As does VisualSearch, the new search view is based on `Backbone`_ and
|
||||||
<http://documentcloud.github.com/backbone/>`_ and makes significant
|
makes significant use of Backbone's models and collections (OpenERP
|
||||||
use of Backbone's models and collections (OpenERP Web's widgets make a
|
Web's widgets make a good replacement for Backbone's own views). As a
|
||||||
good replacement for Backbone's own views). As a result, understanding
|
result, understanding the implementation details of the OpenERP Web 7
|
||||||
the implementation details of the OpenERP Web 7 search view also
|
search view also requires a basic understanding of Backbone's models,
|
||||||
requires a basic understanding of Backbone's models, collections and
|
collections and events.
|
||||||
events.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
|
@ -45,7 +44,7 @@ objects is stored in the ``openerp.web.search.fields``
|
||||||
:js:class:`~openerp.web.Registry` where new field types and widgets
|
:js:class:`~openerp.web.Registry` where new field types and widgets
|
||||||
can be added.
|
can be added.
|
||||||
|
|
||||||
Search view inputs have three main roles:
|
Search view inputs have four main roles:
|
||||||
|
|
||||||
Loading defaults
|
Loading defaults
|
||||||
++++++++++++++++
|
++++++++++++++++
|
||||||
|
|
@ -81,7 +80,9 @@ the user) and should fetch an ``Array`` of possible completions [#]_.
|
||||||
|
|
||||||
A default implementation is provided which fetches nothing.
|
A default implementation is provided which fetches nothing.
|
||||||
|
|
||||||
A completion item is an object literal with two keys:
|
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``
|
``label``
|
||||||
|
|
||||||
|
|
@ -136,168 +137,105 @@ only once.
|
||||||
dynamically collects, lays out and renders filters? =>
|
dynamically collects, lays out and renders filters? =>
|
||||||
exercises drawer thingies
|
exercises drawer thingies
|
||||||
|
|
||||||
Interaction between the Search View and VisualSearch
|
Programmatic interactions: internal model
|
||||||
----------------------------------------------------
|
-----------------------------------------
|
||||||
|
|
||||||
The core data abstraction in VisualSearch is
|
This new searchview is built around an instance of
|
||||||
:js:class:`VS.model.SearchQuery`, a backbone Collection holding
|
:js:class:`~openerp.web.search.SearchQuery` available as
|
||||||
instances of the :js:class:`VS.model.SearchFacet` backbone Model.
|
:js:attr:`openerp.web.SearchView.query`.
|
||||||
|
|
||||||
Backbone models can hold any number of informal properties interacted
|
The query is a `backbone collection`_ of
|
||||||
with through the :js:func:`~Backbone.Model.get` and
|
:js:class:`~openerp.web.search.Facet` objects, which can be interacted
|
||||||
:js:func:`~Backbone.Model.set` methods. VisualSearch reserves three
|
with directly by external objects or search view controls
|
||||||
such properties for its behavior, these properties *must* be correctly
|
(e.g. widgets displayed in the drawer).
|
||||||
set on all search facets created programmatically:
|
|
||||||
|
|
||||||
``app``
|
.. js:class:: openerp.web.search.SearchQuery
|
||||||
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 current search query of the search view, provides convenience
|
||||||
the *name* of the facet, displayed in the first section of a facet
|
behaviors for manipulating :js:class:`~openerp.web.search.Facet`
|
||||||
view.
|
on top of the usual `backbone collection`_ methods.
|
||||||
|
|
||||||
``value``
|
The query ensures all of its facets contain at least one
|
||||||
the *displayed value* of the facet, it is directly printed to the
|
:js:class:`~openerp.web.search.FacetValue` instance. Otherwise,
|
||||||
right of the category.
|
the facet is automatically removed from the query.
|
||||||
|
|
||||||
The search view uses additional keys to store state and data it needs
|
.. js:function:: openerp.web.search.SearchQuery.add(values, options)
|
||||||
to associate with facet objects:
|
|
||||||
|
|
||||||
``field``
|
Overridden from the base ``add`` method so that adding a facet
|
||||||
the search field instance which created the facet, used when the
|
which is *already* in the collection will merge the value of
|
||||||
search view needs to serialize the facets.
|
the new facet into the old one rather than add a second facet
|
||||||
|
with different values.
|
||||||
|
|
||||||
``json``
|
:param values: facet, facet attributes or array thereof
|
||||||
the "logical" value of the facet, can be absent if the logical and
|
:returns: the collection itself
|
||||||
"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 (the
|
.. js:function:: openerp.web.search.SearchQuery.toggle(value, options)
|
||||||
name stands for json-compatible value, it is not a JSON-encoded
|
|
||||||
string).
|
|
||||||
|
|
||||||
.. note::
|
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.
|
||||||
|
|
||||||
in order to simplify getting the logical value of a search facet
|
A toggling is atomic: only one change event will be triggered
|
||||||
model, :js:class:`VS.model.SearchFacet` has been extended with a
|
on the facet regardless of the number of values added to or
|
||||||
:js:func:`~VS.model.SearchFacet.value` method
|
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.
|
||||||
|
|
||||||
Extensions and patches to VisualSearch
|
:param value: facet or facet attributes
|
||||||
++++++++++++++++++++++++++++++++++++++
|
:returns: the collection
|
||||||
|
|
||||||
.. js:function:: VS.model.SearchFacet.value()
|
.. js:class:: openerp.web.search.Facet
|
||||||
|
|
||||||
Bundles the logic of selecting between ``json`` and ``value`` in
|
A `backbone model`_ representing a single facet of the current
|
||||||
order to get the logical value of a facet.
|
research. May map to a search field, or to a more complex or
|
||||||
|
fuzzier input (e.g. a custom filter or an advanced search).
|
||||||
|
|
||||||
.. js:attribute:: VS.options.callbacks.make_facet
|
.. js:attribute:: category
|
||||||
|
|
||||||
Called by :js:class:`VS.ui.SearchBox` when it needs to create a
|
The displayed name of the facet, as a ``String``. This is a
|
||||||
new search facet *view*. By default this is not supported by
|
backbone model attribute.
|
||||||
VisualSearch, and requires monkey-patching
|
|
||||||
:js:func:`VS.ui.SearchBox.renderFacet`.
|
|
||||||
|
|
||||||
This patch should not alter any behavior if
|
.. js:attribute:: field
|
||||||
:js:attr:`~VS.options.callbacks.make_facet` is not used.
|
|
||||||
|
|
||||||
.. js:attribute:: VS.options.callbacks.make_input
|
The :js:class:`~openerp.web.search.Input` instance which
|
||||||
|
originally created the facet, used to delegate some operations
|
||||||
|
(such as serializing the facet's values to domains and
|
||||||
|
contexts). This is a backbone model attribute.
|
||||||
|
|
||||||
Similar to :js:attr:`~VS.options.callbacks.make_facet`, but called
|
.. js:attribute:: values
|
||||||
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
|
:js:class:`~openerp.web.search.FacetValues` as a javascript
|
||||||
get rid of its serialize/load round-tripping of facet data: the
|
attribute, stores all the values for the facet and helps
|
||||||
additional attributes needed by the search view don't round-trip (at
|
propagate their events to the facet. Is also available as a
|
||||||
all) so VisualSearch must not load any data from its (fairly
|
backbone attribute (via ``#get`` and ``#set``) in which cases
|
||||||
simplistic) text-serialization format.
|
it serializes to and deserializes from javascript arrays (via
|
||||||
|
``Collection#toJSON`` and ``Collection#reset``).
|
||||||
|
|
||||||
.. note::
|
.. js:class:: openerp.web.search.FacetValues
|
||||||
|
|
||||||
a second issue is that — as of `commit 3fca87101d`_ — VisualSearch
|
`Backbone collection`_ of
|
||||||
correctly serializes facet categories containing spaces but is
|
:js:class:`~openerp.web.search.FacetValue` instances.
|
||||||
unable to load them back in. It also does not handle facets with
|
|
||||||
*empty* categories correctly.
|
|
||||||
|
|
||||||
Loading Defaults
|
.. js:class:: openerp.web.search.FacetValue
|
||||||
----------------
|
|
||||||
|
|
||||||
After loading the view data, the SearchView will call
|
`Backbone model`_ representing a single value within a facet,
|
||||||
:js:func:`openerp.web.search.Input.facet_for_defaults` on each of its
|
represents a pair of (displayed name, logical value).
|
||||||
inputs with the ``defaults`` mapping of key:values (where each key
|
|
||||||
corresponds to an input). This method should look into the
|
|
||||||
``defaults`` mapping and fetch the field's default value as a
|
|
||||||
:js:class:`~VS.models.SearchFacet` if applicable.
|
|
||||||
|
|
||||||
The default implementation is to check if there is a default value for
|
.. js:attribute:: label
|
||||||
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`.
|
|
||||||
|
|
||||||
There is no built-in (default) implementation of
|
Backbone model attribute storing the "displayable"
|
||||||
:js:func:`openerp.web.search.Input.facet_for`. This method should
|
representation of the value, visually output to the
|
||||||
fetch the :js:class:`~VS.models.SearchFacet` corresponding to the
|
user. Must be a string.
|
||||||
"raw" value passed as argument.
|
|
||||||
|
|
||||||
Providing auto-completion
|
.. js:attribute:: value
|
||||||
-------------------------
|
|
||||||
|
|
||||||
An important component of the unified search view is the faceted
|
Backbone model attribute storing the logical/internal value
|
||||||
autocompletion pane. In order to provide good user and developer
|
(of itself), will be used by
|
||||||
experiences, this pane is pluggable (value-wise): each and every
|
:js:class:`~openerp.web.search.Input` to serialize to domains
|
||||||
control of the search view can check for (and provide) categorized
|
and contexts.
|
||||||
auto-completions for a given value being typed by the user.
|
|
||||||
|
|
||||||
This is done by implementing
|
Can be of any type.
|
||||||
:js:func:`openerp.web.search.Input.complete`: the method is provided
|
|
||||||
with a value to complete, and should fetch an ``Array`` of completion
|
|
||||||
values. These completion values will then be provided to the global
|
|
||||||
autocompletion list, implemented via `jquery-ui autocomplete
|
|
||||||
<http://jqueryui.com/demos/autocomplete/>`_.
|
|
||||||
|
|
||||||
Because the search view uses a custom renderer for its completion, it
|
|
||||||
was possible to fix some incompatibilities between the attributes of
|
|
||||||
completion items and VisualSearch's facet model:
|
|
||||||
|
|
||||||
Actual completion items
|
|
||||||
+++++++++++++++++++++++
|
|
||||||
|
|
||||||
These are selectable items, and upon selection are turned into actual
|
|
||||||
search facet objects. They should have all the properties of a search
|
|
||||||
facet (as described above) and can have one more optional property:
|
|
||||||
``label``.
|
|
||||||
|
|
||||||
When rendering an item in the list, the renderer will first try to use
|
|
||||||
the ``label`` property if it exists (``label`` can contain HTML and
|
|
||||||
will be inserted as-is, so it can bold or emphasize some of its
|
|
||||||
elements), if it does not the ``value`` property will be used.
|
|
||||||
|
|
||||||
.. note:: the ``app`` key should not be specified on completion item,
|
|
||||||
it will be set automatically when the search view creates
|
|
||||||
the facet from the item.
|
|
||||||
|
|
||||||
Section titles
|
|
||||||
++++++++++++++
|
|
||||||
|
|
||||||
A second kind of completion values is the section titles. Section
|
|
||||||
titles are similar to completion items but only have a ``category``
|
|
||||||
property. They will be rendered in a different style and can not be
|
|
||||||
selected in the auto-completion (they will be skipped).
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Technically, section title items can have any property they want
|
|
||||||
*as long as they do not have a value property*. A ``value``
|
|
||||||
property set to ``false``, ``null`` or ``undefined`` is **not**
|
|
||||||
equivalent to not having a ``value`` property.
|
|
||||||
|
|
||||||
If an input *may* fetch more than one completion item, it *should*
|
|
||||||
prepend a section title (using its own name) to the completion items.
|
|
||||||
|
|
||||||
Converting from facet objects
|
Converting from facet objects
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
@ -327,7 +265,7 @@ Converting to facet objects
|
||||||
Changes
|
Changes
|
||||||
-------
|
-------
|
||||||
|
|
||||||
.. todo:: merge in changelog instead
|
.. todo:: merge in changelog instead?
|
||||||
|
|
||||||
The displaying of the search view was significantly altered from
|
The displaying of the search view was significantly altered from
|
||||||
OpenERP Web 6.1 to OpenERP Web 7.
|
OpenERP Web 6.1 to OpenERP Web 7.
|
||||||
|
|
@ -422,5 +360,15 @@ Many To One
|
||||||
.. [#] search view fields may also bundle context data to add to the
|
.. [#] search view fields may also bundle context data to add to the
|
||||||
search context
|
search context
|
||||||
|
|
||||||
|
.. _Backbone:
|
||||||
|
http://documentcloud.github.com/backbone/
|
||||||
|
|
||||||
|
.. _Backbone.Collection:
|
||||||
|
.. _Backbone collection:
|
||||||
|
http://documentcloud.github.com/backbone/#Collection
|
||||||
|
|
||||||
|
.. _Backbone model:
|
||||||
|
http://documentcloud.github.com/backbone/#Model
|
||||||
|
|
||||||
.. _commit 3fca87101d:
|
.. _commit 3fca87101d:
|
||||||
https://github.com/documentcloud/visualsearch/commit/3fca87101d
|
https://github.com/documentcloud/visualsearch/commit/3fca87101d
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue