Class BreadcrumbTool

java.lang.Object

org.apache.velocity.tools.generic.SafeConfig

org.apache.velocity.tools.generic.LocaleConfig

org.apache.velocity.tools.view.BreadcrumbTool

All Implemented Interfaces:

Iterable<BreadcrumbTool.NavigationElement>

@DefaultKey("breadcrumb")
@ValidScope("request")
public class BreadcrumbTool
extends org.apache.velocity.tools.generic.LocaleConfig
implements Iterable<BreadcrumbTool.NavigationElement>

Helper tool to display a navigation breadcrumb to the end user.

It relies on the asumption that your URI hierarchy corresponds to the navigation hierarchy you want to present to your users, each level having its landing index page. Please note that this asumption is considered a *good practice*.

Each intermediate path element becomes a navigation element, and there is an additional ending navigation element when the page is not an index page.

For instance, if the URI is `/colors/red/nuances.html`, the provided path elements will be:

• 'colors', pointing towards '/colors/index.html'
• 'red', pointing towards '/colors/red/index.html'
• 'nuances', pointing towards '/colors/red/nuances.html'

The filename extension (`html` in the above example) is inferred from found URIs.

By default, the displayed name of a navigation element is the name of its corresponding path element with all '_' replaced by spaces, transformed to lowercase.

You can customize this displayed name and the URL of every path element using tools properties:

     <tool key="breadcrumb" colors.name="My Colors" colors.url="/colors/all.vhtml"/>
 

where 'colors' refers to the /colors/ path element. The name and destination of the root path element can be changed with 'home.name' and 'home.url'.

If you provide a name property prefixed with '?', the breadcrumb tool will use the value of the corresponding query parameter as navigation element name, and will keep this query parameter in the navigation element URL.

You can also define your own rules programmatically by subclassing BreadcrumbTool and override the boolean customize(NavigationElement, HttpServletRequest) method, which will be called for every navigation element. Returning false will skip this navigation element from the breadcrumb.

Inside a template, you would either render directly the default resulting HTML fragment with:

$breadcrumb

which would produce simething like:

<a href="/index.vhtml">home</a>&nbsp;&gt;&nbsp;<a href="/colors/all.vhtml">My Colors</a>&nbsp;&gt;&nbsp;nuances

or you would iterate through navigation elements for a better control of the output with:

 

 #foreach($element in $breadcrumb)
  #if(!$foreach.first)
   >
  #end
  #if(!$foreach.last)#end
   $element.name
  #if(!$foreach.last)#end
 #end

And of course, you would supply the necessary CSS, for instance:

 #breadcrumb { font-size: smaller; }
 #breadcrumb a { color: #4183c4; text-decoration: none; }
 #breadcrumb .divider { color: rgba(0, 0, 0, 0.4); vertical-align: baseline; margin: 0 0.2rem; }
 

Since:

3.1

Version:

$$

Author:

Claude Brisson

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	BreadcrumbTool.NavigationElement	Class representing a navigation element

Field Summary

Fields

Modifier and Type	Field	Description
protected List<BreadcrumbTool.NavigationElement>	navigationElements	Navigation elements for the current URI
protected javax.servlet.http.HttpServletRequest	request	Current request

Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig

DEFAULT_LOCALE

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors

Constructor	Description
BreadcrumbTool()

Method Summary

Modifier and Type	Method	Description
protected void	configure(org.apache.velocity.tools.generic.ValueParser config)	Configuration
protected boolean	customize(BreadcrumbTool.NavigationElement navElem, javax.servlet.http.HttpServletRequest request)	Let the user customize programmatically the name and URL of a specific element.
protected String	formatElementName(String elem)	Automatic default formatting of URI elements
protected static String	getExtension(String filename)	Utility method to return URI file extension
Iterator<BreadcrumbTool.NavigationElement>	iterator()	Navigation elements iteration
void	setRequest(javax.servlet.http.HttpServletRequest request)	Current request setter
String	toString()	Default concatenation of navigation elements, separated by '>'

Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

getLocale, setLocale, toLocale

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface Iterable

forEach, spliterator

Field Details

navigationElements

protected List<BreadcrumbTool.NavigationElement> navigationElements

Navigation elements for the current URI

request

protected javax.servlet.http.HttpServletRequest request

Current request

Constructor Details

BreadcrumbTool

public BreadcrumbTool()

Method Details

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest request)

Current request setter

Parameters:

request -

customize

protected boolean customize(BreadcrumbTool.NavigationElement navElem,
 javax.servlet.http.HttpServletRequest request)

Let the user customize programmatically the name and URL of a specific element.

For instance, one can do use query parameters to customize the displayed name or target URL.

Parameters:

navElem - navigation element

request - initial request

Returns:

true (default value) to include this navigation element, false to skip it

formatElementName

protected String formatElementName(String elem)

Automatic default formatting of URI elements

configure

protected void configure(org.apache.velocity.tools.generic.ValueParser config)

Configuration

Overrides:

configure in class org.apache.velocity.tools.generic.LocaleConfig

iterator

public Iterator<BreadcrumbTool.NavigationElement> iterator()

Navigation elements iteration

Specified by:

iterator in interface Iterable<BreadcrumbTool.NavigationElement>

Returns:

Iterator over navigation elements

getExtension

protected static String getExtension(String filename)

Utility method to return URI file extension

Parameters:

filename -

Returns:

toString

public String toString()

Default concatenation of navigation elements, separated by '>'

Overrides:

toString in class Object

Returns:

string representation