breadcrumbs-magnolia
Version:
Breadcrumbs component for Magnolia CMS
181 lines (120 loc) • 6.57 kB
Markdown
# 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:
```bash
mgnl install breadcrumbs-magnolia
```
**Git**
Clone [magnolia breadcrumbs](https://git.magnolia-cms.com/users/kraiskub/repos/breadcrumbs-magnolia/browse) repository into Magnolia's light modules folder.
```bash
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:
```freemarker
<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.
```freemarker
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.
```freemarker
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:
```freemarker
[#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:
```freemarker
[#assign breadcrumbTitlePropertyName = "title"] // Name of the property which will be rendered
```
#### Example title field in a page's dialog
```freemarker
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](https://documentation.magnolia-cms.com/display/DOCS61/Checkbox+field)) in the according page template ContentMap. Specify the name of the property in **/breadcrumbs-magnolia/resources/breadcrumbs.ftl** on line 2:
```freemarker
[#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.
```freemarker
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:
```freemarker
[#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:
```freemarker
// 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](https://getbootstrap.com/) (see their [Breadcrumbs component documentation](https://getbootstrap.com/docs/4.5/components/breadcrumb/)). 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](https://choosealicense.com/licenses/mit/)