Package org.apache.velocity.tools.view

Class BreadcrumbTool

  • All Implemented Interfaces:
    java.lang.Iterable<BreadcrumbTool.NavigationElement>
    @DefaultKey("breadcrumb")
@ValidScope("request")
public class BreadcrumbTool
extends org.apache.velocity.tools.generic.LocaleConfig
implements java.lang.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:

    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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.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

      All Methods Static Methods Instance Methods Concrete Methods 
      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 java.lang.String formatElementName​(java.lang.String elem)
      Automatic default formatting of URI elements
      protected static java.lang.String getExtension​(java.lang.String filename)
      Utility method to return URI file extension
      java.util.Iterator<BreadcrumbTool.NavigationElement> iterator()
      Navigation elements iteration
      void setRequest​(javax.servlet.http.HttpServletRequest request)
      Current request setter
      java.lang.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

      • 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 java.lang.String formatElementName​(java.lang.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

      • getExtension

        protected static java.lang.String getExtension​(java.lang.String filename)
        Utility method to return URI file extension
        Parameters:
        filename -
        Returns:

      • toString

        public java.lang.String toString()
        Default concatenation of navigation elements, separated by '>'
        Overrides:
        toString in class java.lang.Object
        Returns:
        string representation