/ 
Apache-SimpleTemplate-0.02
River stage zero No dependents
/ Apache::SimpleTemplate

NAME

Apache::SimpleTemplate

SYNOPSIS

in httpd.conf:

<Files *.stml>
  SetHandler perl-script
  PerlHandler +Apache::SimpleTemplate
  ### options:
  #PerlSetVar SimpleTemplateCache 0
  #PerlSetVar SimpleTemplateBlockBegin "{{"
  #PerlSetVar SimpleTemplateBlockEnd "}}"
  #PerlSetVar SimpleTemplateContentType "text/html"
  #PerlSetVar SimpleTemplateFile "/templates/foo.stml"
</Files>

in a template:

{{ _some_perl_code_; }}

evaluates the perl code, and the block gets replaced by the 
last value returned in the perl code.

{{+ _some_perl_code_; }}

is the same, but the output gets url-encoded.

{{ $s->include('/some/file'); }}

includes another file or parsed-template.

{{ $$inref{foo}; }}

gives the value of the CGI/form input variable 'foo'.

{{ $$headerref{Location} = '/'; $status = 302; ''; }}

redirects to '/'.

{{ $content_type = 'text/xml'; ''; }}

sets the content-type to 'text/xml' instead of the default 'text/html';

DESCRIPTION

Apache::SimpleTemplate is *another* Template-with-embedded-Perl package for mod_perl. It allows you to embed blocks of Perl code into text documents, such as HTML files, and have this code executed upon HTTP request. It should take moments to set-up and learn; very little knowledge of mod_perl is necessary.

This module is meant to be a slim and basic alternative to more fully featured packages like Apache::Embperl, Apache::ASP, TemplateToolkit. You may wish to compare approaches and features, and consider trade-offs in funcionality, implementation time, speed, memory consumption, etc.

Apache::SimpleTemplate has no added syntax/tags/etc, and only the bare necessities of functionality. Thus, it should have a very small memory footprint and little processing overhead. It has basic caching and pre-loading options for templates to help you tweak performance. It is also designed for making subclasses, in which you can add the functionality you want.

INSTALLATION

The only requirement is mod_perl. To install Apache::SimpleTemplate, run:

perl Makefile.PL
make
make install

EXAMPLES

template "/printenv.stml"

{{ $s->include('/nav/header.stml'); }}

<table border=3>
<tr><th colspan=2>env</th></tr>

{{
  foreach my $e (sort keys(%ENV)) {
        $out .= "<tr><td><strong>$e</strong></td><td>$ENV{$e}</td></tr>\n";
  }
}} 

<tr><th colspan=2>args</th></tr>

{{
  foreach my $e (sort keys %$inref) {
        $out .= "<tr><td><strong>$e</strong></td><td>$$inref{$e}</td></tr>\n";
  }
}}

</table>

subclass "MyTemplate"

# in httpd.conf should set the handler: "PerlHandler +MyTemplate"
# in your template you can call: "{{$s->my_method}}"

package MyTemplate;
use Apache::SimpleTemplate ();
our @ISA = qw(Apache::SimpleTemplate);

# handler() must be defined, as it is not a method.
# instantiate this class, and call SimpleTemplate's handler:
sub handler {
    my $r = shift;
    my $s = new MyTemplate($r);

    # you can do additional steps/calls here, even to change
    # $s->{status} and/or $s->{file} for a different template.

    return Apache::SimpleTemplate::handler($r, $s);
}

sub my_method {
    my $self = shift;
    return 'this is my_method.';
}
1;

cgi script "simpletemplate.cgi"

#!/usr/bin/perl
# 
# example using SimpleTemplate as a CGI.
# this *must* be called with a "file" arg or have $s->{file} defined.
#
# eg: /simpletemplate.cgi?file=/printenv.stml&content_type=text/html
#

# (could use our subclass here instead.)
use Apache::SimpleTemplate;              
my $s = new Apache::SimpleTemplate();

# other stuff can go here.
# eg, set $s->{file} and $s->{content_type}, call subs, etc...

#$s->{block_begin} = '{{';
#$s->{block_end} = '}}';

exit &Apache::SimpleTemplate::handler(undef);

VARIABLES & FUNCTIONS

variables in templates:

$inref        - a reference to a hash containing the CGI/form input args
$headerref    - a reference to a hash into which the template can
                put out-going http headers. (Location, Set-Cookie, etc.)
$content_type - the template can override this.
$status       - the template can set this on errors or to redirect.
                (the rest of the template is still processed.)
$r            - this instance of 'Apache', i.e. the request object.
$s            - this instance of 'Apache::SimpleTemplate' (or your subclass)
$out          - a block of code can use this for the output, instead
                of the last value returned by the block. 
$____*        - these names are reserved for use inside the parsing function.

methods/functions

$s->include('/some/path')   -- include another document/template.
                               the path is relative to the document root

&encode($string)            -- url-encode the $string.
&decode($string)            -- url-decode the $string.
&preload($file)             -- preload the template in $file (a full path).
                               for use in a startup.pl file.

&Apache::SimpleTemplate::include('/some/path');
                            -- include call for use in other code ouside a template
&Apache::SimpleTemplate::include('/some/path', $inref);
                            -- same but without reparsing the input fields.

PerlSetVar options

SimpleTemplateBlockBegin    -- the delim for a code block's end ['{{']
SimpleTemplateBlockEnd      -- the delim for a code block's start ['}}']
SimpleTemplateCache         -- keep templates in memory? [0]
SimpleTemplateContentType   -- the default content_type ['text/html']

SimpleTemplateFile          -- template file location (w/in doc_root)
                               probably useful only within a <Location>.
                               [the incoming request path]

OTHER TIDBITS

template processing

Any errors in evaluating a code block should get logged to the error_log.

Any additional variables you wish to use need to be declared (with 'my').
If you want to share values between code blocks, the best thing to do
is to stuff them into $inref or into your (subclass) instance $s.

Please note that if you are using the default delimiters '{{' & '}}', 
you should avoid "{{$$inref{foo}}}", which will not work. Write 
"{{$$inref{foo};}}" or "{{ $$inref{foo} }}" instead.

A template is always completely parsed, even if $status is changed from 200
within the template or within a subclass handler. In a subclass handler,
you can switch to an error template if desired by setting $s->{file}.

Included sub-templates recieve the same instance of $s, so they have the 
same $inref, etc. Thus, they can also set headers, change $status, etc.

performance notes

If SimpleTemplateCache is on (1) or a template is pre-loaded with preload(),
Apache must be restarted to see template changes. Otherwise, templates
are loaded upon each request, and changes appear immediately.

preload() can be used even with caching off (0), if you have a handful of
templates you want to cache but many others you do not. preload() may not
improve speed over caching, but should reduce unshared memory consumption.

The regular CGI mode will probably be very very slow, so you may want
only to use it when testing something (a cached template or another
module/subclass) and you do not want to restart Apache constantly.

The template parsing herein is very similar to that of Text::Template,
but even dumber. (Instead of using Text::Template, the template
parsing was implemented internally for better speed.)

VERSION

Version 0.02, 2002-September-02.

AUTHOR

peter forty 
Please send any comments or suggestions to
mailto:apache-simple-template@peter.nyc.ny.us

The homepage for this project is: 
http://peter.nyc.ny.us/simpletemplate/

COPYRIGHT (c) 2001-2002

This is free software with absolutely no warranty.
You may use it, distribute it, and/or modify 
it under the same terms as Perl itself.

SEE ALSO

perl, mod_perl.