NAME

CGI::WeT::Engine - Theme engine for the CGI::WeT package

SYNOPSIS

use CGI::WeT::Engine ();

DESCRIPTION

This module provides a web site with the ability to provide themes. It is designed to work seamlessly with mod_perl but can be made to work without mod_perl without too much difficulty.

NOT USING MOD_PERL

To use this module without mod_perl, a script must be written to handle all themed page requests. A sample script might be

    #!/usr/bin/perl

    use CGI::WeT::Engine;
    use CGI::WeT::Theme;
    use CGI::WeT::Modules::Basic;

    my $filename = $ENV{'PATH_TRANSLATED'};
    my $url = $ENV{'PATH_INFO'};

    my($key, $val);

    my $engine = new CGI::WeT::Engine;

    if($inputfile) {

	#
	# get the title and other headers out of the themed page
	#

	open IN, "<$inputfile";

        while(<IN>) {

            last if /^\s*$/;
            next if /^\s*#/;

            chomp;

            if(/^[A-Za-z_]+:/) {
                ($key, $val) = split(/:/,$_,2);
            } else {
                $val = $_;
            }

            $engine->headers_push($key, $val);
        }
	
        #
        # slurp up the rest of the file
        #

        $engine->body_push((<IN>));
        close IN;
    }
    
    $r->print( $engine->render_page );

Apache must then be configured to call the CGI script for all files that are themed.

USING MOD_PERL

To use this module with mod_perl, a handler must be set using the engine to filter the themed pages. The following is an example of the changes needed by the Apache configuration files.

<Files "*.thtml">
    AddHandler perl-script .thtml
    PerlHandler CGI::WeT::Engine
    PerlSendHeader On
    PerlSetupEnv   On
</Files>

All required modules must be loaded in at server startup. No code is loaded during rendering. The minimum modules are CGI::WeT::Engine, CGI::WeT::Theme, and CGI::WeT::Modules::Basic.

CGI::WeT::Engine API

$engine = new CGI::WeT::Engine;

Returns a reference to a new rendering engine. The returned object will have parsed the arguments to the URL (if GET or POST). The returned object will need to be set up before a page can be rendered.

If using mod_perl, the following variables may be set using PerlSetVar:

WeT_SiteName - prefix for page titles to identify the site
WeT_SiteRoot - prefix for URLs for this site - defaults to '/'
WeT_DocumentRoot - Defaults to Apache's DocumentRoot
WeT_Top - location of the top page of the site relative to the SiteRoot
          (this allows splash pages)
WeT_Email - email of the administrator
WeT_ProblemsEmail - email for bug reports and other problems
WeT_DefaultTheme - initial theme people will see

Otherwise, the function CGI::WeT::site_config must be defined expecting a reference to the engine object. The following members of the object need to be defined:

$engine->{'SITENAME'}  -- corresponds to WeT_SiteName
$engine->{'URLBASES'}->{'URLBASE'}  -- corresponds to WeT_DocumentRoot
$engine->{'URLBASES'}->{'TOP'}  -- corresponds to WeT_Top
$engine->{'EMAIL'} -- corresponds to WeT_Email
$engine->{'PROBLEMS_EMAIL'} -- corresponds to WeT_ProblemsEmail
$engine->{'DEFAULT_THEME'} -- corresponds to WeT_DefaultTheme

$engine->content_pop

This function returns the item on the top of the content stack. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine.

$engine->content_push(array ref)

This function pushes the array reference onto the top of the content stack. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine.

$engine->content_peek

This function returns a reference to the item on the top of the stack without removing it. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine.

$engine->arguments_pop

This function returns the item on the top of the argument stack. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine. Caveat coder.

$engine->arguments_push(hash ref)

This function pushes the hash reference onto the top of the argument stack. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine. Caveat coder.

$engine->argument(key)

This function descends the argument stack looking for a definition of key. If one is found, it is cached at the top of the stack and returned. Use this function to retrieve values passed through a GET or POST. Cookies may also be retrieved through this method but will be overridden by any definitions in the GET or POST data.

The calling context determines if the function returns an array or a scalar. This is only significant if the key appeared multiple times in the cookie, GET, or POST data.

$engine->headers_push(key => value, ...)

This function will place value associated with key in the header hash. Multiple values are placed in arrays similar to the arguments. Several keys are meaningful to the rendering code:

Title - Denotes the page title. This is placed in the document head.

Type - Document type. This is used to determine which layout to use in a theme. The first is highest priority. The `DEFAULT' type is implied as the lowest priority layout.

Author, Keywords, Date - These three are placed verbatim in META tags in the header. Useful information for search engines.

$engine->header(key)

This function retrieves the values associated with key. The calling context determines if the function returns an array or a scalar. This is only significant if the key appeared in multiple calls to headers_push.

$engine->body_push(array)

This function places array at the end of the body content caching it for later use by the rendering code. Text placed in the body cannot be removed by a provided method.

$engine->url(array)

This function forms a string from array prefixing it with the base URL for the themed site. Any strings of the form @@var@@ are interpolated from a hash of base URLs. This provides for locations based on the theme or site configuration. Multiple `/'s are collapsed. This function will not be able to return theme dependent URLs except during the actual rendering of a page.

$engine->filename(URL)

This function will return the location of URL in the filesystem. This will use Apache's URl->filename translation code if running under mod_perl. Otherwise, tacks the document root on the beginning.

$engine->render_content

This function is the main workhorse returning an array resulting from rendering the top of the content stack. Used primarily in the rendering code and the CGI::WeT::Modules extensions to the engine. Caveat coder.

$engine->render_page([theme])

This function returns the rendered page constructed with the object using theme if supplied. Otherwise the argument stack is consulted to determine which theme to use. If theme is supplied, it must be an object returned by new CGI::WeT::Theme or a derived class of CGI::WeT::Theme.

SEE ALSO

perl(1), CGI::WeT(3), CGI::WeT::Theme(3), CGI::WeT::Modules(3),

CGI::WeT notes at http://people.physics.tamu.edu/jsmith/wet-perls/

AUTHORS

Written by James G. Smith.
Copyright (C) 1999.  Released under the GNU General Public License v. 2.