Apache-SetWWWTheme
view release on metacpan or search on metacpan
SetWWWTheme.pm view on Meta::CPAN
# SetWWWTheme.pm - perl source for Apache::SetWWWTheme
#
# Copyright (C) 2000 Chad Hogan <chogan@uvastro.phys.uvic.ca>
# Copyright (C) 2000 Joint Astronomy Centre
#
# All rights reserved.
#
# This file is part of Apache::SetWWWTheme
#
# 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.
package Apache::SetWWWTheme;
use strict;
use Carp;
use vars qw($VERSION);
use Apache::Constants ':common';
use Apache::File ();
use HTML::WWWTheme;
$VERSION = '1.06';
##################################################
my $r; # request object variable
my $Theme; # Theme object!
my $blankgif = ""; # the location of the blank gif. or png. Whatever.
my $allowbodymod; #
my ($nextlink, $lastlink, $uplink, $BGCOLOR); # vars we use to customize the page
my ($alink, $link, $text, $vlink); # <BODY> stuff
my @infolinks; # array to contain the links in the infobar
my $usenavbar; # flag that tells if we use the top and bottom navbar
my $serverconfig; # name of the server config file
my $localconfig; # name of the local config file
my $shortlocal; # short name of local config file
my $allowsidebartoggle; # flag set by server to allow turning on/off the sidebar
my $allowBGCOLOR; # flag set by the server to allow the local config to
# change the background color. HTML pages can *never*
# override the background color.
my $nosidebar; # flag set to turn off the sidebar. $allownosidebar
# must be set to use this.
my $allowbgpicture; # let us put in a background gif or something. I put this in
# so you could kill off animated bgs and other junk
my $bgpicture; # used to set the bg picture for the produced page.
#
my $allowsidebarmod; # sidebar modification variables...
my $sidebartop; #
my $sidebarmenutitle; #
my @sidebarmenulinks; #
my $nosidebarextras; #
my $morelinkstitle; #
my $sidebarsearchbox; #
my $sidebarcolor; #
my $sidebarwidth; #
my $searchtemplate; # a search template
my $topbar; #
my $bottombar; #
my @topbottomlinks; #
my $filename; #
my $printable; #
my $printabletag = "printable"; # what we tack on for the QUERY_STRING GET data
my $printableuri; #
##################################################
sub handler
{
$r = shift; # get request object
$Theme = new HTML::WWWTheme(); # grab our theme object.
my $content_type;
$content_type = $r->content_type() || return DECLINED;
# we only want to deal with html files
return DECLINED unless $content_type eq 'text/html';
$filename = $r->filename; # get the filename we're looking for
unless (-e $r->finfo) # Apache does a stat() and puts the results in finfo,
# this is faster than testing the filename.
{
$r->log_error("File does not exist: $filename");
return NOT_FOUND;
}
unless (-r _) # after finfo is used, it goes to perl's _ filehandle
{
$r->log_error("File permissions deny access: $filename");
return FORBIDDEN;
}
$r->send_http_header;
# reset all my vars.
# For now, it works, and I think we're ok for namespace issues since all vars have lexical scope.
# This part is here to let you configure defaults if you want to unleash this module on unsuspecting
# people that don't/won't put in a server config file or something. I dunno. If you can use it,
# great. If not, no big deal.
undef $serverconfig;
undef $localconfig;
$shortlocal = "LookAndFeelConfig"; # a default, if nothing else is set.
undef $nextlink;
SetWWWTheme.pm view on Meta::CPAN
{
my $fh; # grab a filehandle
unless ($fh = Apache::File->new($filename))
{
$r->log_error("Couldn't open $filename for reading: $!");
return SERVER_ERROR;
}
$r->register_cleanup(sub {close $fh}); # register a cleanup for the filehandle
local $/ = undef; # Read in the whole schmear.
while (<$fh>)
{
s|<A\W+HREF[^>]+>||ig; # wipes out our links
s|</A>||ig;
my $return = $r->uri;
s|</BODY>|<A HREF=\"$return\"><H6>return...</H6></A></BODY>|ig;
$r->print($_); # dumps the results to apache
}
return 1; # and tell it we finished.
}
1;
# May a thousand locusts descend upon pod.
=head1 NAME
Apache::SetWWWTheme - Standard theme generation, including sidebars and navigation bars
=head1 SYNOPSIS
Within the httpd.conf or other apache configuration file:
<Location /some/subtree>
SetHandler perl-script
PerlHandler Apache::SetWWWTheme
PerlSetVar CONFIG_FILE /WWWroot/configfile
</Location>
=head1 REQUIREMENTS
This module requires the Apache server, available from
http://www.apache.org; the Apache B<mod_perl> module, which is
available from http://perl.apache.org, and the B<module
HTML::WWWTheme>, by Chad Hogan (version 1.06 or greater) which may
be found at CPAN.
=head1 DESCRIPTION
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.
=item Server-level configuration
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.
=item Module directives
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."
=item @ALINK
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;
=item @ALLOWBODYMOD
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;
=item @ALLOWBGCOLOR L<Deprecated>
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;
=item @ALLOWBGPICTURE L<Deprecated>
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;
=item @ALLOWNOSIDEBAR L<Deprecated>
Server configuration only. I<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;
=item @ALLOWSIDEBARTOGGLE
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;
=item @ALLOWSIDEBARMOD
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;
=item @BGCOLOR
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;
=item @BGPICTURE
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;
=item @BLANKGIF
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;
=item @BOTTOMBAR
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;
=item @INFO
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>;
=item @LINK
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;
=item @LOCALCONFIGFILE
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;
=item @MORELINKSTITLE
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).
=item @NAVBAR
( run in 2.456 seconds using v1.01-cache-2.11-cpan-d8267643d1d )