/ 
CGI-WebsiteGenerator-0.35
/ CGI::WPM::Globals

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, and providing utilities like sending e-mail.

DEPENDENCIES

Perl Version

5.004

Standard Modules

I<none>

Nonstandard Modules

CGI::WPM::FileVirtualPath 0.35
CGI::WPM::WebUserIO 0.94
CGI::WPM::PageMaker 1.02

SYNOPSIS

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.

Subdirectories are all relative, so having '' means the current directory, 'something' is a level down, '..' is a level up, '../another' is a level sideways, 'one/more/time' is 3 levels down. However, any relative subdir beginning with '/' becomes absolute, where '/' corresponds to the site file root. You can not go to parents of the site root. Those are physical directories (site resource path), and the uri does not reflect them. The uri does, however, reflect uri changes (virtual resource path).

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().

FUNCTIONS AND METHODS

This module inherits the full public interfaces and functionality of both CGI::WebUserInput and CGI::WebUserOutput, so the POD in those modules is also applicable to this one. However, the new() and initialize() and clone() methods of those modules are overridden by ones defined in this one.

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

send_content_to_user([ CONTENT ]) -- overrides CGI::WPM::WebUserIO's version

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 ])

today_date_utc()

get_hash_from_file( PHYS_PATH )
get_prefs_rh( FILENAME )

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.

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), CGI::WPM::PageMaker, CGI::WPM::WebUserIO, CGI::WPM::Base.