From 3ecf0e1ae19f9b86251bd0f20154df6a1ad3d2f7 Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Fri, 11 May 2012 15:16:13 +0200 Subject: [PATCH] [IMP] doc for facet's field property bzr revid: xmo@openerp.com-20120511131613-zbqye92sex1ius6x --- doc/search-view.rst | 65 ++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/doc/search-view.rst b/doc/search-view.rst index 2acaea3c8ad..66ad38d7d91 100644 --- a/doc/search-view.rst +++ b/doc/search-view.rst @@ -14,7 +14,8 @@ multiple fields). The goal for this change is twofold: OpenERP Web's new design. The internal structure of the faceted search is inspired by -`VisualSearch `_ [#]_. +`VisualSearch `_ +[#previous]_. As does VisualSearch, the new search view is based on `Backbone`_ and makes significant use of Backbone's models and collections (OpenERP @@ -63,7 +64,7 @@ contains a non-falsy value for the field's ``@name`` and calls :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`. @@ -76,7 +77,8 @@ inputs through the :js:func:`~openerp.web.search.Input.complete` 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. @@ -205,9 +207,9 @@ with directly by external objects or search view controls .. 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 @@ -262,7 +264,7 @@ OpenERP this is done via :ref:`domains `. On 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. @@ -464,20 +466,47 @@ 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 +.. [#previous] -.. [#] In case you are extending the search view with a brand new type - of input + 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 -.. [#] 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. +.. [#no_impl] -.. [#] search view fields may also bundle context data to add to the - search context + 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/