# HG changeset patch # User Aurelien Campeas # Date 1271419047 -7200 # Node ID e8567135a927088402f3f0e297713ab8cbdc6326 # Parent c691a424d9e0ca16b817cb477b9c50b020a9fd5e [doc/book] fix docstrings, add notes diff -r c691a424d9e0 -r e8567135a927 doc/book/en/development/devweb/views/breadcrumbs.rst --- a/doc/book/en/development/devweb/views/breadcrumbs.rst Fri Apr 16 11:40:33 2010 +0200 +++ b/doc/book/en/development/devweb/views/breadcrumbs.rst Fri Apr 16 13:57:27 2010 +0200 @@ -1,51 +1,54 @@ Breadcrumbs ----------- -Breadcrumbs are a navigation component to situate the user in the -arborescence's site. - +Breadcrumbs are a navigation component to help the user locate himself +along a path of entities. 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. +:ref:`the_main_template_sections chapter`). With the default main +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: +:mod:`cubicweb.web.views.ibreadcrumbs`: -- BreadCrumbEntityVComponent: displayed for a result set with one line +- `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 +- `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. +- `BreadCrumbAnyRSetVComponent`: displayed for any other result set. -Implementation -~~~~~~~~~~~~~~ +Building breadcrumbs +~~~~~~~~~~~~~~~~~~~~ The ``IBreadCrumbs`` interface is defined in the -``cubicweb/interfaces.py`` file. It specifies that an entity which +:mod:`cubicweb.interfaces` module. It specifies that an entity which implements this interface must have a ``breadcrumbs`` method. +.. note:: + + Redefining the breadcrumbs is the hammer way to do it. Another way + is to define the `parent` method on an entity (as defined in the + `ITree` interface). If available, it will be used to compute + breadcrumbs. + 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. +the elements. By default, for any entity, if recurs=True, breadcrumbs method returns a list of entities, else a list of a simple string. @@ -53,8 +56,3 @@ 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 diff -r c691a424d9e0 -r e8567135a927 interfaces.py --- a/interfaces.py Fri Apr 16 11:40:33 2010 +0200 +++ b/interfaces.py Fri Apr 16 13:57:27 2010 +0200 @@ -1,11 +1,16 @@ -"""Specific views for entities implementing IDownloadable +# organization: Logilab +# copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. +# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr +# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses +""" +Standard interfaces. -:organization: Logilab -:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. -:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr -:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses +.. note:: + + The `implements` selector matches not only entity classes but also + their interfaces. Writing __select__ = implements('IGeocodable') is + a perfectly fine thing to do. """ - __docformat__ = "restructuredtext en" from logilab.common.interface import Interface @@ -159,6 +164,7 @@ class IBreadCrumbs(Interface): """interface for entities which can be "located" on some path""" + # XXX fix recurs ! def breadcrumbs(self, view, recurs=False): """return a list containing some: diff -r c691a424d9e0 -r e8567135a927 mixins.py --- a/mixins.py Fri Apr 16 11:40:33 2010 +0200 +++ b/mixins.py Fri Apr 16 13:57:27 2010 +0200 @@ -1,11 +1,8 @@ -"""mixins of entity/views organized somewhat in a graph or tree structure - - -:organization: Logilab -:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. -:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr -:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses -""" +# organization: Logilab +# copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. +# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr +# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses +"""mixins of entity/views organized somewhat in a graph or tree structure""" __docformat__ = "restructuredtext en" from itertools import chain @@ -17,7 +14,7 @@ class TreeMixIn(object): - """base tree-mixin providing the tree interface + """base tree-mixin implementing the tree interface This mixin has to be inherited explicitly and configured using the tree_attribute, parent_target and children_target class attribute to @@ -275,8 +272,7 @@ class ProgressMixIn(object): - """provide default implementations for IProgress interface methods""" - # This is an adapter isn't it ? + """provide a default implementations for IProgress interface methods""" @property def cost(self):