NAME

Apache::NavBarDD - A dynamic double-decker (two level) Navigation Bar

SYNOPSIS

    use Apache::NavBarDD;
    $Apache::NavBarDD::myBar = Apache::NavBarDD->new;

DESCRIPTION

The NavBarDD package provides a dynamic navigation bar along the lines of the NavBar module described in Lincoln Stein's and Doug MacEachern's "Writing Apache Modules with Perl and C". It goes one step further in allowing double-decker (two-level) navigation bars, where the selection in the first level (the master bar) determines the contents of the second level (the vassal bar).

The module provides an object oriented API to allow for easy customisation. The navigation bar is an object that must be created prior to use, for example in a server start-up file, according to the contents of a special configuration file.

The main features of the module are:

  • Allows both single and two level navigation bars.

  • It can be used to endow existing HTML pages with a navigation bar, or it can be called from mod_perl modules.

  • Provides a full object oriented interface.

OVERVIEW

To create a new NavBarDD object with the default style:

    use Apache::NavBarDD;
    $Apache::NavBarDD::myBar = Apache::NavBarDD->new;

To create a new NavBarDD object preceded by a header image located in /images and using a specified stylesheet located in /styles:

    use Apache::NavBarDD;
    $Apache::NavBarDD::myBar = 
    Apache::NavBarDD->new(
        before => '<img src=/images/TOP.gif align="center">',
        style => '<link type="text/css" rel="stylesheet" href="/styles/navbar.css"/>'
        );

A navigation bar is usually constructed once and painted each time a page is returned to the browser. Construction refers to reading the configuration file and creating the corresponding bar structure. Painting refers to actually rendering the bar taking into account the currently displayed document etc. The bar is cached after construction; it is reconstructed each time its configuration file changes.

CONFIGURATION

One way to create the bar is to place the navigation bar's construction code in a mod_perl-related initialisation file. Assuming that this file is /conf/startup.pl, place the following in Apache's configuration file:

    PerlRequire      conf/startup.pl
    PerlFreshRestart On

You must of course configure the navigation bar in Apache's configuration files:

    PerlModule Apache::NavBarDD
    <Location /site>
        SetHandler  perl-script
        PerlHandler $Apache::NavBarDD::myBar
        PerlSetVar  NavConf conf/navigation.conf
    </Location>

In this way, all HTML documents residing under /site are endowed with a navigation bar.

The bar can also be called from inside a mod_perl module:

    use Apache::NavBarDD;

    my $navbar = $Apache::NavBarDD::myBar;
    my $style = $navbar->style;
    $r->print("<HTML>\n<HEAD>\n<TITLE>mod_perl module</TITLE>\n$style</HEAD>\n<BODY>");
    $r->print($navbar->paint($r)); # $r is the request object

You have to make sure that the NavConf variable is visible in the module you are using the navigation bar. The variable points to the navigation bar's configuration file, which is something like this:

    # Configuration file for the navigation bar
    /site/Home/                             Home
    /site/SectionA/                         First Section
    /site/SectionB/                         Second Section
    /site/SectionB/SubSectionA/             Second Section A
    /site/SectionB/SubsectionB/             Second Section B
    /site/SectionB/SubsectionC/foo.html     Section B foo
    /site/SectionC/bar                      bar
    /site/SectionC/foo/                     Section C foo
    /site/SectionC/bar/                     Section C bar

The configuration file comprises comments and lines of the form:

    URI    label

Each URI is the location of the content labelled by the corresponding label. Lines starting with # are comments.

If the URI points to a directory it must end with a slash (/). Note that this is different from the original NavBar configuration file, where the trailing slash is not necessary; it is due to the added complexity of interpreting a two-levels structure.

The structure is interpreted by comparing each line to the previous one. The comparison takes into account a specified level of directories for the master bar, and that level plus one for the vassal bar. The default level is 2, so that if the site's root is /site, everything in /site/Master/, where Master is a valid path element, belongs to the master bar, except everything in /site/Master/Vassal/, where Vassal is a valid path element: that belongs to the vassal bar.

This simple interpretation allows us to preselect an item in the vassal bar. Consider the following segment of a configuration file:

    /site/FAQ/A/C.html                          FAQ
    /site/FAQ/B/B.html                          B
    /site/FAQ/A/C.html                          C
    /site/FAQ/D/D.html                          D

When selecting the FAQ tab, the user automatically gets C.html as body, with C selected in the vassal bar.

If no vassals at all are found we get a one-level navigation bar.

CONSTRUCTOR

new Apache::NavBarDD [ OPTIONS ]

This is the constructor for a new Apache::NavBarDD object.

OPTIONS are passed in a hash-like fashion, using key and value pairs. Possible options are:

style - An HTML style element describing the navigation bar's style. The navigation bar uses the following style classes:

  • td.master-active - Master bar, selected item.

  • td.master-normal - Master bar, normal item.

  • td.vassal-active - Vassal bar, selected item.

  • td.vassal-normal - Vassal bar, normal item.

  • a.master Anchors in master bar.

  • a.vassal Anchors in vassal bar.

The default value of style is:

 <style>
 td.master-active {
     height: 2ex;
     font-family: helvetica,arial;
     font-weight: bold;
     font-size: 10pt;
     color: #003366;
     background-color: #FFFFCC;
     text-align: center
 }

 td.master-normal {
     height: 2ex;
     font-family: helvetica,arial;
     font-size: 10pt;
     color: #FFFFFF;
     background-color: #006633; 
     text-align:center;
 }

 td.vassal-active {
     height: 4ex; 
     font-family: helvetica,arial; 
     font-size: 7pt; 
     color: #006633; 
     background-color: #FFFFFF;
 }

 td.vassal-normal {
     height: 4ex; 
     font-family: helvetica, arial; 
     font-size: 7pt; 
     color: #006633; 
     background-color: #FFFFCC; 
 }

 a.master {
     text-decoration: none;
     color: #FFFFFF;
 }

 a.vassal {
     text-decoration: none;
     color: #006633;
 }

 </style>

master_table_atts - The HTML table attributes that apply to the master table. The default are:

CELLSPACING="0" CELLPADDING="1" BORDER="0" WIDTH="600"

vassal_table_atts - The HTML table attributes that apply to the vassal table. The default are:

CELLSPACING="0" CELLPADDING="0" BORDER="0" WIDTH="100%" ALIGN="CENTER"

master_padding - The HTML td element that is used as padding between two cells in the master table. The default is:

<TD BGCOLOR="#FFFFFF" WIDTH="2"><FONT SIZE="2">&nbsp;</FONT></TD>

vassal_padding - The HTML td element that is used as padding between two cells in the vassal table. The default is:

<TD NOWRAP BGCOLOR="#FFFFCC" WIDTH="10"> <FONT SIZE="2" COLOR="#336699">&nbsp;|&nbsp; </FONT></TD>\n

before - An HTML element providing a header to be inserted before the navigation bar. Default is empty.

after - An HTML element providing a header to be inserted after the navigation bar. Default is empty.

bottom - A flag specifying, if set, to output the navigation bar on the bottom as well as on the top of the page. Unset by default.

depth - The depth of the directory hierarchy that is taken into account when building the master bar; directories one level further down are taken into account for the vassal bar. Default is 2.

METHODS

style ( [ STYLE ] )

If called without an argument, returns the bar's current style. STYLE is an HTML style element describing the navigation bar's style.

master_table_atts ( [ TABLE_ATTS ] )

If called without an argument, returns the current master table's attributes. TABLE_ATTS is the HTML table attributes that apply to the master table.

vassal_table_atts ( [ TABLE_ATTS ] )

If called without an argument, returns the current vassal table's attributes. TABLE_ATTS is the HTML table attributes that apply to the vassal table.

master_padding ( [ PADDING_ATTS ] )

If called without an argument, returns the current master table's padding. PADDING_ATTS is the HTML td element that is used as padding between two adjacent cells in the master table.

vassal_padding ( [ PADDING_ATTS ] )

If called without an argument, returns the current vassal table's padding. PADDING_ATTS is the HTML td element that is used as padding between two adjacent cells in the vassal table.

made ( )

Returns the constructed bar.

paint ( )

Paints and returns the constructed bar. Used in the mod_perl modules that want to display it.

before ( [ ELEMENT ] )

If called without an argument, returns the header that is currently inserted before the navigation bar. ELEMENT is an HTML element providing a header to be inserted before the navigation bar.

after ( [ ELEMENT ] )

If called without an argument, returns the header that is currently inserted after the navigation bar. ELEMENT is an HTML element providing a header to be inserted after the navigation bar.

bottom ( [ FLAG ] )

If called without an argument, returns the current value of the bottom option. If FLAG is true the navigation bar is displayed in the bottom as well as on top of the page.

AUTHOR

Panos Louridas <louridas@acm.org>.

SEE ALSO

Stein, L., MacEachern, D., (1999): "Writing Apache Modules with Perl and C", O'Reilly & Associates, Sebastopol, CA, pp. 113--122. The original Apache::NavBar.

Stein, L. D., (1998): "A Dynamic Navigation Bar", The Perl Journal, Issue 12, Volume 3, Winter.

CREDITS

Lincoln Stein <lstein@cshl.org>, Doug MacEahern <dougm@pobox.com> - for writing the original Apache::NavBar module. Lincoln gave permission to distribute this on CPAN.

COPYRIGHT

Copyright (c) 2002-2003 Panagiotis Louridas <louridas@acm.org>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.