/ 
duncand-prerelease-0.38
/ CGI::WPM::Base

NAME

CGI::WPM::Base - Perl module that defines the API for subclasses, which are miniature applications called "web page makers", and provides them with a hierarchical environment that handles details for obtaining program settings, resolving file system or web site contexts, obtaining user input, and sending new web pages to the user.

DEPENDENCIES

Perl Version

5.004

Standard Modules

I<none>

Nonstandard Modules

CGI::WPM::Globals 0.34

SYNOPSIS

How A Subclass Is Called

require CGI::WPM::Globals;  # to hold our input, output, preferences
my $globals = CGI::WPM::Globals->new( "/path/to/site/files" );  # get input

$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

require HelloWorld;  # all content is made through here
$globals->move_current_srp( 'content' );  # subdir holding content files
$globals->move_site_prefs( {'text' => 'hey you'} );  # configuration details
HelloWorld->execute( $globals );  # do all the work
$globals->restore_site_prefs();  # rewind configuration context
$globals->restore_last_srp();  # rewind subdir context

$globals->send_to_user();  # send output now that everything's ready

A Simple Hello World Subclass

package HelloWorld;
require 5.004;

use strict;
use vars qw($VERSION @ISA);
$VERSION = '0.01';

use CGI::WPM::Base 0.3;
@ISA = qw(CGI::WPM::Base);

sub _dispatch_by_user {
	my $self = shift( @_ );
	my $globals = $self->{'site_globals'};

	$globals->title( $globals->site_title().' - Hello World' );
	$globals->body_content( <<__endquote );
<H2 ALIGN="center">@{[$globals->title()]}</H2>

<P>This module doesn't do anything interesting, but what the hey, 
everyone has to do a "hello world" program sometime.</P>

<P>Oh, and the main program says @{[$globals->site_pref( 'text' )]}.</P>

<P>You can write to @{[$globals->site_owner_name()]} 
at @{[$globals->site_owner_email()]}.</P>

<P>Click <A HREF="@{[$globals->self_url()]}">here</A> to call me back.</P>
__endquote
}

1;

DESCRIPTION

This POD is coming when I get the time to write it.

The above module can be its own complete web site, or it can be one page on a larger site, it's up to you to decide. Also, there can be multiple pages made by the same HelloWorld module, with their preferences differentiating them. Any WPM module can call others in turn, and each call should be preceeded and followed by setting/rewinding the context for the inner module. Each module can act like it is the only one in the system, whether that is true or not. But follow proper programming protocols like only unwinding contexts you set, and vice-versa. The Globals object does not enforce anything like that.

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

PUBLIC FUNCTIONS AND METHODS

This POD is coming when I get the time to write it.

execute( GLOBALS ) - calls new(), then dispatch_by_user(), then finalize()

-- or --

new( GLOBALS )
initialize( GLOBALS )
dispatch_by_user()
dispatch_by_admin()
finalize() - replaces the depreciated shim finalize_page_content()

Note that the second approach is depreciated, and only execute() should be used. In release 0.4 the second approach will not be available.

PREFERENCES HANDLED BY THIS MODULE

This POD is coming when I get the time to write it.

amend_msg  # personalized html appears on error page instead of subc action

page_body    # if defined, no subclass is used and this literal used instead
page_header  # content goes above our subclass's
page_footer  # content goes below our subclass's
page_title   # title for this document
page_author  # author for this document
page_meta    # meta tags for this document
page_css_src   # stylesheet urls to link in
page_css_code  # css code to embed in head
page_body_attr # params to put in <BODY>
page_replace   # replacements to perform

PRIVATE METHODS FOR OVERRIDING BY SUBCLASSES

This POD is coming when I get the time to write it.

_initialize()
_dispatch_by_user()
_dispatch_by_admin()
_finalize()

PRIVATE METHODS FOR USE BY SUBCLASSES

This POD is coming when I get the time to write it.

_set_to_init_error_page()
_get_amendment_message()

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::Globals.