Gavin Carr > HTML-Breadcrumbs-0.7 > HTML::Breadcrumbs

Download:
HTML-Breadcrumbs-0.7.tar.gz

Dependencies

Annotate this POD

Related Modules

Compress::Zlib
more...
By perlmonks.org

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.7   Source  

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

LABELS

RENDERING

AUTHOR ^

Gavin Carr <gavin@openfusion.com.au>

COPYRIGHT ^

Copyright 2002-2005, Gavin Carr. All Rights Reserved.

This program is free software. You may copy or redistribute it under the same terms as perl itself.

syntax highlighting: