# HG changeset patch
# User Sandrine Ribeau <sandrine.ribeau@logilab.fr>
# Date 1230667245 28800
# Node ID 99943acb44af0ec988d18505502937fef35f6478
# Parent  210f99896a5bc31820a51eeb0360228039b98cf0
[doc] Add sub-section about selectors and a little about registerer in views chapter.

diff -r 210f99896a5b -r 99943acb44af doc/book/en/B1020-define-views.en.txt
--- a/doc/book/en/B1020-define-views.en.txt	Tue Dec 30 14:48:30 2008 +0100
+++ b/doc/book/en/B1020-define-views.en.txt	Tue Dec 30 12:00:45 2008 -0800
@@ -11,7 +11,7 @@
 
 We'll start with a description of the interface providing you with a basic
 understanding of the classes and methods available, then detail the view
-selection principle we makes is makes `CubicWeb` web interface very flexible.
+selection principle which makes `CubicWeb` web interface very flexible.
 
 Basic class for views
 ---------------------
@@ -77,28 +77,45 @@
 The selection view principle
 ----------------------------
 
-A view includes :
+A view is essentially defined by:
 
 - an identifier (all objects in `CubicWeb` are entered in a registry
   and this identifier will be used as a key). This is defined in the class
   attribute ``id``.
   
 - a filter to select the resulsets it can be applied to. This is defined in
-  the class attribute ``__selectors__``
+  the class attribute ``__selectors__``, which expects a tuple of selectors
+  as its value.
 
 
 For a given identifier, multiple views can be defined. `CubicWeb` uses
 a selector which computes scores so that it can identify and select the
-best view to apply in context. The selector library is in 
+best view to apply in context. The selectors library is in 
 ``cubicweb.common.selector`` and a library of the methods used to
 compute scores is in ``cubicweb.vregistry.vreq``.
 
+.. include:: B1021-views-selectors.en.txt
+
+Registerer
+``````````
+A view is also customizable through its attribute ``__registerer__``.
+This is used at the time the application is launched to manage how
+objects (views, graphic components, actions, etc.) 
+are registered in the `cubicWeb` registry.
+
+A `registerer` can, for example, identify when we register an 
+object that is equivalent to an already registered object, which
+could happen when we define two `primary` views for an entity type.
+
+The purpose of a `registerer` is to control objects registry
+at the application startup whereas `selectors` controls objects
+when they are selected for display.
+
 
 `CubicWeb` provides a lot of standard views for the default class
 `EntityType`. You can find them in ``cubicweb/web/views/``.
 
-.. include:: B1021-views-stdlib.en.txt
-
+.. include:: B1022-views-stdlib.en.txt
 
 Example of a view customization
 -------------------------------
diff -r 210f99896a5b -r 99943acb44af doc/book/en/B1021-views-selectors.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B1021-views-selectors.en.txt	Tue Dec 30 12:00:45 2008 -0800
@@ -0,0 +1,54 @@
+.. -*- coding: utf-8 -*-
+
+Selectors
+`````````
+
+A selector is responsible to score how well an object may be used with a
+given result set during publishing time selection. This enables the selection
+of the most appropriate views to a given result set.
+
+A selector is a method that computes a score. This score is used by
+`CubicWeb` engine to identify which view is the best to apply in the
+context. In the case, no score is higher than the others, then an
+exception is raised ``NoSelectableObject`` to let you know that the
+engine was not able to identify the view to apply. In such case
+you would need to review your design and make sure your views are
+properly defined.
+
+`CubicWeb` provides its own set of selectors that you can use and here
+is a description of some of the most common used:
+
+*yes_selector*
+    This selector accepts everything which basically means to any result
+    set.
+
+*norset_selector*
+    This selector accepts no result set, so it can be applied to any
+    object.
+
+*rset_selector*
+    This selector accepts result set, whatever the number of objects
+    in the result set.
+
+*anyrset_selector*
+    This selector accepts any non empty result set.
+
+*emptyrset_selector*
+    This selector accepts empty result set.
+
+*onelinerset_selector*
+    This selector accepts result set with a single line of result.
+
+*twolinerset_selector*
+    This selector accepts result set with *at least* two lines of result.
+
+*anonymous_selector*
+    This selector accepts if user is anonymous.
+
+*not_anonymous_selector*
+    This selector accepta if user is authenticated.
+
+
+Of course you can write your own set of selectors as you get familiar with the
+framework.
+
diff -r 210f99896a5b -r 99943acb44af doc/book/en/B1021-views-stdlib.en.txt
--- a/doc/book/en/B1021-views-stdlib.en.txt	Tue Dec 30 14:48:30 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,89 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Predefined views in the library
--------------------------------
-
-A certain number of views are used to build the web interface, which apply
-to one or more entities. Their identifier is what distinguish them from
-each others and the main ones are:
-
-*primary*
-    Primary view of an entity, this is the view called by default when a single
-    non final entity is in the result set and needs to be displayed. 
-    This view is supposed to render a maximum of informations about the entity.
-
-*text*
-    This is the simplest text view for an entity. It displays the 
-    title of an entity. It should not contain HTML.
-
-*oneline*
-    This is a hyper linked *text* view. Similar to the `secondary` view, 
-    but called when we want the view to stand on a single line, or just 
-    get a brief view. By default this view uses the
-    parameter `MAX_LINE_CHAR` to control the result size.
-
-*secondary*
-    This is a combinaison of an icon and a *oneline* view.
-    By default it renders the two first attributes of the entity as a 
-    clickable link redirecting to the primary view.
-
-*incontext, outofcontext*
-    Similar to the `secondary` view, but called when an entity is considered
-    as in or out of context. By default it respectively returns the result of 
-    `textincontext` and `textoutofcontext` wrapped in a link leading to 
-    the primary view of the entity.
-
-*textincontext, textoutofcontext*
-    Similar to the `text` view, but called when an entity is considered out or
-    in context. By default it returns respectively the result of the 
-    methods `.dc_title` and `.dc_long_title` of the entity.
-
-*list*
-    This view displays a list of entities by creating a HTML list (`<ul>`) 
-    and call the view `listitem` for each entity of the result set.
-
-*listitem*
-    This view redirects by default to the `outofcontext` view.
-
-*rss*
-    Creates a RSS/XML view and call the view `rssitem` for each entity of
-    the result set.
-
-*rssitem*
-    Create a RSS/XML view for each entity based on the results of the dublin core
-    methods of the entity (`dc_*`)
-
-*sidebox*
-  This view displays usually a side box of some related entities 
-  in a primary view.
-
-Start view:
-
-*index*
-    This view defines the home page of your application. It does not require
-    a result set to apply to.
-
-*schema*
-    A view dedicated to the display of the schema of the application
-
-Special views:
-
-*noresult*
-    This view is the default view used when no result has been found
-    (e.g. empty result set).
-
-*final*
-    Display the value of a cell without trasnformation (in case of a non final
-    entity, we see the eid). Applicable on any result set.
-
-*table*
-    Creates a HTML table (`<table>`) and call the view `cell` for each cell of
-    the result set. Applicable on any result set.
-
-*cell*
-    By default redirects to the `final` view if this is a final entity or
-    `outofcontext` view otherwise
-
-*null*
-    This view is the default view used when nothing needs to be rendered.
-    It is always applicable and it does not return anything
diff -r 210f99896a5b -r 99943acb44af doc/book/en/B1022-views-stdlib.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B1022-views-stdlib.en.txt	Tue Dec 30 12:00:45 2008 -0800
@@ -0,0 +1,88 @@
+.. -*- coding: utf-8 -*-
+
+Predefined views in the library
+```````````````````````````````
+A certain number of views are used to build the web interface, which apply
+to one or more entities. Their identifier is what distinguish them from
+each others and the main ones are:
+
+*primary*
+    Primary view of an entity, this is the view called by default when a single
+    non final entity is in the result set and needs to be displayed. 
+    This view is supposed to render a maximum of informations about the entity.
+
+*text*
+    This is the simplest text view for an entity. It displays the 
+    title of an entity. It should not contain HTML.
+
+*oneline*
+    This is a hyper linked *text* view. Similar to the `secondary` view, 
+    but called when we want the view to stand on a single line, or just 
+    get a brief view. By default this view uses the
+    parameter `MAX_LINE_CHAR` to control the result size.
+
+*secondary*
+    This is a combinaison of an icon and a *oneline* view.
+    By default it renders the two first attributes of the entity as a 
+    clickable link redirecting to the primary view.
+
+*incontext, outofcontext*
+    Similar to the `secondary` view, but called when an entity is considered
+    as in or out of context. By default it respectively returns the result of 
+    `textincontext` and `textoutofcontext` wrapped in a link leading to 
+    the primary view of the entity.
+
+*textincontext, textoutofcontext*
+    Similar to the `text` view, but called when an entity is considered out or
+    in context. By default it returns respectively the result of the 
+    methods `.dc_title` and `.dc_long_title` of the entity.
+
+*list*
+    This view displays a list of entities by creating a HTML list (`<ul>`) 
+    and call the view `listitem` for each entity of the result set.
+
+*listitem*
+    This view redirects by default to the `outofcontext` view.
+
+*rss*
+    Creates a RSS/XML view and call the view `rssitem` for each entity of
+    the result set.
+
+*rssitem*
+    Create a RSS/XML view for each entity based on the results of the dublin core
+    methods of the entity (`dc_*`)
+
+*sidebox*
+  This view displays usually a side box of some related entities 
+  in a primary view.
+
+Start view:
+
+*index*
+    This view defines the home page of your application. It does not require
+    a result set to apply to.
+
+*schema*
+    A view dedicated to the display of the schema of the application
+
+Special views:
+
+*noresult*
+    This view is the default view used when no result has been found
+    (e.g. empty result set).
+
+*final*
+    Display the value of a cell without trasnformation (in case of a non final
+    entity, we see the eid). Applicable on any result set.
+
+*table*
+    Creates a HTML table (`<table>`) and call the view `cell` for each cell of
+    the result set. Applicable on any result set.
+
+*cell*
+    By default redirects to the `final` view if this is a final entity or
+    `outofcontext` view otherwise
+
+*null*
+    This view is the default view used when nothing needs to be rendered.
+    It is always applicable and it does not return anything