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.
``Array`` of groupby domains rather than a single context. At this
point, it is only implemented on (and used by) filters.
-Converting to facet objects
----------------------------
+Field services
+++++++++++++++
+
+:js:class:`~openerp.web.search.Field` provides a default
+implementation of :js:func:`~openerp.web.search.Input.get_domain` and
+:js:func:`~openerp.web.search.Input.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
+:js:func:`~openerp.web.search.Input.get_domain` or
+:js:func:`~openerp.web.search.Input.get_context`:
+
+.. js:function:: openerp.web.search.Field.get_context(facet)
+
+ If the field has no ``@context``, simply returns
+ ``null``. Otherwise, calls
+ :js:func:`~openerp.web.search.Field.value_from` once for each
+ :js:class:`~openerp.web.search.FacetValue` of the current
+ :js:class:`~openerp.web.search.Facet` (in order to extract the
+ basic javascript object from the
+ :js:class:`~openerp.web.search.FacetValue` then evaluates
+ ``@context`` with each of these values set as ``self``, and
+ returns the union of all these contexts.
+
+ :param facet:
+ :type facet: openerp.web.search.Facet
+ :returns: a context (literal or compound)
+
+.. js:function:: openerp.web.search.Field.get_domain(facet)
+
+ If the field has no ``@filter_domain``, calls
+ :js:func:`~openerp.web.search.Field.make_domain` once with each
+ :js:class:`~openerp.web.search.FacetValue` of the current
+ :js:class:`~openerp.web.search.Facet` as well as the field's
+ ``@name`` and either its ``@operator`` or
+ :js:attr:`~openerp.web.search.Field.default_operator`.
+
+ If the field has an ``@filter_value``, calls
+ :js:func:`~openerp.web.search.Field.value_from` once per
+ :js:class:`~openerp.web.search.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
+ :js:class:`~openerp.web.search.FacetValue` and returns the union
+ of the result.
+
+ :param facet:
+ :type facet: openerp.web.search.Facet
+ :returns: a domain (literal or compound)
+
+.. js:function:: openerp.web.search.Field.make_domain(name, operator, facetValue)
+
+ Builds a literal domain from the provided data. Calls
+ :js:func:`~openerp.web.search.Field.value_from` on the
+ :js:class:`~openerp.web.search.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.
+
+ :param String name: the field's name
+ :param String operator: the operator to use in the field's domain
+ :param facetValue:
+ :type facetValue: openerp.web.search.FacetValue
+ :returns: Array<(String, String, Object)>
+
+.. js:function:: openerp.web.search.Field.value_from(facetValue)
+
+ Extracts a "bare" javascript value from the provided
+ :js:class:`~openerp.web.search.FacetValue`, and returns it.
+
+ The default implementation will simply return the ``value``
+ backbone property of the argument.
+
+ :param facetValue:
+ :type facetValue: openerp.web.search.FacetValue
+ :returns: Object
+
+.. js:attribute:: openerp.web.search.Field.default_operator
+
+ Operator used to build a domain when a field has no ``@operator``
+ or ``@filter_domain``. ``"="`` for
+ :js:class:`~openerp.web.search.Field`
+
+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
-------
* :js:func:`~openerp.web.search.Input.get_domain` and
:js:func:`~openerp.web.search.Input.get_context` now take a
- :js:class:`~VS.model.SearchFacet` as parameter, from which it's
+ :js:class:`~openerp.web.search.Facet` as parameter, from which it's
their job to get whatever value they want
* :js:func:`~openerp.web.search.Input.get_groupby` has been added. It returns
Fields
++++++
-* ``get_value`` now takes a :js:class:`~VS.model.SearchFacet` (instead
- of taking no argument).
-
- A default implementation is provided as
- :js:func:`openerp.web.search.Field.get_value` and simply calls
- :js:func:`VS.model.SearchFacet.value`.
+* ``get_value`` has been replaced by
+ :js:func:`~openerp.web.search.Field.value_from` as it now takes a
+ :js:class:`~openerp.web.search.FacetValue` argument (instead of no
+ argument). It provides a default implementation returning the
+ ``value`` property of its argument.
* The third argument to
- :js:func:`~openerp.web.search.Field.make_domain` is now the
- :js:class:`~VS.model.SearchFacet` received by
- :js:func:`~openerp.web.search.Field.get_domain`, so child classes
- have all the information they need to derive the "right" resulting
- domain.
+ :js:func:`~openerp.web.search.Field.make_domain` is now a
+ :js:class:`~openerp.web.search.FacetValue` so child classes have all
+ the information they need to derive the "right" resulting domain.
Custom filters
++++++++++++++
:js:func:`openerp.web.search.ManyToOneField.setup_autocomplete` has
been removed.
-.. [#] 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
+Advanced Search
++++++++++++++++
+
+* 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.
-.. [#] In case you are extending the search view with a brand new type
- of input
+ 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.
-.. [#] 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.
+.. [#special]
-.. [#] search view fields may also bundle context data to add to the
- search context
+ search view fields may also bundle context data to add to the
+ search context
.. _Backbone:
http://documentcloud.github.com/backbone/
projects / odoo / odoo.git / blobdiff