|
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. |