# HG changeset patch
# User Stephanie Marcu <stephanie.marcu@logilab.fr>
# Date 1271410833 -7200
# Node ID c691a424d9e0ca16b817cb477b9c50b020a9fd5e
# Parent  228932b4f8c523e30ccc52ebbd60b6bc6c23bf32
[doc/book] complete the breadcrumbs section

diff -r 228932b4f8c5 -r c691a424d9e0 doc/book/en/development/devweb/views/basetemplates.rst
--- a/doc/book/en/development/devweb/views/basetemplates.rst	Fri Apr 16 13:22:35 2010 +0200
+++ b/doc/book/en/development/devweb/views/basetemplates.rst	Fri Apr 16 11:40:33 2010 +0200
@@ -39,6 +39,8 @@
 TheMainTemplate
 ---------------
 
+.. _the_main_template_sections:
+
 Layout and sections
 ```````````````````
 
diff -r 228932b4f8c5 -r c691a424d9e0 doc/book/en/development/devweb/views/breadcrumbs.rst
--- a/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 13:22:35 2010 +0200
+++ b/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 11:40:33 2010 +0200
@@ -1,3 +1,60 @@
-Breadcrumbs (:mod:`cubicweb.web.views.ibreadcrumbs`)
-----------------------------------------------------
-XXX feedme
\ No newline at end of file
+Breadcrumbs
+-----------
+
+Breadcrumbs are a navigation component to situate the user in the
+arborescence's site.
+
+
+Display
+~~~~~~~
+
+Breadcrumbs are displayed by default in the header section (see
+:ref:`the_main_template_sections`).  With the default base template,
+the header section is composed by the logo, the application name,
+breadcrumbs and, at the most right, the login box. Breadcrumbs are
+displayed just next to the application name, thus breadcrumbs begin
+with a separator.
+
+Here is the header section of the CubicWeb's forge:
+
+.. image:: ../../../images/breadcrumbs_header.png
+
+There are three breadcrumbs components defined in
+``cubicweb/web/views/ibreadcrumbs.py`` file:
+
+- BreadCrumbEntityVComponent: displayed for a result set with one line
+  if the entity implements the ``IBreadCrumbs`` interface.
+- BreadCrumbETypeVComponent: displayed for a result set with more than
+  one line, but with all entities of the same type which implement the
+  ``IBreadCrumbs`` interface.
+- BreadCrumbAnyRSetVComponent: displayed for any other result set.
+
+Implementation
+~~~~~~~~~~~~~~
+
+The ``IBreadCrumbs`` interface is defined in the
+``cubicweb/interfaces.py`` file. It specifies that an entity which
+implements this interface must have a ``breadcrumbs`` method.
+
+Here is the API of the ``breadcrumbs`` method:
+
+.. automethod:: cubicweb.interfaces.IBreadCrumbs.breadcrumbs
+
+
+If the breadcrumbs method return a list of entities, the
+``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display
+the first elements and the
+``cubicweb.web.views.ibreadcrumbs.BreadCrumbTextView`` is used to
+display the last one.
+
+By default, for any entity, if recurs=True, breadcrumbs method returns
+a list of entities, else a list of a simple string.
+
+In order to see a hierarchical breadcrumbs, entities must have a
+``parent`` method which returns the parent entity. By default this
+method doesn't exist on entity, given that it can not be guessed.
+
+XXX To change the default separator, you have to monkeypatch the
+``BreadCrumbEntityVComponent.separator`` class attribute.
+
+XXX  add_to_breadcrumbs = False on an EntityView