NAME
CGI::WPM::Globals - Perl module that is used by all subclasses of CGI::WPM::Base for managing global program settings, file system and web site hierarchy contexts, providing environment details, gathering and managing user input, collecting and sending user output.
DEPENDENCIES
Perl Version
5.004Standard Modules
Apache (when running under mod_perl only)
HTTP::Headers 1.36 (earlier versions may work, but not tested)Nonstandard Modules
HTML::Application 0.38SYNOPSIS
Complete Example Of A Main Program
#!/usr/bin/perl
use strict;
use lib '/path/to/extra/perl/modules';
require CGI::WPM::Globals; # to hold our input, output, preferences
my $globals = CGI::WPM::Globals->new( "/path/to/site/files" ); # get input
if( $globals->user_input_param( 'debugging' ) eq 'on' ) { # when owner's here
$globals->is_debug( 1 ); # let us keep separate logs when debugging
$globals->persistant_user_input_param( 'debugging', 1 ); # remember...
}
$globals->user_vrp( lc( $globals->user_input_param( # fetch extra path info...
$globals->vrp_param_name( 'path' ) ) ) ); # to know what page user wants
$globals->current_user_vrp_level( 1 ); # get ready to examine start of vrp
$globals->site_title( 'Sample Web Site' ); # use this in e-mail subjects
$globals->site_owner_name( 'Darren Duncan' ); # send messages to him
$globals->site_owner_email( 'darren@sampleweb.net' ); # send messages here
$globals->site_owner_email_vrp( '/mailme' ); # site page email form is on
require CGI::WPM::MultiPage; # all content is made through here
$globals->move_current_srp( 'content' ); # subdir holding content files
$globals->move_site_prefs( 'content_prefs.pl' ); # configuration file
CGI::WPM::MultiPage->execute( $globals ); # do all the work
$globals->restore_site_prefs(); # rewind configuration context
$globals->restore_last_srp(); # rewind subdir context
require CGI::WPM::Usage; # content is done, log usage though here
$globals->move_current_srp( $globals->is_debug() ? 'usage_debug' : 'usage' );
$globals->move_site_prefs( '../usage_prefs.pl' ); # configuration file
CGI::WPM::Usage->execute( $globals );
$globals->restore_site_prefs();
$globals->restore_last_srp();
if( $globals->is_debug() ) {
$globals->body_append( <<__endquote );
<P>Debugging is currently turned on.</P> # give some user feedback
__endquote
}
$globals->add_later_replace( { # do some token substitutions
__mailme_url__ => "__vrp_id__=/mailme",
__external_id__ => "__vrp_id__=/external&url",
} );
$globals->add_later_replace( { # more token substitutions in static pages
__vrp_id__ => $globals->persistant_vrp_url(),
} );
$globals->send_to_user(); # send output now that everything's ready
if( my @errs = $globals->get_errors() ) { # log problems for check later
foreach my $i (0..$#errs) {
chomp( $errs[$i] ); # save on duplicate "\n"s
print STDERR "Globals->get_error($i): $errs[$i]\n";
}
}
1;The Configuration File "content_prefs.pl"
my $rh_preferences = {
page_header => <<__endquote,
__endquote
page_footer => <<__endquote,
<P><EM>Sample Web Site was created and is maintained for personal use by
<A HREF="__mailme_url__">Darren Duncan</A>. All content and source code was
created by me, unless otherwise stated. Content that I did not create is
used with permission from the creators, who are appropriately credited where
it is used and in the <A HREF="__vrp_id__=/cited">Works Cited</A> section of
this site.</EM></P>
__endquote
page_css_code => [
'BODY {background-color: white; background-image: none}'
],
page_replace => {
__graphics_directories__ => 'http://www.sampleweb.net/graphics_directories',
__graphics_webring__ => 'http://www.sampleweb.net/graphics_webring',
},
vrp_handlers => {
external => {
wpm_module => 'CGI::WPM::Redirect',
wpm_prefs => {},
},
frontdoor => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'frontdoor.html' },
},
intro => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'intro.html' },
},
whatsnew => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'whatsnew.html' },
},
timelines => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'timelines.html' },
},
indexes => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'indexes.html' },
},
cited => {
wpm_module => 'CGI::WPM::MultiPage',
wpm_subdir => 'cited',
wpm_prefs => 'cited_prefs.pl',
},
mailme => {
wpm_module => 'CGI::WPM::MailForm',
wpm_prefs => {},
},
guestbook => {
wpm_module => 'CGI::WPM::GuestBook',
wpm_prefs => {
custom_fd => 1,
field_defn => 'guestbook_questions.txt',
fd_in_seqf => 1,
fn_messages => 'guestbook_messages.txt',
},
},
links => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'links.html' },
},
webrings => {
wpm_module => 'CGI::WPM::Static',
wpm_prefs => { filename => 'webrings.html' },
},
},
def_handler => 'frontdoor',
};DESCRIPTION
This POD is coming when I get the time to write it.
SYNTAX
This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().
UNDOCUMENTED FUNCTIONS AND METHODS
This POD is coming when I get the time to write it.
new([ ROOT[, DELIM[, PREFS[, USER_INPUT]]] ])
initialize([ ROOT[, DELIM[, PREFS[, USER_INPUT]]] ])
clone([ CLONE ]) -- POD for this available below
is_debug([ NEW_VALUE ])
get_errors()
get_error([ INDEX ])
add_error( MESSAGE )
add_no_error()
add_filesystem_error( FILENAME, UNIQUE_STR )
site_root_dir([ NEW_VALUE ])
system_path_delimiter([ NEW_VALUE ])
phys_filename_string( FILENAME )
site_prefs([ NEW_VALUES ])
move_site_prefs([ NEW_VALUES ])
restore_site_prefs()
site_pref( NAME[, NEW_VALUE] )
site_resource_path([ NEW_VALUE ])
site_resource_path_string()
move_current_srp([ CHANGE_VECTOR ])
restore_last_srp()
srp_child( FILENAME )
srp_child_string( FILENAME[, SUFFIX] )
virtual_resource_path([ NEW_VALUE ])
virtual_resource_path_string()
move_current_vrp([ CHANGE_VECTOR ])
restore_last_vrp()
vrp_child( FILENAME )
vrp_child_string( FILENAME[, SUFFIX] )
user_vrp([ NEW_VALUE ])
user_vrp_string()
current_user_vrp_level([ NEW_VALUE ])
inc_user_vrp_level()
dec_user_vrp_level()
current_user_vrp_element([ NEW_VALUE ])
vrp_param_name([ NEW_VALUE ])
persistant_vrp_url([ CHANGE_VECTOR ])
smtp_host([ NEW_VALUE ])
smtp_timeout([ NEW_VALUE ])
site_title([ NEW_VALUE ])
site_owner_name([ NEW_VALUE ])
site_owner_email([ NEW_VALUE ])
site_owner_email_vrp([ NEW_VALUE ])
site_owner_email_html([ VISIBLE_TEXT ])
get_hash_from_file( PHYS_PATH )
get_prefs_rh( FILENAME )
is_mod_perl()
user_cookie_str()
user_query_str()
user_post_str()
user_offline_str()
is_oversize_post()
request_method()
content_length()
server_name()
virtual_host()
server_port()
script_name()
http_referer()
remote_addr()
remote_host()
remote_user()
user_agent()
base_url()
self_url()
self_post([ LABEL ])
self_html([ LABEL ])
user_cookie([ NEW_VALUES ])
user_cookie_string()
user_cookie_param( KEY[, NEW_VALUES] )
user_input([ NEW_VALUES ])
user_input_string()
user_input_param( KEY[, NEW_VALUE] )
user_input_keywords()
persistant_user_input_params([ NEW_VALUES ])
persistant_user_input_string()
persistant_user_input_param( KEY[, NEW_VALUES] )
persistant_url()
redirect_url([ NEW_VALUE ]) -- POD for this available below
get_http_headers()
send_headers_to_user([ HTTP ])
send_content_to_user([ CONTENT ])
send_to_user([ HTTP[, CONTENT] ])
parse_url_encoded_cookies( DO_LC_KEYS, ENCODED_STRS )
parse_url_encoded_queries( DO_LC_KEYS, ENCODED_STRS )DOCUMENTED FUNCTIONS AND METHODS
clone([ CLONE ])
This method initializes a new object to have all of the same properties of the current object and returns it. This new object can be provided in the optional argument CLONE (if CLONE is an object of the same class as the current object); otherwise, a brand new object of the current class is used. Only object properties recognized by CGI::WPM::Globals are set in the clone; other properties are not changed.
redirect_url([ VALUE ])
This method is an accessor for the "redirect url" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. If this property is defined, then an http redirection header will be returned to the user instead of an ordinary web page.
body_content([ VALUES ])
This method is an accessor for the "body content" list property of this object, which it returns. This property is used literally to go between the "body" tag pair of a new HTML document. If VALUES is defined, this property is set to it, and replaces any existing content. VALUES can be any kind of valid list. If the first argument to this method is an ARRAY ref then that is taken as the entire list; otherwise, all the arguments are taken as elements in a list.
head_content([ VALUES ])
This method is an accessor for the "head content" list property of this object, which it returns. This property is used literally to go between the "head" tag pair of a new HTML document. If VALUES is defined, this property is set to it, and replaces any existing content. VALUES can be any kind of valid list. If the first argument to this method is an ARRAY ref then that is taken as the entire list; otherwise, all the arguments are taken as elements in a list.
title([ VALUE ])
This method is an accessor for the "title" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in the header of a new document to define its title. Specifically, it goes between a <TITLE></TITLE> tag pair.
author([ VALUE ])
This method is an accessor for the "author" scalar property of this object, which it returns. If VALUE is defined, this property is set to it. This property is used in the header of a new document to define its author. Specifically, it is used in a new '<LINK REV="made">' tag if defined.
meta([ KEY[, VALUE] ])
This method is an accessor for the "meta" hash property of this object, which it returns. If KEY is defined and it is a valid HASH ref, then this property is set to it. If KEY is defined but is not a HASH ref, then it is treated as a single key into the hash of meta information, and the value associated with that hash key is returned. In the latter case, if VALUE is defined, then that new value is assigned to the approprate meta key. Meta information is used in the header of a new document to say things like what the best keywords are for a search engine to index this page under. If this property is defined, then a '<META NAME="n" VALUE="v">' tag would be made for each key/value pair.
style_sources([ VALUES ])
This method is an accessor for the "style sources" list property of this object, which it returns. If VALUES is defined, this property is set to it, and replaces any existing content. VALUES can be any kind of valid list. If the first argument to this method is an ARRAY ref then that is taken as the entire list; otherwise, all the arguments are taken as elements in a list. This property is used in the header of a new document for linking in CSS definitions that are contained in external documents; CSS is used by web browsers to describe how a page is visually presented. If this property is defined, then a '<LINK REL="stylesheet" SRC="url">' tag would be made for each list element.
style_code([ VALUES ])
This method is an accessor for the "style code" list property of this object, which it returns. If VALUES is defined, this property is set to it, and replaces any existing content. VALUES can be any kind of valid list. If the first argument to this method is an ARRAY ref then that is taken as the entire list; otherwise, all the arguments are taken as elements in a list. This property is used in the header of a new document for embedding CSS definitions in that document; CSS is used by web browsers to describe how a page is visually presented. If this property is defined, then a "<STYLE><!-- code --></STYLE>" multi-line tag is made for them.
body_attributes([ KEY[, VALUE] ])
This method is an accessor for the "body attributes" hash property of this object, which it returns. If KEY is defined and it is a valid HASH ref, then this property is set to it. If KEY is defined but is not a HASH ref, then it is treated as a single key into the hash of body attributes, and the value associated with that hash key is returned. In the latter case, if VALUE is defined, then that new value is assigned to the approprate attribute key. Body attributes define such things as the background color the page should use, and have names like 'bgcolor' and 'background'. If this property is defined, then the attribute keys and values go inside the opening <BODY> tag of a new document.
replacements([ VALUES ])
This method is an accessor for the "replacements" array-of-hashes property of this object, which it returns. If VALUES is defined, this property is set to it, and replaces any existing content. VALUES can be any kind of valid list whose elements are hashes. This property is used in implementing this class' search-and-replace functionality. Within each hash, the keys define tokens that we search our content for and the values are what we replace occurances with. Replacements are priortized by having multiple hashes; the hashes that are earlier in the "replacements" list are performed before those later in the list.
body_append( VALUES )
This method appends new elements to the "body content" list property of this object, and that entire property is returned.
body_prepend( VALUES )
This method prepends new elements to the "body content" list property of this object, and that entire property is returned.
head_append( VALUES )
This method appends new elements to the "head content" list property of this object, and that entire property is returned.
head_prepend( VALUES )
This method prepends new elements to the "head content" list property of this object, and that entire property is returned.
add_earlier_replace( VALUE )
This method prepends a new hash, defined by VALUE, to the "replacements" list-of-hashes property of this object such that keys and values in the new hash are searched and replaced earlier than any existing ones. Nothing is returned.
add_later_replace( VALUE )
This method appends a new hash, defined by VALUE, to the "replacements" list-of-hashes property of this object such that keys and values in the new hash are searched and replaced later than any existing ones. Nothing is returned.
do_replacements()
This method performs a search-and-replace of the "body content" property as defined by the "replacements" property of this object. This method is always called by to_string() prior to the latter assembling a web page.
content_as_string()
This method returns a scalar containing the complete HTML page that this object describes, that is, it returns the string representation of this object. This consists of a prologue tag, a pair of "html" tags and everything in between. This method requires HTML::EasyTags to do the actual page assembly, and so the results are consistant with its abilities.
AUTHOR
Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications.
I am always interested in knowing how my work helps others, so if you put this module to use in any of your own code then please send me the URL. Also, if you make modifications to the module because it doesn't work the way you need, please send me a copy so that I can roll desirable changes into the main release.
Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.
SEE ALSO
perl(1), mod_perl, HTML::Application, CGI::WPM::Base, HTTP::Headers, Apache.