Warning
Starting from CubicWeb version 4.0 all code related to generating html
views has been moved to the Cube cubicweb_web.
If you want to migrate a project from 3.38 to 4.* while still using all the
html views you need to both install the cubicweb_web cube AND add it to
your dependencies and run add_cube('web')
.
cubicweb_web can be installed from pypi this way:
We don’t plan to maintain the features in cubicweb_web in the long run;
we are moving to a full javascript frontend using both
cubicweb_api (which
exposes a HTTP API) and @cubicweb/client as a frontend
javascript toolkit.
In the long run cubicweb_api will be merged inside of CubicWeb.
Breadcrumbs
Breadcrumbs are a navigation component to help the user locate himself
along a path of entities.
Display
Breadcrumbs are displayed by default in the header section (see
Layout and sections). With the default main template,
the header section is composed by the logo, the application name,
breadcrumbs and, at the most right, the login box. Breadcrumbs are
displayed just next to the application name, thus they begin with a
separator.
Here is the header section of the CubicWeb’s forge:
There are three breadcrumbs components defined in
cubicweb_web.views.ibreadcrumbs
:
BreadCrumbEntityVComponent: displayed for a result set with one line
if the entity is adaptable to IBreadCrumbsAdapter
.
BreadCrumbETypeVComponent: displayed for a result set with more than
one line, but with all entities of the same type which can adapt to
IBreadCrumbsAdapter
.
BreadCrumbAnyRSetVComponent: displayed for any other result set.
Building breadcrumbs
The IBreadCrumbsAdapter
adapter is defined in the
cubicweb_web.views.ibreadcrumbs
module. It specifies that an
entity which implements this interface must have a breadcrumbs
and
a parent_entity
method. A default implementation for each is
provided. This implementation expoits the ITreeAdapter.
Note
Redefining the breadcrumbs is the hammer way to do it. Another way
is to define an ITreeAdapter adapter on an entity type. If
available, it will be used to compute breadcrumbs.
Here is the API of the IBreadCrumbsAdapter
class:
If the breadcrumbs method return a list of entities, the
cubicweb_web.views.ibreadcrumbs.BreadCrumbView
is used to display
the elements.
By default, for any entity, if recurs=True, breadcrumbs method returns
a list of entities, else a list of a simple string.
In order to see a hierarchical breadcrumbs, entities must have a
parent
method which returns the parent entity. By default this
method doesn’t exist on entity, given that it can not be guessed.