doc/book/en/devweb/views/breadcrumbs.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Thu, 22 Sep 2011 19:02:36 +0200
branchstable
changeset 7836 0ada13ce2e16
parent 6120 c000e41316ec
permissions -rw-r--r--
[doc] get back baseviews documentation into the code, enhance it and reorganize the module accordingly also properly deprecates SecondaryView as it should have been done a while ago.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     1
Breadcrumbs
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     2
-----------
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     3
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
     4
Breadcrumbs are a navigation component to help the user locate himself
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
     5
along a path of entities.
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     6
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     7
Display
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     8
~~~~~~~
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
     9
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    10
Breadcrumbs are displayed by default in the header section (see
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    11
:ref:`the_main_template_sections`).  With the default main template,
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    12
the header section is composed by the logo, the application name,
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    13
breadcrumbs and, at the most right, the login box. Breadcrumbs are
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    14
displayed just next to the application name, thus they begin with a
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    15
separator.
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    16
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    17
Here is the header section of the CubicWeb's forge:
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    18
5394
105011657405 [doc/book] move devweb up from development, turn development into devrepo (much better structure)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5311
diff changeset
    19
.. image:: ../../images/breadcrumbs_header.png
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    20
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    21
There are three breadcrumbs components defined in
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    22
:mod:`cubicweb.web.views.ibreadcrumbs`:
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    23
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    24
- `BreadCrumbEntityVComponent`: displayed for a result set with one line
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    25
  if the entity is adaptable to ``IBreadCrumbsAdapter``.
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    26
- `BreadCrumbETypeVComponent`: displayed for a result set with more than
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    27
  one line, but with all entities of the same type which can adapt to
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    28
  ``IBreadCrumbsAdapter``.
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    29
- `BreadCrumbAnyRSetVComponent`: displayed for any other result set.
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    30
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    31
Building breadcrumbs
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    32
~~~~~~~~~~~~~~~~~~~~
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    33
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    34
The ``IBreadCrumbsAdapter`` adapter is defined in the
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    35
:mod:`cubicweb.web.views.ibreadcrumbs` module. It specifies that an
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    36
entity which implements this interface must have a ``breadcrumbs`` and
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    37
a ``parent_entity`` method. A default implementation for each is
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    38
provided. This implementation expoits the ITreeAdapter.
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    39
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    40
.. note::
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    41
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    42
   Redefining the breadcrumbs is the hammer way to do it. Another way
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    43
   is to define an `ITreeAdapter` adapter on an entity type. If
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    44
   available, it will be used to compute breadcrumbs.
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    45
5879
7d3044271a29 [doc] update book for adapters
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    46
Here is the API of the ``IBreadCrumbsAdapter`` class:
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    47
6120
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5879
diff changeset
    48
.. automethod:: cubicweb.web.views.ibreadcrumbs.IBreadCrumbsAdapter.parent_entity
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5879
diff changeset
    49
.. automethod:: cubicweb.web.views.ibreadcrumbs.IBreadCrumbsAdapter.breadcrumbs
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    50
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    51
If the breadcrumbs method return a list of entities, the
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    52
``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display
5309
e8567135a927 [doc/book] fix docstrings, add notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5308
diff changeset
    53
the elements.
5308
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    54
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    55
By default, for any entity, if recurs=True, breadcrumbs method returns
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    56
a list of entities, else a list of a simple string.
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    57
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    58
In order to see a hierarchical breadcrumbs, entities must have a
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    59
``parent`` method which returns the parent entity. By default this
c691a424d9e0 [doc/book] complete the breadcrumbs section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 5266
diff changeset
    60
method doesn't exist on entity, given that it can not be guessed.