OpenERP Web's new design.
The internal structure of the faceted search is inspired by
-`VisualSearch <http://documentcloud.github.com/visualsearch/>`_ [#]_.
+`VisualSearch <http://documentcloud.github.com/visualsearch/>`_
+[#previous]_.
As does VisualSearch, the new search view is based on `Backbone`_ and
makes significant use of Backbone's models and collections (OpenERP
:js:func:`openerp.web.search.Input.facet_for` with that value.
There is no default implementation of
-:js:func:`openerp.web.search.Input.facet_for` [#]_, but
+:js:func:`openerp.web.search.Input.facet_for` [#no_impl]_, but
:js:class:`openerp.web.search.Field` provides one, which uses the
value as-is to fetch a :js:class:`~openerp.web.search.Facet`.
method.
This method should take a single argument (the string being typed by
-the user) and should fetch an ``Array`` of possible completions [#]_.
+the user) and should fetch an ``Array`` of possible completions
+[#completion]_.
A default implementation is provided which fetches nothing.
.. js:attribute:: field
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.
+ originally created the facet [#facet-field]_, used to delegate
+ some operations (such as serializing the facet's values to
+ domains and contexts). This is a backbone model attribute.
.. js:attribute:: values
it serializes to and deserializes from javascript arrays (via
``Collection#toJSON`` and ``Collection#reset``).
+ .. js:attribute:: [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.
+
.. js:class:: openerp.web.search.FacetValues
`Backbone collection`_ of
the other hand, the OpenERP Web 7 search view's state is modelled
after a collection of :js:class:`~openerp.web.search.Facet`, and each
field of a search view may have special requirements when it comes to
-the domains it produces [#]_.
+the domains it produces [#special]_.
So there needs to be some way of mapping
:js:class:`~openerp.web.search.Facet` objects to OpenERP search data.
or ``@filter_domain``. ``"="`` for
:js:class:`~openerp.web.search.Field`
-Converting to facet objects
----------------------------
+Arbitrary data storage
+++++++++++++++++++++++
+
+:js:class:`~openerp.web.search.Facet` and
+:js:class:`~openerp.web.search.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
-------
Advanced Search
+++++++++++++++
-The advanced search is now a more standard
-:js:class:`~openerp.web.search.Input` configured to be rendered in the
-drawer.
-
-.. [#] the original view was implemented on top of a monkey-patched
- VisualSearch, but as our needs diverged from VisualSearch's goal this
- made less and less sense ultimately leading to a clean-room
- reimplementation
-
-.. [#] In case you are extending the search view with a brand new type
- of input
-
-.. [#] Ideally this array should not hold more than about 10 items,
- but the search view does not put any constraint on this at the
- moment. Note that this may change.
-
-.. [#] search view fields may also bundle context data to add to the
- search context
+* The advanced search is now a more standard
+ :js:class:`~openerp.web.search.Input` configured to be rendered in
+ the drawer.
+
+* :js:class:`~openerp.web.search.ExtendedSearchProposition.Field` are
+ now standard widgets, with the "right" behaviors (they don't rebind
+ their ``$element`` in ``start()``)
+
+* The ad-hoc optional setting of the openerp field descriptor on a
+ :js:class:`~openerp.web.search.ExtendedSearchProposition.Field` has
+ been removed, the field descriptor is now passed as second argument
+ to the
+ :js:class:`~openerp.web.search.ExtendedSearchProposition.Field`'s
+ constructor, and bound to its
+ :js:attr:`~openerp.web.search.ExtendedSearchProposition.Field.field`.
+
+* Instead of its former domain triplet ``(field, operator, value)``,
+ :js:func:`~openerp.web.search.ExtendedSearchProposition.get_proposition`
+ now returns an object with two fields ``label`` and ``value``,
+ respectively a human-readable version of the proposition and the
+ corresponding domain triplet for the proposition.
+
+.. [#previous]
+
+ the original view was implemented on top of a monkey-patched
+ VisualSearch, but as our needs diverged from VisualSearch's goal
+ this made less and less sense ultimately leading to a clean-room
+ reimplementation
+
+.. [#no_impl]
+
+ In case you are extending the search view with a brand new type of
+ input
+
+.. [#completion]
+
+ Ideally this array should not hold more than about 10 items, but
+ the search view does not put any constraint on this at the
+ moment. Note that this may change.
+
+.. [#facet-field]
+
+ ``field`` does not actually need to be an instance of
+ :js:class:`~openerp.web.search.Input`, nor does it need to be what
+ created the facet, it just needs to provide the three
+ facet-serialization methods
+ :js:func:`~openerp.web.search.Input.get_domain`,
+ :js:func:`~openerp.web.search.Input.get_context` and
+ :js:func:`~openerp.web.search.Input.get_gropuby`, existing
+ :js:class:`~openerp.web.search.Input` subtypes merely provide
+ convenient base implementation for those methods.
+
+ Complex search view inputs (especially those living in the drawer)
+ may prefer using object literals with the right slots returning
+ closed-over values or some other scheme un-bound to an actual
+ :js:class:`~openerp.web.search.Input`, as
+ :js:class:`~openerp.web.search.CustomFilters` and
+ :js:class:`~openerp.web.search.Advanced` do.
+
+.. [#special]
+
+ search view fields may also bundle context data to add to the
+ search context
.. _Backbone:
http://documentcloud.github.com/backbone/