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

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

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

    14 are displayed just next to the application name, thus breadcrumbs

    15 begin with a 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 implements the ``IBreadCrumbs`` interface.

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

    27   one line, but with all entities of the same type which implement the

    28   ``IBreadCrumbs`` interface.

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

    30 

    31 Building breadcrumbs

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

    33 

    34 The ``IBreadCrumbs`` interface is defined in the

    35 :mod:`cubicweb.interfaces` module. It specifies that an entity which

    36 implements this interface must have a ``breadcrumbs`` method.

    37 

    38 .. note::

    39 

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

    41    is to define the `parent` method on an entity (as defined in the

    42    `ITree` interface). If available, it will be used to compute

    43    breadcrumbs.

    44 

    45 Here is the API of the ``breadcrumbs`` method:

    46 

    47 .. automethod:: cubicweb.interfaces.IBreadCrumbs.breadcrumbs

    48 

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

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

    51 the elements.

    52 

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

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

    55 

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

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

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