NAME

HTML::Breadcrumbs - module to produce HTML 'breadcrumb trails'.

SYNOPSIS

    # Procedural interace
    use HTML::Breadcrumbs qw(breadcrumbs);
    print breadcrumbs(path => '/foo/bar/bog.html');
    # prints: Home > Foo > Bar > Bog (the first three as links)

    # More complex version - some explicit element labels + extras
    print breadcrumbs(
        path => '/foo/bar/biff/bog.html', 
        labels => {
            'bog.html' => 'Various Magical Stuff',
            '/foo' => 'Foo Foo',
            bar => 'Bar Bar',
            '/' => 'Start', 
        },
        sep => ' :: ',
        format => '<a target="_blank" href="%s">%s</a>',
    );
    # prints: Start :: Foo Foo :: Bar Bar :: Biff :: Various Magical Stuff

    # Object interface
    use HTML::Breadcrumbs;

    # Create
    $bc = HTML::Breadcrumbs->new(
        path => $path, 
        labels => {
            'download.html' => 'Download',
            foo => 'Bar',
            'x.html' => 'The X Files',
        },
    );

    # Render
    print $bc->render(sep => '&nbsp;::&nbsp;');

DESCRIPTION

HTML::Breadcrumbs is a module used to create HTML 'breadcrumb trails' i.e. an ordered set of html links locating the current page within a hierarchy.

HTML::Breadcrumbs splits the given path up into a list of elements, derives labels to use for each of these elements, and then renders this list as N-1 links using the derived label, with the final element being just a label.

Both procedural and object-oriented interfaces are provided. The OO interface is useful if you want to separate object creation and initialisation from rendering or display, or for subclassing.

Both interfaces allow you to munge the path in various ways (see the roots and indexes arguments); set labels either explicitly via a hashref or via a callback subroutine (see labels); and control the formatting of elements via sprintf patterns or a callback subroutine (see format and format_last).

PROCEDURAL INTERFACE

The procedural interface is the breadcrumbs() subroutine (not exported by default), which uses a named parameter style. Example usage:

    # Procedural interace
    use HTML::Breadcrumbs qw(breadcrumbs);
    print breadcrumbs(
        path => $path, 
        labels => {
            'download.html' => 'Download',
            foo => 'Bar',
            'x.html' => 'The X Files',
        },
        sep => '&nbsp;::&nbsp;',
        format => '<a class="breadcrumbs" href="%s">%s</a>',
        format_last => '<span class="bclast">%s</span>,
    );

OBJECT INTERFACE

The object interface consists of two public methods: the traditional new() for object creation, and render() to return the formatted breadcrumb trail as a string (to_string() is an alias for render). Arguments are passed in the same named parameter style used in the procedural interface. All arguments can be passed to either method (using new() is preferred, although using render() for formatting arguments can be a useful convention).

Example usage:

    # OO interface
    use HTML::Breadcrumbs;
    $bc = HTML::Breadcrumbs->new(path => $path);
    
    # Later
    print $bc->render(sep => '&nbsp;::&nbsp;');

    # OR
    $bc = HTML::Breadcrumbs->new(
        path => $path,
        labels => {
            'download.html' => 'Download',
            foo => 'Bar',
            'x.html' => 'The X Files',
        },
        sep => '&nbsp;::&nbsp;',
        format => '<a class="breadcrumbs" href="%s">%s</a>',
        format_last => '<span class="bclast">%s</span>,
    );
    print $bc->render();    # Same as bc->to_string()

ARGUMENTS

breadcrumbs() takes the following parameters:

PATH PROCESSING

path - the uri-relative path of the item this breadcrumb trail is for, as found, for example, in $ENV{SCRIPT_NAME}. This should probably be the real uri-based path to the object, so that the elements derived from it produce valid links - if you want to munge the path and the elements from it see the roots, omit, and map parameters. Default: $ENV{SCRIPT_NAME}.
roots - an arrayref of uri-relative paths used to identify the root (the first element) of the breadcrumb trail as something other than '/'. For example, if the roots arrayref contains '/foo', a path of /foo/test.html will be split into two elements: /foo and /foo/test.html, and rendered as "Foo > Test". The default behaviour would be to split /foo/test.html into three elements: /, /foo, and /foo/test.html, rendered as "Home > Foo > Test". Default: [ '/' ].
indexes - an arrayref of filenames (basenames) to treat as index pages. Index pages are omitted where they occur as the last element in the element list, essentially identifying the index page with its directory e.g. /foo/bar/index.html is treated as /foo/bar, rendered as "Home > Foo > Bar" with the first two links. Anything you would add to an apache DirectoryIndex directive should probably also be included here. Default: [ 'index.html' ].
omit - a scalar or arrayref of elements to be omitted or skipped when producing breadcrumbs. Omit arguments should be either bare element names (i.e. contain no '/' characters, e.g. 'forms') or full absolute paths (i.e. begin with a '/', e.g. '/cgi-bin/forms') . For example, if omit includes 'cgi-bin', then a path of '/cgi-bin/forms/help.html' would be rendered as "Home > Forms > Help" instead of the default "Home > cgi-bin > Forms > Help". Default: none.
omit_regex - a scalar or arrayref of regular expressions used to match elements to be omitted when producing breadcrumbs. Like 'omit', regexes should match either bare element names (no '/' characters, e.g. 'forms') or full absolute paths (beginning with '/', e.g. '/cgi-bin/forms'). WARNING: absolute paths are always explicitly anchored at both ends (i.e. '/cgi-bin/forms' is used as m!^/cgi-bin/forms/$!), since otherwise the pattern matches every path after an initial match.
For example, a path like "/product/12/sample" will be rendered as "Home > Product > Sample" instead of the default "Home > Product > 12 > Sample" using any of the following omit_regex patterns: '\d+', '/product/\d+', '/product/[^/]+', etc. Note that partial full-path matches like '/product/1' will NOT cause the '12' element to be omitted, however.

Default: none.
map - a hashref of path mappings used to transform individual element paths. Map key paths may be either full absolute paths, or simple path basenames. Elements that match a map key path have their paths replaced by the map value e.g. a path of /foo/bar/bog.html with the following map:
```
  map => {
    '/' => '/home.html',
    '/foo' => '/foo/foo.html',
    'bar' => '/foo/bar.html',
  },
```
will render with paths of (non-final labels omitted for clarity):
```
  /home.html > /foo/foo.html > /foo/bar.html > Bog
```

LABELS

labels - a hashref or a subroutine reference used to derive the labels of the breadcrumb trail elements. Default: none.
If a hashref, first the fully-qualified element name (e.g. /foo/bar or /foo/bar/, or /foo/bar/bog.html) and then the element basename (e.g. 'bar' or 'bog.html') are looked up in the hashref. If found, the corresponding value is used for the element label.

If this parameter is a subroutine reference, the subroutine is invoked for each element as:
```
  C<$sub->($elt, $base, $last)>
```
where $elt is the fully-qualified element (e.g. /foo/bar or /foo/bar/bog.html), $base is the element basename (e.g. 'bar' or 'bog.html'), and $last is a boolean true iff this is the last element. The subroutine should return the label to use (return undef or '' to accept the default).

If no label is found for an element, the default behaviour is to use the element basename as its label (without any suffix, if the final element). If the label is lowercase and only \w characters, it will be ucfirst()-ed.

RENDERING

sep - the separator (scalar) used between breadcrumb elements. Default: ' > '.
format - a subroutine reference or a (scalar) sprintf pattern used to format each breadcrumb element except the last (for which, see format_last).
If a subroutine reference, the subroutine is invoked for each element as:
```
  C<$sub->($elt, $label)>.
```
where $elt is fully-qualified element (e.g. /foo/bar or /foo/bar/bog.html) and $label is the label for the element.

If a scalar, it is used as a sprintf format with the fully-qualified element and the label as arguments i.e. sprintf $format, $element, $label.

Default: '<a href="%s">%s</a>' i.e. a vanilla HTML link.
format_last - a subroutine reference or a (scalar) sprintf pattern used to format the last breadcrumb element (not a link).
If a subroutine reference, the subroutine is invoked for the element the label as only parameter i.e. $sub-($label)>.

If a scalar, it is used as a sprintf format with the label as argument i.e. sprintf $format_last, $label.

Default: '%s' i.e. the label itself.