NAME

HTML::WWWTheme - Standard theme generation, including sidebars and navigation bars

SYNOPSIS

 use HTML::WWWTheme;
 my $Theme = new HTML::WWWTheme(@args);

REQUIREMENTS

Nothing special -- Perl 5 or newer.

DESCRIPTION

HTML::WWWTheme is a module that creates a standard sidebar and implements local colour conventions. It is used by the Apache::SetWWWTheme module to enforce this through the server. In fact, the code in this module was originally contained within the SetWWWTheme module, but at the suggestion of Tim Jenness, I separated this module to allow CGI programs to create standard pages that would fit in with the static pages that are automatically rewritten by the Apache module. So, static pages in the web tree are filtered through Apache::SetWWWTheme, and CGI-generated pages are generated with the help of HTML::WWWTheme. In this manner, a consistent look and feel can be maintained in all pages. Any changes in the structure of WWWTheme are automatically reflected in both the CGI-generated and static pages.

The new() function will return a reference to a Theme object. It will accept an array of arbitrary length as arguments. Each element of this array must be a fully qualified path to a configuration file.

Configuration is accomplished in three ways. First, one may pass arguments to the new() function. These arguments must be fully qualified paths to a configuration file. The syntax of the directives in this file is simple:

 @DIRECTIVE=value;
  

for example,

 @BGCOLOR=#FFFFFF;

or, in the case of a directive that accepts a list, the values are comma-separated and semi-colon terminated. Escaped semi-colons will be transformed into semi-colons, and will not terminate the directive.

 @DIRECTIVE=value1, value2, value3;

 @DIRECTIVE=value1, value2\; still going, value3;

In the second example, the value2\; will be replaced with value2; in the parsed text.

for example,

 @INFO=<A HREF="here.html">Here</a>, <A HREF="there.html">There</a>;

Second, the GetConfiguration() function may be passed a list of full-paths to configuration files. The GetConfiguration() function will parse these files and set the appropriate values.

Finally, one may use methods to directly change the settings of the page before it is produced. This is the recommended method, because it is the most intuitive and the easiest to figure out when you're trying to figure out someone else's code. I use these methods extensively in my Apache::SetWWWTheme module.

METHODS

The following are all the methods that may be used to control the behaviour of the module.

GetConfiguration()

This method takes the names of configuration files as arguments, and parses them one by one. The configuration files contain a series of directives of the form

 @DIRECTIVE=value;

or, in the case of a list-value (for example, with the infolinks that make up the links on the sidebar under "More Links" or "More Info")

 @DIRECTIVE=value1, value2, value3;

Valid directives are listed, along with the corresponding method that performs the same method:

 @BLANKGIF          (see SetBlankGif() )
 @NAVBAR            (see SetUseNavBar() )
 @NEXTLINK          (see SetNextLink() )
 @LASTLINK          (see SetLastLink() )
 @UPLINK            (see SetUpLink() )
 @BGCOLOR           (see SetBGColor() )
 @BGPICTURE         (see SetBGPicture() )
 @BACKGROUND        (see SetBGPicture() )
 @ALINK             (see SetALink() )
 @LINK              (see SetLink() )
 @VLINK             (see SetVLink() )
 @SIDEBARTOP        (see SetSideBarTop() )
 @SIDEBARMENUTITLE  (see SetSidebarMenuTitle() )
 @SIDEBARSEARCHBOX  (see SetSideBarSearchBox() )
 @SIDEBARCOLOR      (see SetSideBarColor() )
 @SIDEBARWIDTH      (see SetSideBarWidth() )
 @NOSIDEBAREXTRAS   (see SetNoSideBarExtras() )
 @MORELINKSTITLE    (see SetMoreLinksTitle() )
 @INFO              (see SetInfoLinks() )
 @SIDEBARMENULINKS  (see SetSideBarMenuLinks() )

MakeFooter()

Returns a footer to end the document. Should be the last part of a dynamically generated HTML page. See the example.

MakeHeader()

Returns the header to the page. Should be the first part of a dynamically generated HTML page. See the example.

MakeNavBar()

Returns a "previous/up/next" navigation bar. This bar is designed to be sandwiched between the Header and the main body, and then later on between the end of the main body and the Footer. See the example.

SetNextLink()

Sets the "Next" link on the top/bottom nav bars. Valid entries must be in the form of an HTML link,

 $Theme->SetNextLink('<A HREF="http://somewhere.com">somewhere</a>');

SetLastLink()

Sets the "Last" or "Previous" link on the top/bottom nav bars. Valid entries must be in the form of an HTML link,

 $Theme->SetLastLink('<A HREF="http://here.com">here</a>');

SetUpLink()

Sets the "Up" link on the top/bottom nav bars. Valid entries must be in the form of an HTML link,

 $Theme->SetUpLink('<A HREF="http://there.com">there</a>');

SetBGColor()

Sets the background color for the page generated. Valid entries must be in the form of a hex color code,

 $Theme->SetBGColor("#CCFFFF");

SetBGPicture()

Sets the background image for the page generated. Valid entries must be in the form of an absolute URL or URI.

 $Theme->SetBGPicture("/WWW/images/wallpaper.gif");

SetALink(), SetLink(), SetVLink()

Sets the [a|v]link color for the <BODY> tag. Valid entries must be in the form of a hex color code.

 $Theme->SetALink("#FFCCFF");
 $Theme->SetVLink("#FFCCFF");
 $Theme->SetLink ("#FFCCFF");

SetMoreLinksTitle()

Sets the "More links" title on the sidebar. By default it says "More links", but you may want to change it something else.

 $Theme->SetMoreLinksTitle("More useful links");

SetNoSideBarExtras()

If this is true, it turns off the sidebar extras -- those parts of the sidebar that aren't in the "SidebarMenuLinks" bit.

 $Theme->SetNoSideBarExtras("1");

SetHTMLStartString()

Sets the HTML starting string. This string should include the <HTML> opening tag, the <HEAD></HEAD> tags (and anything inbetween). Essentially, it should contain everything before the <BODY> tag. If you are using this module for a CGI program, you should probably include the usual Content-Type: text/html sort of thing.

 $Theme->SetHTMLStartString("<HTML><HEAD><TITLE>This is my page.</TITLE></HEAD>");

SetHTMLEndString()

Sets the HTML ending string. This string should contain everything after the </BODY> tag, including such things as </HTML>.

 $Theme->SetHTMLEndString("</HTML>");

SetPrintableName()

Sets the URL that is used to produce a printable version of the page. This is used to generate the small "click here to produce a printable version" link on the themed page. How this is implemented is left to the caller. Apache::SetWWWTheme produces an un-themed page, with all the link tags stripped out to discourage people from browsing in the printable pages and thus subverting the theming.

 $Theme->SetPrintableName("/printable/path/to/file.html");

SetText()

Sets the text color for the <BODY> tag. Valid entries must be in the form of a hex color code.

 $Theme->SetText("#000000");

SetSideBarColor()

Sets the color of the generated sidebar. Valid entries must be in the form of a hex color code.

 $Theme->SetSideBarColor("#FFCCFF");

SetSideBarWidth()

Sets the width of the sidebar in pixels. The default is 150.

 $Theme->SetSideBarWidth("120");

SetBlankGif()

Sets the location of the blank gif. A blank gif (blank.gif) is included in the distribution of this package. Valid entries must be in the form of a URL or URI pointing to this file.

 $Theme->SetBlankGif("/WWW/images/blank.gif");

SetInfoLinks()

Sets the value of the "info links". Info links are designed to be user-configurable and fall under the "More Links" or "More information" section of the sidebar. Valid entries must be in the form of a reference to an array of valid links.

 @array = ('<a href="here.html">here</a>', '<a href="there.html">there</a>');
 $Theme->SetInfoLinks(\@array);

SetSideBarTop()

Sets the name appearing at the top of the sidebar. This may be a link, if desired. Valid entries are strings.

 $Theme->SetSideBarTop('<A HREF="/">My Webserver</a>');

SetSearchTemplate()

Sets the template to insert into the HTML for the side searchbox. It should be self-contained HTML with the appropriate form methods etc. to interface with your local search engine. Here is an example of a template:

 <B>Search JAC</B><BR><HR>
 <DIV align="center">
 <form method="POST" action="/cgi-bin/isearch">
 <input name="SEARCH_TYPE" type=hidden  value="ADVANCED">
 <input name="HTTP_PATH" type=hidden value="/WWW"> 
 <input name="DATABASE" type=hidden value="webindex">
 <input name="FIELD_1" type=hidden value="FULLTEXT">
 <input name="WEIGHT_1" type=hidden value= "1">
 <input name="ELEMENT_SET" type=hidden value="TITLE">
 <input name="MAXHITS" type=hidden value="50">
 <input name="ISEARCH_TERM" size="14" border="0">
 </form>
 </DIV>
 <H6><a href="http://www.yoursite.edu/search.html">More searching....</a></h6>

Your template must be customized as appropriate for your engine, of course. This template should be passed to the SetSearchTemplate function as one big string.

SetSideBarMenuLinks()

Sets the value of the main sidebar links. Valid entries must be in the form of a reference to an array of valid links.

 @array = ('<a href="here.html">here</a>', '<a href="there.html">there</a>');
 $Theme->SetSideBarMenuLinks(\@array);

SetSideBarMenuTitle()

Sets the name of the main sidebar links. Valid entries must be in the form of a string,

 $Theme->SetSideBarMenuTitle("Main Sections");

SetSideBarSearchBox()

Sets the state of the sidebar searchbox. If this value is set to anything true (in the perl sense), the searchbox will appear on the sidebar.

 $Theme->SetSideBarSearchBox("1");

SetUseNavBar()

Sets the state of the top/bottom navbars. If this value is set to anything true (in the perl sense), the top/bottom navbars will be place on the page. These navbars will be created with the values set in the Set__Link() methods.

 $Theme->SetUseNavBar("1");

SetTopBottomLinks()

Sets the links used in the top/bottom link bars. It takes an array reference as data.

 @array = ('<a href="here.html">here</a>', '<a href="there.html">there</a>');
 $Theme->SetTopBottomLinks(\@array);

StartHTML()

Returns the contents of the string set in SetHTMLStartString. This is mostly just a placeholder for some time in the future when I get around to fully implementing this module to mimic the abilities of some other well-known modules.

 print $Theme->StartHTML();

EndHTML()

Returns the contents of the string set in SetHTMLEndString. This is mostly just a placeholder for some time in the future when I get around to fully implementing this module to mimic the abilities of some other well-known modules.

 print $Theme->EndHTML();

The MakeNavBar() function may be used to create the top/bottom navigation bar. This bar contains the previous/up/next links. It takes no arguments, but uses the [next|last|up]link keys in the hash.

Finally, the MakeFooter() function is used to end the html file. This function is absolutely necessary, as the page won't render without it! The tables will not be finished, and very few browswers can deal with this.

Here is a simple but functional example. Notice that there are no <BODY> tags. The header and footer take care of this. Write your HTML as if you were writing between the <BODY> and </BODY> tags.:

 #!/usr/bin/perl -w

 use strict;
 use HTML::WWWTheme;

 # read in a few defaults
 my $Theme = new HTML::WWWTheme("/WWW/LookAndFeel", "/home/chogan/Lookandfeel");

 # set a few things by hand
 $Theme->SetBlankGif("/WWW/images/blank.gif");
 $Theme->SetBGColor("#FFFFFF");
 $Theme->SetHTMLStartString("<HTML><HEAD><TITLE>My Example.</TITLE></HEAD>");
 $Theme->SetHTMLEndString("</HTML>");

 # make the header, navbar, body, navbar, footer.  
 print $Theme->StartHTML();
 print $Theme->MakeHeader();
 print $Theme->MakeTopBottomBar();
 print $Theme->MakeNavBar();
 print "This is the body of my file.  Isn't it groovy?";
 print $Theme->MakeNavBar();
 print $Theme->MakeTopBottomBar();
 print $Theme->MakeFooter();
 print $Theme->EndHTML();
 exit 0;

SEE ALSO

Apache::SetWWWTheme

AUTHOR

Copyright (C) 2000 Chad Hogan (chogan@uvastro.phys.uvic.ca). Copyright (C) 2000 Joint Astronomy Centre

All rights reserved. HTML::WWWTheme is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 or (at your option) any later version.

HTML::WWWTheme is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with HTML::WWWTheme; see the file gpl.txt. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

cpanm HTML::WWWTheme

perl -MCPAN -e shell
install HTML::WWWTheme