Magnolia-cms Breadcrumbs component

Ready to use Breadcrumbs component. Rendered Breadcrumbs items correspond with the hierarchical structure of your pages in pages-app.

Installation

Magnolia CLI

Run in Magnolia's folder:

mgnl install breadcrumbs-magnolia

Git

Clone magnolia breadcrumbs repository into Magnolia's light modules folder.

git clone https://git.magnolia-cms.com/scm/~kraiskub/breadcrumbs-magnolia.git breadcrumbs-magnolia

Example

Take a look at the page-tree below.

For Web-development page, the rendered markup will be:

<nav id="breadcrumbs" aria-label="breadcrumb">
    <ol>
        <li class="breadcrumb-item" >
            <a href="/magnoliaAuthor/Home.html">
                Home
            </a>
        </li>
        <li class="breadcrumb-item" >
            <a href="/magnoliaAuthor/Home/Services.html">
                Services
            </a>
        </li>
        <li class="breadcrumb-item active" aria-current="page">
            Web development
        </li>
    </ol>
</nav>

Usage

You can use the breadcrumbs as component, area or simply as an include.

1. As a component

You can register this component in available components in an area in your page definition and then render this area in your page template file. This approach is suitable if you want to allow editors to manipulate the Breadcrumbs, e.g. show/hide the breadcrumbs, let them specify the number of breadcrumbs items displayed, etc. - in this case, you would create a dialog for this component with corresponding settings.

areas: 
    header:
        templateScript: /path-to-renderer-template-for-this-area.ftl
        availableComponents:
            breadcrumbs: 
                id: breadcrumbs-magnolia/templates/components/breadcrumbs/breadcrumbs.yaml

2. As an area

You can register breadcrumbs as an area in your page definition and then render this area in your page template file.

areas: 
    breadcrumbs:
        templateScript: /breadcrumbs-magnolia/templates/components/breadcrumbs/breadcrumbs.ftl

3. Include directly into your template file

Directly include the breadcrumbs.ftl file into your template file. Place this line somewhere into your page template:

[#include "/breadcrumbs-magnolia/templates/components/breadcrumbs/breadcrumbs.ftl"]

4. As a generic page returning a JSON response

Open Pages app and create a new page with the 'Breadcrumbs' template in the root, for example name it 'breadcrumbs'.

In order to view the breadcrumbs, navigate to the breadcrumbs page. Apend the desired page's path to the URL as a query parameter named 'path'. For example, if you want to get the breadcrumbs for a certain page, your URL might look like this:

http://localhost:8080/magnoliaAuthor/breadcrumbs?path=/path/to/your/page

Replace '/path/to/your/page' with the actual path to the page for which you want to see the breadcrumbs.

Configuration

Page title property

For breadcrumbs to work correctly, you have to have to specify the name of the property which will be used as a title in the rendered markup. This property and its value have to be present in the ContentMap of the according Page.

Set the property name in /breadcrumbs-magnolia/resources/breadcrumbs.ftl on line 1:

[#assign breadcrumbTitlePropertyName = "title"] // Name of the property which will be rendered

Example title field in a page's dialog

form:
    # ... other form properties
    fields:
        title: 
            fieldType: text
            label: "Page title"
            type: String

Omit specific page

If you want to be able to manually exclude specific pages from rendering in the breadcrumbs, you have to have a property (checkbox type, see documentation) in the according page template ContentMap. Specify the name of the property in /breadcrumbs-magnolia/resources/breadcrumbs.ftl on line 2:

[#assign breadcrumbExcludePagePropertyName = "excludeFromBreadcrumbs"] // Name of the checkbox property used to exclude specific pages

Example checkbox field in a page's dialog

Do not set the default value for the checkbox in the dialog, the page will be omitted if the editor checks the checkbox.

form:
    # ... other form properties
    fields:
        excludeFromBreadcrumbs:
            fieldType: checkbox
            label: Exclude from Breadcrumbs
            buttonLabel: Select to not render this page in the Breadcrumbs

Omit pages with specific template

If you want to omit pages with specific templates and not render them in breadcrumbs, specify the template names in /breadcrumbs-magnolia/resources/breadcrumbs.ftl on line 3:

[#assign excludeTemplates = ['my-light-module:pages/some-template']] // Add names of templates you want to omit to this array

Depth

You can also specify the number of breadcrumbs items you want to render.

Set the depth in /breadcrumbs-magnolia/resources/breadcrumbs.ftl on line 4:

// depth == -1 .. Default value - display all Breadcrumbs items
// depth == 0 .. display 0 Breadcrumbs items
[#assign depth = - 1] // Number of breadcrumbs items to be rendered

HTML markup

HTML markup is inspired by the Twitter Bootstrap framework (see their Breadcrumbs component documentation). The markup also implements accessibility. Styling is completely up to the developer.

You can modify the markup in /breadcrumbs-magnolia/templates/components/breadcrumbs/breadcrumbs.ftl.

JSON response

You can modify the json response in /breadcrumbs-magnolia/templates/pages/breadcrumbs/breadcrumbs.ftl.

License

MIT