CGI::Widget::Path - Simple HTML navigation path bar builder

   use CGI::Widget::Path;
   my $path = new CGI::Widget::Path( 
      separator => ' > ',
      base_url  => 'http://www.foo.com',
      link      => 1,
      link_last => 1,
   );
   $path->addElem( elems => [
      { name => 'One', wrap => [ { tag => 'a', attr => { 'href' => 'url1' } ], append => 1 },
      { name => 'Two', wrap => [ { tag => 'a', attr => { 'href' => 'url2' } ], append => 1 },
      ] );
   print $path->asHTML;

CGI::Widget::Path lets you build a navigation path bar (you know: "You are here: Home > some > page") in order to put it in your HTML pages.

This module is very simple but it can be useful if you create a path component at the top of your application and share it among all sub-pages.

In order to install and use this package you will need Perl version 5.005 or higher.

Installation as usual:

   % perl Makefile.PL
   % make
   % make test
   % su
     Password: *******
   % make install

No thirdy-part modules are required.

* new( %args )

It's possible to create a new CGI::Widget::Path by invoking the new method. Parameters are passed as hash array:

base_url string

Adds this string at the beginning of each link.

link boolean

Links all path items wrapped by an 'a' tag. Default is 1.

link_last boolean

Links last path item. Default is 0.

separator string

Sets separator between path items. Default is '>'

path string

Uses path as a file system path and builds automatically a path tree array (see EXAMPLES section).

elems array reference

This parameter is an anonymous array. Each element (an hash reference) represents each path item. You can also set or add (other) path elements by calling addElem method.

See elems argument in addElem method for more informations.

CGI::Widget::Path has following public methods:

* addElem( %args )

Adds an element into path tree. Parameters are passed as hash array:

position number

Sets position where to start adding new element(s). New path elements are appended at the end of array if none.

elems array reference

This argument is the same of elems contructor argument, that is an anonymous array o hash reference. Each element is a anonymous hash with following keys:

name string

The name of path item.

wrap array reference

An anonymous array containing HTML tags that will wrap the path item (like tha 'A' tag for links). Each element is a hash reference containg at least 'tag' key. An optional 'attr' keys can be used in order to set tag's attributes.

append

If set to 1, the 'href' attribute of 'a' tag will be 'appended' to all other previous path elements 'href' values. Default is 0.

For example:

   elems => [ 
      { name => 'One', wrap => [ { tag => 'a', attr => { 'href' => 'url1', class => 'myclass' } } ], append => 1 },
	]

Returns the number of path elements

* deleteElem( %args )

Deletes items from path tree. Parameters are passed as hash array:

position number

Deletes item, starting from position

lenght number

Deletes lenght items. Default value is 1.

Returns the number of path elements

* asHTML()

Builds and returns HTML path widget. After call it, you can use also $self->{out} object property in order to retrieve HTML generated code.

* errstr()

Returns current error string.

This example creates and renders a path widget from a filesystem path:

   use CGI::Widget::Path;
   # create new path object
   my $path = new CGI::Widget::Path( 
      separator => ' / ', 
      base_url  => 'http://www.foo.com', 
      path => '/one/two/tree/four.txt' 
      );
   # Optionally set root label with 'My Home' (default is 'root')
   $path->{elems}->[0]->{'name'} = 'My Home';
   print $path->asHTML;

This will produce following output:

   <a href="http://www.foo.com/">My Home</a> / <a href="http://www.foo.com/one/">one</a> / 
   <a href="http://www.foo.com/one/two/">two</a> / <a href="http://www.foo.com/one/two/tree/">tree</a> / four.txt

This example creates and renders a path widget from a filesystem path:

   use CGI::Widget::Path;
   # create new path object
   my $path = new CGI::Widget::Path();
   $path->addElem( elems => [
      { name => 'One', wrap => [ { tag => 'a', attr => { 'href' => '/url1', class => 'myclass' } } ], append => 1 },
      { name => 'Two', wrap => [ { tag => 'a', attr => { 'href' => '/url2' } } ], append => 1 },
		{ name => 'Three', wrap => [ { tag => 'a', attr => { 'href' => '/url3' } } ], append => 1 },
      ] );
   print $path->asHTML;

This will produce following output:

   <a href="/url1" class="myclass">One</a>><a href="/url1/url2">Two</a>>Three

This example creates and renders a path widget from current URI:

   # create new path object
   my $path = new CGI::Widget::Path( 
      separator => '/',
      base_url  => 'http://' . $ENV{HTTP_HOST},
      path => $ENV{SCRIPT_NAME} . $ENV{PATH_INFO}
      );
   $path->{elems}->[0]->{name} = 'My Home';
   print $path->asHTML;

*

Add an OO interface to manage HTML elements (possibly by using HTML::Element, if installed)

Enrico Sorcinelli <enrico@sorcinelli.it>

This library has been tested by the author with Perl versions 5.005, 5.6.x and 5.8.x on different platforms: Linux 2.2 and 2.4, Solaris 2.6 and 2.7 and Windows 98.

Send bug reports and comments to: enrico@sorcinelli.it In each report please include the version module, the Perl version, the Apache, the mod_perl version and your SO. If the problem is browser dependent please include also browser name and version.

Patches are welcome and I'll update the module if any problems will be found.

File::Spec

Copyright (C) 2003,2004 Enrico Sorcinelli. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.