Apache::SetWWWTheme - Standard theme generation, including sidebars and navigation bars
Within the httpd.conf or other apache configuration file:
<Location /some/subtree> SetHandler perl-script PerlHandler Apache::SetWWWTheme PerlSetVar CONFIG_FILE /WWWroot/configfile </Location>
This module requires the Apache server, available from http://www.apache.org; the Apache mod_perl module, which is available from http://perl.apache.org, and the module HTML::WWWTheme, by Chad Hogan (version 1.06 or greater) which may be found at CPAN.
The SetWWWTheme module provides a server-based look-and-feel configuration for an entire webtree. This module allows the server to introduce a common navigation side-bar. It also provides mechanisms to control the background color and background picture for a web page.
This is implemented in a layered fashion. The module first reads the server directives. This sets defaults, and decides what users may have control over. Server directives may only be set by the webmasters. Following these, the module reads local directives. These directives are specified in a file, and will affect all files in that same directory, as well as subdirectories underneath it. They are set at the user-level, and so they are subject to the constraints imposed by the server directives. Finally, the module parses the individual HTML files. Within a file, an HTML authour may override the settings given in the local directives. Again, these are subject to the constraints of the server directives.
Please note that you are not required to change anything in your pages. Your unmodified HTML will work just fine with this module. You are required to make changes only if you wish to take advantage of the features offered.
At the server level, the webmaster has full access to all directives. These tags are specified in a file that is set in the httpd.conf file. If a webmaster would like his/her subtree to use the module, a <LOCATION> tag is used to activate the module. A PerlSetVar is used to tell the module the name of the configuration file. Here is an example:
<Location /> SetHandler perl-script PerlHandler Apache::SetWWWTheme PerlSetVar CONFIG_FILE /WWW/ServerConfig </Location>
This example will use the module for the entire document tree. The CONFIG_FILE variable is used by the module to look for the file that controls the defaults for the entire site. Please note that CONFIG_FILE takes the full path to the file name on the file-system -- do not list this file relative to the document root.
The creation of printable versions of pages has been greatly simplified. No longer is any configuration required -- the page is automatically generated using a GET method. Adding "?printable" to a URI will cause the page to be displayed in a printable manner, for example.
The server-level configuration is primarily to set defaults. It is also to set restrictions on the configurability of the rest of the site. The server-level configuration decides whether or not individual authours will be permitted to, for example, change the background colour and background image of their web pages.
Once again, the server configuration may make use of all of the following directives. The server then decides which of these the users may override.
Local configuration
Any authour may create a text file containing directives. The name of this file is set by the server directive @LOCALCONFIGFILE, with a default of LookAndFeelConfig. This file will affect all HTML files within that directory, as well as any subdirectories. These directives are subject to the restrictions placed by the server-level configuration. This file is intended to be used to set common settings for a tree. For example, one may wish to set the background colour for an entire tree to white. Then a @BGCOLOR=#FFFFFF; directive in the local config file. file will set this. Directives that are explicitly set override the server settings (if allowed). Otherwise, the server's settings persist.
Individual file configuration
This is the final level of configuration. Any authour may embed directives within a comment tag in an HTML file, as long as this tag appears before the <BODY> tag. Directives that are explicitly set override the local configuration and/or server settings (if allowed). Otherwise, the local settings and the server settings persist.
Directives consist of a series of tags within a text file, or within an html comment block before the <BODY> tag. Valid directive tags are always terminated with a semicolon. For tags that accept lists as values, elements are separated by commas. Semicolons may be escaped within a tag. Any semicolon preceded by a backslash will be considered text, and will not terminate the directive. The final text will have the escaped semicolon replaced with a bare semicolon.
@DIRECTIVE=Some string of text\; semicolons are escaped.;
The above directive would set a value of "Some string of text; semicolons are escaped."
HTML and local configuration subject to server configuration This tag is used to set the HTML BODY setting "alink". This is the active link color. It is subject to the setting of the @ALLOWBODYMOD tag. If @ALLOWBODYMOD is set to a non-zero value, @ALINK will set this attribute in the page. Here is an example:
@ALINK=#FF00FF;
Server configuration only This tag is used to allow or disallow users from changing BODY elements. These include "alink", "vlink", "link", "text", "bgcolor", and "background" items using the directives @ALINK, @VLINK, @LINK, @TEXT, @BGCOLOR and @BGPICTURE respectively. If it is set to a non-zero value, the user's directives will be read and used. Otherwise, user settings will be ignored, and only the server configuration values will be used in creating the <BODY> tag for the page. Here is an example:
@ALLOWBODYMOD=1;
Server configuration only This tag is used to allow or disallow users from changing the background colours of their pages. By default it is set to 0, meaning that users are not allowed to change their background colours. If it is not set to a non-zero value, only the server's @BGCOLOR directives will be used. This directive is deprecated. Administrators should use @ALLOWBODYMOD instead. Here is an example:
@ALLOWBGCOLOR=0;
Server configuration only This tag is used to allow or disallow users from changing the background picture of their pages. By default it is set to 0, meaning that users are not allowed to change their background colours. If it is not set to a non-zero value, only the server's @BGPICTURE directives will be used. This directive is deprecated. Administrators should use @ALLOWBODYMOD instead Here is an example:
@ALLOWBGPICTURE=0;
Server configuration only. Use @ALLOWSIDEBARTOGGLE instead. This tag is used to allow or disallow users from turning on/off the left sidebar. By default, it is set to 0, meaning that users are not allowed to toggle the sidebar. If is not set to a true value (1 is recommended), only the server's @NOSIDEBAR directives will be used. Here is an example:
@ALLOWNOSIDEBAR=0;
Server configuration only This tag is used to allow or disallow users from turning on/off the left sidebar. By default it is set to 0, meaning that users are not allowed to toggle the sidebar. If it is not set to a true value (1 is recommended), only the server's @NOSIDEBAR directives will be used. Here is an example:
@ALLOWSIDEBARTOGGLE=0;
Server configuration only This tag is set to allow users to modify the characteristics of the sidebar. If this flag is set to anything non-zero, users may change the title at the top of the sidebar with the @SIDEBARTOP directive, the menu title above the menulinks with @SIDEBARMENUTITLE, the menu links with the @SIDEBARMENULINKS. Users are also allowed to change the title of the "More links" section to something else. They may also then switch the sidebar search box on or off with @SIDEBARSEARCHBOX. Here is an example:
@ALLOWSIDEBARMOD=0;
HTML and local configuration subject to server configuration This tag may be used to set the background colour of a page (or a group of pages, in the case of local and server configuration). @BGCOLOR is subject to the server directive @ALLOWBGCOLOR. If @ALLOWBGCOLOR is not set to a non-zero value by server directives, the @BGCOLOR directive will have no effect whatsoever when used in local and HTML configuration. @BGCOLOR will always work when used in a server configuration. Here is an example:
@BGCOLOR=#FFFFCC;
HTML and local configuration subject to server configuration This tag may be used to set the background image of a page (or a group of pages, in the case of a local and server configuration. @BGPICTURE is subject to the server directive @ALLOWBGPICTURE. If @ALLOWBGPICTURE is not set to a non-zero value by server directives, the @BGPICTURE directive will have no effect whatsoever when used in local and HTML configuration. @BGPICTURE will always work when used in a server configuration. Here is an example:
@BGPICTURE=/images/paperbackground.gif;
Server configuration only This tag is used to specify the location of the blank.gif image file. This image is a 1x1 transparent gif that is used to space the tables properly. This should be set to the path of the image file with respect to the server's document root. So, if the apache document root is /WWW and the file is /WWW/images/blank.gif then the proper use of this tag would be:
@BLANKGIF=/images/blank.gif;
Valid in HTML, local configuration, and server configuration. This tag is used to toggle a navigation bar at the bottom of the page. This bottom navigation bar contains the links defined with the @TOPBOTTOMLINKS directive. If @BOTTOMBAR is set to something non-zero, it will appear in the document.
@BOTTOMBAR=1;
Valid in HTML, local configuration, and server configuration This tag is used to customize the "More links" section in the left sidebar. To use this tag, supply a comma-separated list of valid HTML links terminated with a semi-colon. The links supplied will appear in the "More Links" section. Here is an example:
@INFO=<A HREF="http://www.sun.com">Sun</a>, <A HREF="http://www.slashdot.org">Slashdot</a>;
Valid in HTML, local configuration, and server configuration This tag is used to set the HTML BODY setting "link". This is the normal link color. It is subject to the setting of the @ALLOWBODYMOD tag. If @ALLOWBODYMOD is set to a non-zero value, @LINK will set this attribute in the page. Here is an example:
@LINK=#FFFFFF;
Valid only in server configuration. This directive tells the module what file to look for when it looks for local configuration files. The default is LookAndFeelConfig. It may be set to any valid filename.
@LOCALCONFIGFILE=LOOKANDFEEL;
Valid in HTML, local configuration, and server configuration, subject to the server's configuration (@ALLOWSIDEBARMOD must be on in the server's configuration in order for local and HTML directives to be obeyed).
Valid in HTML, local configuration, and server configuration This tag gives the switch setting for the top and bottom navigation bars. The top and bottom navigation bars are also known as the "previous/up/next" bars. If this is set to 0, the top and bottom bars are not shown. If this is set to a non-zero value (1 is recommended) then the bars will be shown. If this switch is non-zero, it is recommended that the @NEXTLINK, @UPLINK, and @LASTLINK directives be set. Here is an example:
@NAVBAR=0;
Valid in HTML, local configuration, and server configuration These tags control the behaviour of the top navigation bar. These tags should be set in conjunction with the @NAVBAR directive. They should contain valid text and linking information. Here is an example:
@NEXTLINK=<A HREF="/pages/page3.html">Page 3</a>; @UPLINK=<A HREF="/pages/toc.html">Table of contents</a>; @LASTLINK=<A HREF="/pages/page1.html">Page 1</a>;
HTML and local configuration subject to server configuration This tag may be used to turn off the left sidebar by setting it to a non-zero value. This tag is subject to the server directive @ALLOWNOSIDEBAR. If the server configuration has not set the @ALLOWNOSIDEBAR to a non-zero value, the @NOSIDEBAR directive will have no effect whatsoever. Here is an example:
@NOSIDEBAR=1;
HTML and local configuration subject to server configuration This tag is used to set the color of the sidebar. Local and HTML configuration is subject to the server directive @ALLOWSIDEBARMOD. Here is an example:
@SIDEBARCOLOR=#CCCCCC;
HTML and local configuration subject to server configuration. This tag is used to set the width of the sidebar in pixels. Local and HTML configuration is subject to the server directive @ALLOWSIDEBARMOD.
@SIDEBARWIDTH=150;
HTML and local configuration subject to server configuration This tag is used to set the searchbox template. It should be a fully-contained HTML chunk that interfaces to the apropriate cgi binary (or whatever you want).
@SEARCHTEMPLATE= <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>;
Don't forget to terminate the template with a semicolon!
HTML and local configuration subject to server configuration This tag is used to set the main menulinks. It is effective in local and HTML configuration if and only if the server configuration has set @ALLOWSIDEBARMOD. It takes a comma-separated list of links, terminated by a semicolon. Here is an example:
@SIDEBARMENULINKS=<A HREF="/WWW/stuff">Some Directory</A>, <A HREF="/WWW/morestuff">Another Directory</A>;
HTML and local configuration subject to server configuration This tag is used to set the title above the menulinks. It is effective in local and HTML configuration if and only if the server configuration has set @ALLOWSIDEBARMOD to a non-zero value. Here is an example of its use:
@SIDEBARMENUTITLE=My Divisions;
HTML and local configuration subject to server configuration This tag is a switch that determines whether or not the sidebar will contain the search box. If it is set to a non-zero value, the search box will appear on the sidebar. It is effective in local and HTML configuration if and only if the server configuration has set @ALLOWSIDEBARMOD to a non-zero value. Here is an example of its use:
@SIDEBARSEARCHBOX=0;
HTML and local configuration subject to server configuration This tag is used to set the title at the top of the sidebar. It is effective in local and HTML configuration if and only if the server configuration has set @ALLOWSIDEBARMOD to a non-zero value. Here is an example of its use:
@SIDEBARTOP=<A HREF="/">Joint Astronomy Centre</a>;
HTML and local configuration subject to server configuration This tag is used to set the HTML BODY setting "text". This is the normal text color. It is subject to the setting of the @ALLOWBODYMOD tag. If @ALLOWBODYMOD is set to a non-zero value, @TEXT will set this attribute in the page. Here is an example:
@TEXT=#000000;
This tag is valid in HTML, local, and server configuration. It is used to toggle the existence of a top navigation bar that contains the links specified in the @TOPBOTTOMLINKS directive. It is similar to the @BOTTOMBAR directive, except it works at the top of the page. Setting @TOPBAR to a non-zero value will turn this navigation tool on in the final produced document.
@TOPBAR=1;
This is valid in HTML, local, and server configuration. It is a comma-separated list of navigation links that will be place in the top and bottom bars as toggled by the @TOPBAR and @BOTTOMBAR directives.
@TOPBOTTOMLINKS=<A HREF="/">JAC</a>, <A HREF="/JCMT">JCMT</a>;
This tag is used to set the HTML BODY setting "vlink". This is the visited-link color. It is subject to the setting of the @ALLOWBODYMOD tag. If @ALLOWBODYMOD is set to a non-zero value, @VLINK will set this attribute in the page. Here is an example:
@VLINK=#FF00FF;
HTML::WWWTheme
Copyright (C) 2000 Chad Hogan (chogan@uvastro.phys.uvic.ca). Copyright (C) 2000 Joint Astronomy Centre
All rights reserved. Apache::SetWWWTheme 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.
Apache::SetWWWTheme 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 Apache::SetWWWTheme; see the file gpl.txt. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Apache::SetWWWTheme, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::SetWWWTheme
CPAN shell
perl -MCPAN -e shell install Apache::SetWWWTheme
For more information on module installation, please visit the detailed CPAN module installation guide.