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:

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

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

     includes another file or parsed-template.

{{ $$inref{foo}; }}

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

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

     redirects to '/'.

     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/

  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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

in httpd.conf:

in a template:

{{ _some_perl_code_; }}

{{+ _some_perl_code_; }}

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

{{ $$inref{foo}; }}

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

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

DESCRIPTION

INSTALLATION

EXAMPLES

template "/printenv.stml"

subclass "MyTemplate"

cgi script "simpletemplate.cgi"

VARIABLES & FUNCTIONS

variables in templates:

methods/functions

PerlSetVar options

OTHER TIDBITS

template processing

performance notes

VERSION

AUTHOR

COPYRIGHT (c) 2001-2002

SEE ALSO

NAME

SYNOPSIS

in httpd.conf:

in a template:

{{ _some_perl_code_; }}

{{+ _some_perl_code_; }}

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

{{ $$inref{foo}; }}

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

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

DESCRIPTION

INSTALLATION

EXAMPLES

template "/printenv.stml"

subclass "MyTemplate"

cgi script "simpletemplate.cgi"

VARIABLES & FUNCTIONS

variables in templates:

methods/functions

PerlSetVar options

OTHER TIDBITS

template processing

performance notes

VERSION

AUTHOR

COPYRIGHT (c) 2001-2002

SEE ALSO

Module Install Instructions