1 Breadcrumbs

     2 -----------

     3 

     4 Breadcrumbs are a navigation component to help the user locate himself

     5 along a path of entities.

     6 

     7 Display

     8 ~~~~~~~

     9 

    10 Breadcrumbs are displayed by default in the header section (see

    11 :ref:`the_main_template_sections`).  With the default main template,

    12 the header section is composed by the logo, the application name,

    13 breadcrumbs and, at the most right, the login box. Breadcrumbs are

    14 displayed just next to the application name, thus they begin with a

    15 separator.

    16 

    17 Here is the header section of the CubicWeb's forge:

    18 

    19 .. image:: ../../images/breadcrumbs_header.png

    20 

    21 There are three breadcrumbs components defined in

    22 :mod:`cubicweb.web.views.ibreadcrumbs`:

    23 

    24 - `BreadCrumbEntityVComponent`: displayed for a result set with one line

    25   if the entity is adaptable to ``IBreadCrumbsAdapter``.

    26 - `BreadCrumbETypeVComponent`: displayed for a result set with more than

    27   one line, but with all entities of the same type which can adapt to

    28   ``IBreadCrumbsAdapter``.

    29 - `BreadCrumbAnyRSetVComponent`: displayed for any other result set.

    30 

    31 Building breadcrumbs

    32 ~~~~~~~~~~~~~~~~~~~~

    33 

    34 The ``IBreadCrumbsAdapter`` adapter is defined in the

    35 :mod:`cubicweb.web.views.ibreadcrumbs` module. It specifies that an

    36 entity which implements this interface must have a ``breadcrumbs`` and

    37 a ``parent_entity`` method. A default implementation for each is

    38 provided. This implementation expoits the ITreeAdapter.

    39 

    40 .. note::

    41 

    42    Redefining the breadcrumbs is the hammer way to do it. Another way

    43    is to define an `ITreeAdapter` adapter on an entity type. If

    44    available, it will be used to compute breadcrumbs.

    45 

    46 Here is the API of the ``IBreadCrumbsAdapter`` class:

    47 

    48 .. automethod:: cubicweb.web.views.ibreadcrumbs.IBreadCrumbsAdapter.parent_entity

    49 .. automethod:: cubicweb.web.views.ibreadcrumbs.IBreadCrumbsAdapter.breadcrumbs

    50 

    51 If the breadcrumbs method return a list of entities, the

    52 ``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display

    53 the elements.

    54 

    55 By default, for any entity, if recurs=True, breadcrumbs method returns

    56 a list of entities, else a list of a simple string.

    57 

    58 In order to see a hierarchical breadcrumbs, entities must have a

    59 ``parent`` method which returns the parent entity. By default this

    60 method doesn't exist on entity, given that it can not be guessed.