App::ZofCMS::Plugin::BreadCrumbs - add "breadcrumbs" navigation to your sites

In your ZofCMS template:

    plugins => [ qw/BreadCrumbs/ ]

In your HTML::Template template:

    <tmpl_var name="breadcrumbs">

The module is a plugin for App::ZofCMS. It provides means to add a "breadcrumbs" (http://en.wikipedia.org/wiki/Breadcrumb_(navigation)) to your pages.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

The plugin automagically generates breadcrumb links, if your sites are relatively simple and pages are in good hierarchy the plugin will do the Right Thing(tm) most of the time. The links for breadcrumbs are determined as follows. If the page is not called index then the index page in the current "directory" will be added to the breadcrumbs, the "path" will be broken down to pieces and index page in each piece will be added to the breadcrumbs. Note: the examples below assume that the no_pages argument was not specified:

    # page
    index.pl?page=/foo/bar/baz

    # crumbs
    /index => /foo/index => /foo/bar/index => /foo/bar/baz




    # page
    index.pl?page=/foo/bar/beer/index

    # crumbs
    /index => /foo/index/ => /foo/bar/index => /foo/bar/beer/index

    plugins => [ qw/BreadCrumbs/ ]

First and obvious you need to add BreadCrumbs to the list of plugins to execute. Just this will already make the plugin execute, i.e. having the breadcrumbs key (see below) is not necessary.

    breadcrumbs => {}, # disable the plugin

    # lots of options
    breadcrumbs => {
        direct      => 1,
        span        => 1,
        no_pages => [ '/comments' ],
        key         => 'page_title',
        text_re     => qr/([^-]+)/,
        change      => {
            qr/foo/ => 'foos',
            qr/bar/ => 'bars',
        },
        replace     => {
            qr/foo/ => 'foos',
            qr/bar/ => 'bars',
        },
    },

The breadcrumbs first-level ZofCMS template key controls the behaviour of the plugin. Can be specified as the first-level key in Main Config File, but unlike many other plugins the hashref keys do NOT merge; i.e. if you set the key in both files, the value in ZofCMS Template will take precedence. The key takes a hashref as a value. Do NOT specify this key if you wish to use all the defaults, as specifying an empty hashref as a value will disable the plugin for that given page. Possible keys/values of that hashref are as follows:

    { direct => 1 },

Optional. Takes either true or false values. When set to a false value the breadcrumb links will all be of form /index.pl?page=/index. When set to a true value the links will be of form /index which is useful when you are making your URIs with something like mod_rewrite. Defaults to: false

    { span => 1 },

Optional. The span key takes either true or false values. When set to a true value, the plugin will generate <span> based breadcrumbs. When set to a false value, the plugin will generate <ul> based breadcrumbs. Default to: false.

    { no_pages => [ '/comments', '/index' ], }

Optional. Takes an arrayref as a value. Each element of that array must be a dir + page (as described in Note on page and dir query parameters in App::ZofCMS::Config). If a certain element of that array matches the page in the breadcrumbs being generated it will be removed from the breadcrumbs. In other words, if you specify no_pages => [ '/index' ] the "index" page of the "root" directory will not show up in the breadcrumbs. By default is not specified.

    { key => 'title', }

Optional. When walking up the "tree" of pages plugin will open ZofCMS templates for those pages and use the key key's value as the text for the link. Only first-level keys are supported. Defaults to: title

    { text_re => qr/([^-]+)/ }

Optional. Takes a regex (qr//) as a value which must contain a capturing set of parentheses. When specified will run the regex on the value of key (see above) key's value and whatever was captured in the capturing parentheses will be used for the text of the link. By default is not specified.

    change => {
        qr/foo/ => 'foos',
        qr/bar/ => 'bars',
    },

Optional. Takes a hashref as a value. The keys of that hashref are regexen (qr//) and the values are the text with which the entire text of the link will be replaced if that particular regex matches. In other words, if you specify change => { qr/foo/ => 'foo' } and your link text is lots and lots of foos it will turn into just foo. By default is not specified.

    replace => {
        qr/foo/ => 'foos',
        qr/bar/ => 'bars',
    },

Optional. Same as change key described above, except replace will replace the matching part with the text provided as a value. In other words, if you specify replace => { qr/foo/ => 'BAR' } and your link text is lots and lots of foos it will turn into lots and lots of BARs. By default is not specified.

    <tmpl_var name="breadcrumbs">

The plugin set one key - breadcrumbs - in {t} special key which means that you can stick <tmpl_var name="breadcrumbs"> in any of your HTML::Template templates and this is where the breadcrumbs will be placed.

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

Please report any bugs or feature requests to bug-app-zofcms-plugin-breadcrumbs at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-BreadCrumbs. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc App::ZofCMS::Plugin::BreadCrumbs

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS-Plugin-BreadCrumbs

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS-Plugin-BreadCrumbs

* CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS-Plugin-BreadCrumbs

* Search CPAN

http://search.cpan.org/dist/App-ZofCMS-Plugin-BreadCrumbs

Copyright 2008 Zoffix Znet, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.