Breadcrumbs

  • Tags: /
  • Latest: 0.5.2
  • Last Updated: 11 August 2010
  • Grails version: 1.3.2 > *
  • Authors: hardwickj
4 votes
Dependency:
compile ":breadcrumbs:0.5.2"

 Documentation

Summary

Installation

grails install-plugin breadcrumbs

Description

Breadcrumbs

This plugin will provide a fully functional breadcrumb with minimal effort. It allows you to specify your breadcrumbs by simply specifying a CSS selector for selecting an element on the current page to represent the breadcrumb name. It manages the saving of crumb information across page views and in many circumstances only requires adding a single taglib entry to your layout(s).

Please create tickets in JIRA if you encounter any problems or would like to provide suggestions!

To Install:

Plugin installation:

grails install-plugin breadcrumbs

Including resources:

Breadcrumbs makes use of multiple resources, including: You can optionally install these into your application yourself and include them in your layout or desired pages, or you can add the following taglib into your <head> to inject the jBreadCrumb and Easing contents for you. Please Note: This does not include the jQuery library, which must be loaded prior to any of the crumb resources being loaded.
<crumbs:resources/>
will result in the following code being injected into your page:
<script type="text/javascript" src="/appName/plugins/breadcrumbs-0.5.2/js/jquery.easing.js"></script>
<script type="text/javascript" src="/appName/plugins/breadcrumbs-0.5.2/js/jquery.jBreadCrumb.js"></script>
<link rel="stylesheet" type="text/css" href="/appName/plugins/breadcrumbs-0.5.2/css/BreadCrumb.css" media="screen"/>

Usage

Adding the Taglib

Once you have the necessary resources, adding the following taglib to your layout to generate crumb names based on the contents of html <title> elements:
<crumbs:trail selector="title"/>
If you use a common element as the title of your crumbs for each page, for example a <title> element, you can specify this within your Config.groovy file by adding the following snippet:
breadcrumbs.selector="title"
Feel free to make use of both methods. Breadcrumbs will use the in-page taglib defined element over the Config.groovy defined element when it exists. Any standard jquery-style selector should work in specifying the element to use for crumb naming.

Configuring Behavior

Breadcrumbs offers several properties that can be defined in Config.groovy to alter it's default behavior. These are described as follows:
breadcrumbs.home
By default the home icon in the crumb trail will forward to the grails.serverURL property. You can alter this location by defining the breadcrumbs.home property in Config.groovy
breadcrumbs.selector
You can optionally specify a default selector to use in determining crumb names across all pages that contain the crumb trail. This can also be defined as described in Usage --> Adding the Taglib
breadcrumbs.selectors
Soon to come…
breadcrumbs.crumbs.max
By default the crumb trail is limited to a maximum of 10 crumbs. If the number of crumbs exceeds this, the oldest crumb is dropped from the trail. You can alter the number of crumbs to allow before this cut off by defining the breadcrumbs.crumbs.max property in Config.groovy
breadcrumbs.crumbs.showDuplicates
By default the crumb trail will not show duplicate crumbs. If a crumb is already in the crumb trail and you revisit the page represented by that crumb, it will reposition the crumb to the front of the crumb trail. By enabling the showing of duplicates, the original crumb is left in it's position while a new one is added to the front of the crumb trail.
breadcrumbs.crumbs.maxNameLength
By default each crumb name does not have a maximum length. This can potentially result in lengthy crumb names which cause the crumb trail to expand to an undesirable width. Defining breadcrumbs.crumbs.maxNameLength will cause any crumb name in excess of said length to be truncated and appended with a "..." to indicate the truncation.