NAME

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

SYNOPSIS

   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;

DESCRIPTION

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.

INSTALLATION

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

DEPENDENCIES

No thirdy-part modules are required.

CONSTRUCTOR

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

METHODS

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.

EXAMPLES

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;

TODO

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

AUTHORS

Enrico Sorcinelli <enrico@sorcinelli.it>

BUGS

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.

SEE ALSO

File::Spec

COPYRIGHT AND LICENSE

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.

cpanm CGI::Widget::Path

perl -MCPAN -e shell
install CGI::Widget::Path