@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:
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> > <a href="/colors/all.vhtml">My Colors</a> > 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; }
Modifier and Type | Class and Description |
---|---|
static class |
BreadcrumbTool.NavigationElement
Class representing a navigation element
|
Modifier and Type | Field and Description |
---|---|
protected List<BreadcrumbTool.NavigationElement> |
navigationElements
Navigation elements for the current URI
|
protected javax.servlet.http.HttpServletRequest |
request
Current request
|
DEFAULT_LOCALE
LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY
Constructor and Description |
---|
BreadcrumbTool() |
Modifier and Type | Method and Description |
---|---|
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 '>'
|
getLocale, setLocale, toLocale
configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
forEach, spliterator
protected List<BreadcrumbTool.NavigationElement> navigationElements
protected javax.servlet.http.HttpServletRequest request
public void setRequest(javax.servlet.http.HttpServletRequest request)
request
- 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.
navElem
- navigation elementrequest
- initial requestprotected String formatElementName(String elem)
protected void configure(ValueParser config)
configure
in class LocaleConfig
config
- configuration valuespublic Iterator<BreadcrumbTool.NavigationElement> iterator()
iterator
in interface Iterable<BreadcrumbTool.NavigationElement>
protected static String getExtension(String filename)
filename
- Copyright © 2002–2021 The Apache Software Foundation. All rights reserved.