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

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->print((<IN>));
        close IN;
    }
    # page is rendered when $engine is destroyed...

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.

USING TIED HANDLES

CGI::WeT::Engine now supports tied handles. This makes themeing of older code much easier:

    use CGI::WeT;
    tie *STDOUT, 'CGI::WeT::Engine';
    print "Title: <title of page>\nAuthor: A. U. Thor\n\n";
    .
    .  Old script here printing to STDOUT
    .
    untie *STDOUT;

The resulting page will have the scripts output as the body. When using this method, do not use the CGI::start_html function -- this is taken care of by the CGI::WeT::Engine code.

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.

When the object returned by new is destroyed, the page is rendered to STDOUT.

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
                      this can be overridden with the environment variable
                      `WET_THEME'
   WeT_UseSSLURLs - whether to add :SSL and :NOSSL to the
                    end of URLs generated by the engine or not. (This
                    is considered true if defined.)  This is still
                    experimental and will most likely break graphical
                    navigation.
   WeT_AnonymousCoward - in a bow to slashdot.org, this is what the site
                         names anonymous contributors.  This is not
                         retroactive (yet).

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->{'SSL_URLS'} -- corresponds to WeT_UseSSLURLs
   $engine->{'AC'} -- corresponds tp WeT_AnonymousCoward
=cut
# ' for Emacs
# ` for Emacs

sub DESTROY { my $engine = shift; my $r;

  return if $engine->{'INTERNAL_USE_ONLY'};
  if($engine->{'doing_headers'}) {
    $engine->print("\n\n");
  }


  if($engine->{'MOD_PERL'} ) {
    $r = Apache->request;
    my $fh = $engine->{'STDOUT'};

#    $r->content_type('text/html');

#    $r->cgi_headers_out unless $engine->{'FILTERED'};

    $fh->print($engine->render_page);
  } else {
#    print "Content-type: text/html\n\n";
    print $engine->render_page;
  }
}

$engine->internal_use_only
This function will mark the $engine object as being for internal use only (hence its name). That is, it will not output a page to output upon destruction. Returns the previous value. If an argument is present, the internal flag is set to that value.

This function is valuable if a CGI script decides it needs to redirect instead of outputing HTML. Calling this function will disable automatic HTML output.

$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. An optional argument specifies how many elements to pop.

$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->print(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.

If the url built from array begins with `/', then the link is absolute with respect to the top of the site. Otherwise, it is relative to the page being produced.

If this function is called without arguments, it will return the URI of the current request.

$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. If no arguments are passed, it will return the filename of the current page.

$engine->smarttext(array)
This function will accept the array of plain text and return a string of HTML formatted text.

HTML character entities are preserved. Also, &star; and &under; are translated to `*' and `_' respectively. Paragraphs beginning with whitespace are quoted as preformatted text. The ampersand, greater-than and less-than are translated to character entities. Therefore, no HTML may be included in the input text. Text may be _underlined_ or made *bold*.

$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(3), CGI::WeT(3), CGI::WeT::Theme(3), CGI::WeT::Modules(3),

CGI::WeT notes at http://www.jamesmith.com/cgi-wet/

AUTHORS

 Written by James G. Smith.
 Copyright (C) 1999.  Released under the Artistic License.

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