# HG changeset patch
# User Sylvain Thénault <sylvain.thenault@logilab.fr>
# Date 1285157004 -7200
# Node ID 1aad5389c013b1c75da3304eb60e914d437dfd1d
# Parent  ca5d09ff0379845ca40925eed5039c9a374dc3db
[book] backport documentation about primary/base views sent on the list

diff -r ca5d09ff0379 -r 1aad5389c013 doc/book/en/devweb/views/baseviews.rst
--- a/doc/book/en/devweb/views/baseviews.rst	Wed Sep 22 13:33:17 2010 +0200
+++ b/doc/book/en/devweb/views/baseviews.rst	Wed Sep 22 14:03:24 2010 +0200
@@ -4,11 +4,12 @@
 ----------
 
 *CubicWeb* provides a lot of standard views, that can be found in
- :mod:`cubicweb.web.views` and :mod:`cubicweb.web.views.baseviews`.
+:mod:`cubicweb.web.views` sub-modules.
 
-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:
+A certain number of views are used to build the web interface, which apply to one
+or more entities. As other appobject, Their identifier is what distinguish them
+from each others. The most generic ones, found in
+:mod:`cubicweb.web.views.baseviews`, are described below.
 
 HTML views
 ~~~~~~~~~~
@@ -32,53 +33,105 @@
     This view is the default view used when nothing needs to be rendered.
     It is always applicable.
 
+
 Entity views
 ````````````
 
 *incontext, outofcontext*
-    Those are used to display a link to an entity, depending on the
-    entity having to be displayed in or out of context
-    (of another entity).  By default it respectively produces the
-    result of `textincontext` and `textoutofcontext` wrapped in a link
-    leading to the primary view of the entity.
+
+    Those are used to display a link to an entity, whose label depends on the
+    entity having to be displayed in or out of context (of another entity): some
+    entities make sense in the context of another entity. For instance, the
+    `Version` of a `Project` in forge. So one may expect that 'incontext' will
+    be called when display a version from within the context of a project, while
+    'outofcontext"' will be called in other cases. In our example, the
+    'incontext' view of the version would be something like '0.1.2', while the
+    'outofcontext' view would include the project name, e.g. 'baz 0.1.2' (since
+    only a version number without the associated project doesn't make sense if
+    you don't know yet that you're talking about the famous 'baz' project. |cubicweb|
+    tries to make guess and call 'incontext'/'outofcontext' nicely. When it can't
+    know, the 'oneline' view should be used.
+
+    By default it respectively produces the result of `textincontext` and
+    `textoutofcontext` wrapped in a link leading to the primary view of the
+    entity.
+
 
 *oneline*
+
     This view is used when we can't tell if the entity should be considered as
-    displayed in or out of context.  By default it produces the result of `text`
+    displayed in or out of context. By default it produces the result of `text`
     in a link leading to the primary view of the entity.
 
+
 List
 `````
 
 *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.
+
+    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. The 'list' view
+    will generate html like:
+
+    .. sourcecode:: html
+
+      <ul class="section">
+        <li>"result of 'subvid' view for a row</li>
+        ...
+      </ul>
+
 
-*listitem*
-    This view redirects by default to the `outofcontext` view.
+*simplelist*
+
+  This view is not 'ul' based, and rely on div behaviour to separate items. html
+  will look like
+
+    .. sourcecode:: html
+
+      <div class="section">"result of 'subvid' view for a row</div>
+      ...
+
+
+  It relies on base :class:`~cubicweb.view.View` class implementation of the
+  :meth:`call` method to insert those <div>.
+
 
 *sameetypelist*
-    This view displays a list of entities of the same type, in HTML section (`<div>`)
-    and call the view `sameetypelistitem` for each entity of the result set.
 
-*sameetypelistitem*
-    This view redirects by default to the `listitem` view.
+    This view displays a list of entities of the same type, in HTML section
+    (`<div>`) and call the view `sameetypelistitem` for each entity of the result
+    set. It's designed to get a more adapted global list when displayed entities
+    are all of the same type.
+
 
 *csv*
-    This view applies to entity groups, which are individually
-    displayed using the `incontext` view. It displays each entity as a
-    coma separated list. It is NOT related to the well-known text file
-    format.
+
+    This view displays each entity in a coma separated list. It is NOT related to
+    the well-known text file format.
+
+
+Those list view can be given a 'subvid' arguments, telling the view to use of
+each item in the list. When not specified, the value of the 'redirect_vid'
+attribute of :class:`ListItemView` (for 'listview') or of :class:`SimpleListView`
+will be used. This default to 'outofcontext' for 'list' / 'incontext' for
+'simplelist'
+
 
 Text entity views
 ~~~~~~~~~~~~~~~~~
 
+Basic html view have some variantsto be used when generating raw text, not html
+(for notifications for instance).
+
 *text*
+
     This is the simplest text view for an entity. By default it returns the
     result of the `.dc_title` method, which is cut to fit the
     `navigation.short-line-size` property if necessary.
 
 *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.
+
+    Similar to the `text` view, but called when an entity is considered out or in
+    context (see description of incontext/outofcontext html views for more
+    information on this). By default it returns respectively the result of the
+    methods `.dc_title()` and `.dc_long_title()` of the entity.
diff -r ca5d09ff0379 -r 1aad5389c013 doc/book/en/devweb/views/primary.rst
--- a/doc/book/en/devweb/views/primary.rst	Wed Sep 22 13:33:17 2010 +0200
+++ b/doc/book/en/devweb/views/primary.rst	Wed Sep 22 14:03:24 2010 +0200
@@ -36,15 +36,16 @@
 Attributes/relations display location
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In the primary view, there are 3 sections where attributes and
+In the primary view, there are three sections where attributes and
 relations can be displayed (represented in pink in the image above):
 
-* attributes
-* relations
-* sideboxes
+* 'attributes'
+* 'relations'
+* 'sideboxes'
 
 **Attributes** can only be displayed in the attributes section (default
-  behavior). They can also be hidden.
+  behavior). They can also be hidden. By default, attributes of type `Password`
+  and `Bytes` are hidden.
 
 For instance, to hide the ``title`` attribute of the ``Blog`` entity:
 
@@ -95,6 +96,10 @@
 * ``order``: int used to control order within a section. When not specified,
   automatically set according to order in which tags are added.
 
+* ``label``: label for the relations section or side box
+
+* ``showlabel``: boolean telling whether the label is displayed
+
 .. sourcecode:: python
 
    # let us remind the schema of a blog entry
@@ -110,15 +115,31 @@
    for index, attr in enumerate('title', 'content', 'publish_date'):
        view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index})
 
-Keys for relations only:
+By default, relations displayed in the 'relations' section are being displayed by
+the 'autolimited' view. This view will use comma separated values, or list view
+and/or limit your rset if there is too much items in it (and generate the "view
+all" link in this case).
 
-* ``label``: label for the relations section or side box
+You can control this view by setting the following values in the
+`primaryview_display_ctrl` relation tag:
+
+* `limit`, maximum number of entities to display. The value of the
+  'navigation.related-limit'  cwproperty is used by default (which is 8 by default).
+  If None, no limit.
 
-* ``showlabel``: boolean telling whether the label is displayed
+* `use_list_limit`, number of entities until which they should be display as a list
+  (eg using the 'list' view). Below that limit, the 'csv' view is used. If None,
+  display using 'csv' anyway.
+
+* `subvid`, the subview identifier (eg view that should be used of each item in the
+  list)
 
-* ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed
+Notice you can also use the `filter` key to set up a callback taking the related
+result set as argument and returning it filtered, to do some arbitrary filtering
+that can't be done using rql for instance.
 
-* ``filter``: callback taking the related result set as argument and returning it filtered
+
+
 
 .. sourcecode:: python
 
@@ -153,22 +174,19 @@
 are:
 
 *render_entity_title(self, entity)*
-    Renders the entity title using the ``def dc_title(self)`` method.
-
-*render_entity_metadata(self, entity)*
-    Renders the entity metadata by calling the ``metadata`` view on the
-    entity. This generic view is in cubicweb.views.baseviews.
+    Renders the entity title, by default using entity's :meth:`dc_title()` method.
 
 *render_entity_attributes(self, entity)*
-    Renders all the attribute of an entity with the exception of
-    attribute of type `Password` and `Bytes`. The skip_none class
-    attribute controls the display of None valued attributes.
+    Renders all attributes and relations in the 'attributes' section . The
+    :attr:`skip_none` attribute controls the display of `None` valued attributes.
 
 *render_entity_relations(self, entity)*
-    Renders all the relations of the entity in the main section of the page.
+    Renders all relations in the 'relations' section.
 
 *render_side_boxes(self, entity, boxes)*
-    Renders relations of the entity in a side box.
+    Renders side boxes on the right side of the content. This will generate a box
+    for each relation in the 'sidebox' section, as well as explicit box
+    appobjects selectable in this context.
 
 The placement of relations in the relations section or in side boxes
 can be controlled through the :ref:`primary_view_configuration` mechanism.
@@ -184,24 +202,25 @@
 subclass, you can already customize some of the rendering:
 
 *show_attr_label*
-    Renders the attribute label next to the attribute value if set to True.
+    Renders the attribute label next to the attribute value if set to `True`.
     Otherwise, does only display the attribute value.
 
 *show_rel_label*
-    Renders the relation label next to the relation value if set to True.
+    Renders the relation label next to the relation value if set to `True`.
     Otherwise, does only display the relation value.
 
 *skip_none*
-    Does not render an attribute value that is None if set to True.
+    Does not render an attribute value that is None if set to `True`.
 
 *main_related_section*
-    Renders the relations of the entity if set to True.
+    Renders the relations of the entity if set to `True`.
 
 A good practice is for you to identify the content of your entity type for which
 the default rendering does not answer your need so that you can focus on the specific
 method (from the list above) that needs to be modified. We do not advise you to
 overwrite ``render_entity`` unless you want a completely different layout.
 
+
 Example of customization and creation
 `````````````````````````````````````