Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Breadcrumbs(3)	      User Contributed Perl Documentation	Breadcrumbs(3)

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

       o   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}.

       o   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: [ '/' ].

       o   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' ].

       o   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.

       o   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.

       o   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

       o   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

       o   sep - the separator (scalar)	used between breadcrumb	elements.
	   Default: '&nbsp;&gt;&nbsp;'.

       o   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.

       o   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.

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.

perl v5.32.0			  2007-06-25			Breadcrumbs(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Breadcrumbs&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help