NAME

HTML::Widgets::Index - Perl for creating web Indexes and Menus

SYNOPSIS

  use HTML::Widgets::Index;

DESCRIPTION

This module renders the index of a document tree using the data stored in a MySQL database generated by anxova. It has a flexible set of render options that gives the webmaster many options on the menu item layout.

Table

The tree data must be in a table in a database. The fields of this table should be:

 id: int            identifies the entry
 uri: varchar(150)  link of the entry
 text: varchar(150) text displayed in the screen
 id_parent: int     the parent of the current entry. The root is 0
 ordern: int        menu item position on the menu

Data

Say you have a document tree like this:

 a
   a1.html
   a2.html

 b
   b1.html
   b2
     b21.html
     b22.html
   b3.html

 c
   c1.html

Then you must enter this in the table :

 ; First the directory A
 INSERT INTO index_items (id,id_parent,uri,text) 
    VALUES (1,0,'a','dir A');

 ; Now the docs of the a dir
 INSERT INTO index_items (id,id_parent,uri,text) 
    VALUES (2,1,'a1.html','A first');
 INSERT INTO index_items (id,id_parent,uri,text) 
    VALUES (3,1,'a2.html','A 2nd');

; Now the directory B INSERT INTO index_items (id,id_parent,uri,text) VALUES (4,0,'b','dir B'); INSERT INTO index_items (id,id_parent,uri,text) VALUES (5,4,'b1.html','B first');

; The directory B has subdirs INSERT INTO index_items (id,id_parent,uri,text) VALUES (6,4,'b2','B second section');

 INSERT INTO index_items (id,id_parent,uri,text)
    VALUES (7,6,'b21.html','B 2 1 doc');

Notice the uri field is relative, not absolute. You don't need to specify all the path to a document. So you can move docs in the directory, then just change the parent in the table.

The items are sorted alphabetically, if you want to change the order displayed in the html, just add the field ordern when you do the insert:

  INSERT INTO index_items (id,id_parent,uri,text,ordern)
    VALUES (5,4,'b1.html','B first',2);

  INSERT INTO index_items (id,id_parent,uri,text)
    VALUES (6,4,'b2','B second section',1);

CONSTRUCTOR

open

  my $index = HTML::Widgets::Index->open($dbh);

  my $index = HTML::Widgets::Index->open(
               dbh => $dbh           # mandatory
            format => $format,       # optional
        javascript => $javascript,   # optional
  );

  my $index = HTML::Widgets::Index->open(
           $dbh,                 # mandatory
        format => $format,       # optional
    javascript => $javascript,   # optional
  );

METHODS

set_uri

  $index->set_uri( $uri );

  $index->set_uri('/products/networking.html');

get_html

Renders the menu to html:

    print $index->get_html( );

You can use it from a perl templating system for apache, like HTML::Mason or others:

    <% $index->get_html %>

get_title

Returns a suitable title for the document.

The url /computers/networking/data.html returns:

  computers - networking - data

get_path

Returns all the items that leads to the current document, each one has its href.

The url "/computers/networking.html" returns:

  <a href="/computers">computers</a> 
   - <a href="/computers/netwoking.html">networking</a>

It's like the title with links to each part of it.

set_allowed

  Adds a check before every item.

   $index->set_allowed(\&check_user);

  The argument is a reference to a subroutine. This subroutine will
  accept the first argument as the uri and must return true or false.

  example:

    sub check_user {
        my $uri = shift;
        return $uri =~ m#^/intranet#
                        && defined $ENV{REMOTE_USER}
                        && exists intranet_users{$ENV{REMOTE_USER}};
    }

set_render_children

Sets if active item's next level in menu should be rendered or not. This includes not only direct children but also the same level item's children (aka nephews).

  $index->set_render_children( 0 );
  $index->set_render_children( 1 );

set_render_parent

Sets if active item's parent AND uncles should appear in menu or not.

  $index->set_render_parent( 0 );
  $index->set_render_parent( 1 );

set_render_nephews

Sets if active item's nephews should be rendered or not.

  $index->set_render_nephews( 0 );
  $index->set_render_nephews( 1 );

set_render_nth_parents

Sets the number of parents to be rendered (in ascending order). A value of zero deactivates this feature, while a value of one would render only the current menu item (and allow brothers and childs).

  $index->set_render_nth_parents( 0 );
  $index->set_render_nth_parents( 2 );

AUTHOR

Francesc Guasch - Ortiz , frankie@etsetb.upc.edu Joaquim Rovira , jrovira@etsetb.upc.edu

CPAN RT