Breadcrumb Plugin – Configuration

Configuration

Class Name

The Breadcrumb plugin is implemented by the class:

org.onehippo.forge.breadcrumb.components.BreadcrumbComponent

Purpose

This class is used to create a Breadcrumb provider and set the breadcrumbs. The provider can be instantiated within a component to add breadcrumb functionalities by composition. It can be easily extended for specific, custom needs.

Component Parameters

Name	Description
breadcrumb-menus	Not visible in the Experience Manager since webmasters do not know internal menu names. Comma separated list of menu names. The first part of the breadcrumb is generated from the expanded site menu items of the menu named 'main' or from multiple menu's as configured by this parameter. The last (trailing) part of the breadcrumb is generated from the resolved sitemap item belonging to the current request. The trailing items are based on the current resolved sitemap item and then moving upwards, until the highest menu item is encountered. The default is "main".
breadcrumb-separator	Visible in the Experience Manager (since 4.1.0) A separator for the links that are displayed. Value can be entered to the text field for separator. The default is right double angle quotes "»".
breadcrumb-add-content-based	Visible in the Experience Manager (since 4.1.0) If 'true', and there is no active menu item to base the breadcrumb on, the breadcrumb is created from content, i.e. with items pointing to the current content bean and to upward content folders, if URLs exist for those. A boolean value can be assigned using the checkbox field "addContentBased". The default is `false`.
breadcrumb-link-not-found-mode	Visible in the Experience Manager (since 4.1.0) Entries of the breadcrumb path may link to the 'pagenotfound' sitemap item, effectively giving a 404 if the user navigates to them. This parameter specifies alternative behaviour regarding rendering these items: if the value is "hide", the plugin will not render these entries at all. If the value is "unlink", the plugin will render the entries but without a link (so, as plain text). Values can be selected from the dropdown field "linkNotFoundMode". The default is `null`, meaning no rendering behaviour change.
breadcrumb-add-trailing-document-only	Visible in the Experience Manager (since 4.1.0) Set a flag that changes behaviour of the breadcrumb provider: it does not look at path between current document and deepest expanded menu item but just adds the document. The default is `false`, meaning it looks at path between current document and deepest expanded menu item.

Rendering Attributes

Name	Type	Description
breadcrumb	org.onehippo.forge.breadcrumb.om.Breadcrumb	List with the breadcrumb items

Example of a template for the Breadcrumb

Create a Freemarker template such as the following example in the project's webfiles module, per default at repository-data/webfiles/src/main/resources/site/freemarker/myproject/breadcrumb.ftl

<#include "../include/imports.ftl">

<#-- @ftlvariable name="breadcrumb" type="org.onehippo.forge.breadcrumb.om.Breadcrumb" -->
<#if breadcrumb?? && breadcrumb.items??>
    <#list breadcrumb.items as item>
        <#if item.link.notFound && (breadcrumb.linkNotFoundMode == 'hide' || breadcrumb.linkNotFoundMode == 'unlink')>
            <#if breadcrumb.linkNotFoundMode == 'unlink'>
                <a>${item.title?html}</a><#sep> ${breadcrumb.separator}&nbsp;
            </#if>
        <#else>
            <@hst.link var="link" link=item.link/>
            <a <#sep>href="${link}"</#sep>>${item.title?html}</a><#sep> ${breadcrumb.separator}&nbsp;
        </#if>
    </#list>
</#if>

HST Configuration

In the console, add node breadcrumb.template to /hst:hst/hst:configurations/myproject/hst:templates as defined in the YAML below and have it auto-exported.

Alternatively, append the following piece of YAML to the existing repository-data/application/src/main/resources/hcm-config/hst/configurations/myproject/templates.yaml file:
```
/breadcrumb.template:
  jcr:primaryType: hst:template
  hst:renderpath: webfile:/freemarker/myproject/breadcrumb.ftl
```
In the console, add node breadcrumb to /hst:hst/hst:configurations/myproject/hst:components as defined in the YAML below and have it auto-exported.

Alternatively, create breadcrumb.yaml in repository-data/application/src/main/resources/hcm-config/hst/configurations/myproject/components/:
```
definitions:
  config:
    /hst:hst/hst:configurations/myproject/hst:components/breadcrumb:
      jcr:primaryType: hst:component
      hst:componentclassname: org.onehippo.forge.breadcrumb.components.BreadcrumbComponent
      hst:template: breadcrumb.template
```

Applying breadcrumb to pages

To apply the breadcrumb to pages in the website, you can use the developer's method, see HST Component Configuration page.

For example, to apply the breadcrumb to all pages, add node breadcrumb to /hst:hst/hst:configurations/myproject/hst:abstractpages/base. Auto-export should insert a piece of yaml that looks like this:

/breadcrumb:
  jcr:primaryType: hst:component
  hst:referencecomponent: hst:components/breadcrumb

Then, to relevant Freemarker template base-layout.ftl, add the following reference: <@hst.include ref="breadcrumb"/>

Adding breadcrumb component to catalog

To be able to drag and drop the breadcrumb component to a page in the Experience Manager, it should be added to your project's catalog.

For example, add node breadcrumb to /hst:hst/hst:configurations/myproject/hst:catalog/myproject-catalog/. Auto-export should insert a piece of yaml that looks like this:

/breadcrumb:
  jcr:primaryType: hst:containeritemcomponent
  hst:componentclassname:org.onehippo.forge.breadcrumb.components.BreadcrumbComponent
  hst:iconpath: images/myproject/catalog-component-icons/breadrumb.png
  hst:label: Breadcrumb
  hst:template: breadcrumb.template

Note: add a breadcrumb icon image in the Resource folder to your existing project at /myproject-webapp/src/main/webapp/images/myproject/catalog-component-icons. For example, this icon here.

After rebuilding and restarting you should now be able to drag and drop the Breadcrumb component on the pages you want. Configure the component as required and see the changes.

Bloomreach Forge Breadcrumb Plugin