Welcome to HTML::Widgets::Menu.

INSTALATION
	perl Makefile.PL
	make
	make install

NAME
    HTML::Widgets::Menu - Builds an HTML menu

SYNOPSIS
      use HTML::Widgets::Menu;
      my $main=HTML::Widgets::Menu->new(
             home   => "/users/frankie/",

             format => {
                default=>{
                     # default format options #
                },
                0=>{
                   #level 0 format  options#
                }
                # more levels
             },

             menu=> [
                item1=>{
                    url=>"url for item 1",
                    menu=>[
                          item1_1=>'url for item 1_1'
                    ]
                },
                item2=>"url for item 2"
                # more items
             ]
          );

          my ($menu)=$main->show();

          <% $menu %>

DESCRIPTION
    This module will help you build a menu for your HTML site. You
    can use with CGI or any mod_perl module. I use it from Mason.
    Every time you request to show a menu it will return the HTML
    tags. It's smart enough it will highlight the current active
    items.

    This software is in a very early stage. It works fine for me and
    is used in production sites. You can send me patches, bugs or
    suggestions. I'm not likely to answer your questions. This
    software is provided as is and you're using it at your own risk.
    You agree to use it with the same license of perl itself.

    Drawing a menu is a matter of : 
		- the items of the menu 
		- the format you want it to have

    You also must supply the home directory for all the web you want
    to add this menu.

  ITEMS

    The items is a list.

    For example, a simple menu could be:

        my @menu=(
              homepage   =>'.',
              "my links" =>"links.html"
        );

    You can add levels of depth to the menu:

        my @menu=(  
            homepage => '.',
            "my links=>{
                      url=>"links/",
                      menu=>[
                            perl  =>"perl_link.html",
                            "movies I like"=>'movies.html'
                      ],
             about=>"about.html"
         );

    For every level you add instead of the url you must supply a
    reference to a hash with the url and the menu. Now you can get
    this menu printed without any format at all.

    my
    $main=HTML::Widgets::Menu(menu=>\@menu,home=>"/users/frankie/");
    my ($menu)=$main->show();

    Later insert $menu in your page. With Mason I'd do: <% $menu %>

    If the url of the item is only the name of a directory (the
    final / is not necessary), the path is added to the submenu. For
    the example above you must write the files: 
		index.html
    	links/index.html 
		links/perl_link.thml 
		links/movies.html
    	about.html

    The format is the way you tell how to show the items of the menu
    It's a hash where you define the options. There should be a
    default entry and numbered entries for every level, starting
    with 0.

    Options available (with defaults): 
		max_depth => 1, # max number
    						of depth if items are not active 
		start => '', #html to put at
    					the start of the level 
		end => '', #html to add at the end of the level
    	
		font=>'<FONT>', 
	
		active_item_start => '<B><I>',

	    active_item_end => '</B></I>', 

		inactive_item_start => '',

 		inactive_item_end => '', text_placeholder => '<text>', 
			# example:
            <IMG SRC="<text>.gif" ALT="<text>"> 
                      ------           ------
    	link_args=>'', # put javascript options here or other args 
    					# for the <A HREF tag 

		indent => 1, # pixels for the indentation

    Example: 
		my %format={ 
			default=>{ 
				max_depth=>2, 
				font=>"<FONT
    						SIZE=2>\n", 

				active_item_start=>"<IMG
    				SRC=\"/users/frankie/img/blue_arrow.gif\" BORDER=0
    				WIDTH=6><B><I><FONT COLOR=\"BLUE\">",

    			active_item_end=>"</FONT></I></B>\n", 

				indent=>20 
			}, 

			0=>{
    			inactive_item_start=>"<FONT SIZE=\"5\">",
    			inactive_item_end=>"</FONT>", 
				text_placeholder=>"<IMG
    								SRC=\"<text>.gif\".gif>", 
				link_args=>"onmouseover='javascript
    											thingie'", 
			},
			1=>{ indent=>10 } };

    Try it like this: 
		my ($main)=HTML::Widgets::Menu->new(
    				format=>\%format,
					menu=>\@menu, 
					home=>"/users/frankie");

    When you want to request the html that shows the menu you must
    call the show funcion. It will build it using home, format and
    menu. The final links will always be related to the current URL.

    The show function also returns a usefull thing: the active items
    of the menu. In the former example if the user is in the url:
    "movies.html" it will return a reference to a list like this:
    "my_links"=>"links" "movies I like "=>"links/movies.html" 
    so you can know the path of the currem item. Now you can add the keys
    of it to the title for example.

 	%   my ($menu,$active)=$main->show();
	<% $menu %>

AUTHOR
    Francesc Guasch-Ortiz frankie@etsetb.upc.es

SEE ALSO
    perl(1). mod_perl