org.apache.velocity.tools.view

## 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(value="breadcrumb")
     @ValidScope(value="request")
    public class BreadcrumbTool
    extends 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:

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:

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
`static class` `BreadcrumbTool.NavigationElement` Class representing a navigation element

### Field Summary

Fields
`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 and Description
`BreadcrumbTool()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`protected void` `configure(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 java.lang.Object

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

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Field Detail

#### navigationElements

    protected List<BreadcrumbTool.NavigationElement> navigationElements

Navigation elements for the current URI

#### request

    protected javax.servlet.http.HttpServletRequest request

Current request

### Constructor Detail

#### BreadcrumbTool

    public BreadcrumbTool()

### Method Detail

#### 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(ValueParser config)

Configuration

Overrides:
  `configure` in class `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