doc/book/en/devweb/views/breadcrumbs.rst
branchstable
changeset 5394 105011657405
parent 5311 34dc38456376
child 5879 7d3044271a29
equal deleted inserted replaced
5393:875bdc0fe8ce 5394:105011657405
       
     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.