view release on metacpan or  search on metacpan

SimpleTemplate.pm  view on Meta::CPAN

1;

__END__


=head1 NAME

  Apache::SimpleTemplate



=head1 SYNOPSIS

=head2 in httpd.conf:

  <Files *.stml>
    SetHandler perl-script
    PerlHandler +Apache::SimpleTemplate

    ### options (w/ defaults):
    #PerlSetVar SimpleTemplateCache 1
    #PerlSetVar SimpleTemplateReload 1
    #PerlSetVar SimpleTemplateDebug 0
    #PerlSetVar SimpleTemplateCascadeStatus 1
    #PerlSetVar SimpleTemplateBlockBegin "<%"
    #PerlSetVar SimpleTemplateBlockEnd "%>"
    #PerlSetVar SimpleTemplateContentType "text/html"
  </Files>

  ### have index.stml files handle a request for a directory name.
  #DirectoryIndex index.html index.stml

  <Location /example>
    SetHandler perl-script
    PerlHandler +Apache::SimpleTemplate
    PerlSetVar SimpleTemplateFile "/templates/example.stml"
  </Location>

=head2 in a template:

=head3  <%! _perl_definitions_or_declarations_ %>

     compiles the code once. (the code block is replaced by nothing.)
     can be used for defining subroutines, 'use' calls, declaring and 
     populating variables/hashes/etc.

=head3  <% _perl_code_ %>

     executes the perl code. (this block is replaced by nothing.)
     can also declare variables for use within the template.

=head3  <%= _a_perl_expression_ %>

     evaluates the perl expression, and the block gets replaced by 
     the expression's value.

     '<%+ %>' is the same as '<%= %>', but the output gets url-encoded.
     (mnemonic: '+' is a space in a url-encoded string.)

     '<%^ %>'is the same as '<%= %>', but the output gets html-escaped.
     (mnemonic: '^' looks like the '<' and '>' that get replaced.)

     '<%\ %>'is the same as '<%= %>', except the string gets escaped for
     use as a single-quoted javascript var. ("'", "\", NL, CR get escaped.)

=head3  <%- _a_comment_ %>

     is ignored and replace by nothing.
     (mnemonic: "-" as in "<!-- html comments -->".)

=head3  <%# _comment_out_text_and/or_template_blocks_ #%>

     comment out larger areas of templates, including code blocks.
     NB: the '#' on the closing tag, as this is the only tag which can 
     wrap other tags.

=head3  <% $s->include('/dir/file.stml') %>

     includes another file or parsed-template in place of this.

=head3  <%= $$inref{foo}; %>

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

=head3  <% $s->header('Location','/'); $s->status(302); return; %>

     ends execution of the template and redirects browser to '/'.

=head3  <% $s->content_type('text/xml'); %>

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

=head3  <%: _perl_code_ %> DEPRECATED

     evaluates the perl code, and the block gets replaced by the last
     value returned in the perl code, or $out if defined. (included
     mostly for backward compatability-- it's better to use a mixture
     of <% %> and <%= %> blocks.)
     (mnemonic: '<%: %>' is like a combination of '<% %>' and '<%= %>'.)



=head1 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, though some knowledge of Apache and perl is
assumed.

This module is meant to be a slim and basic alternative to more fully
featured packages like Apache::Embperl, Apache::ASP, or TemplateToolkit,
and more of a mod_perl counterpart to JSP or PHP. You may wish to compare 
approaches and features of the other perl templating schemes, and consider 
trade-offs in funcionality, implementation time, speed, memory 
consumption, etc. This module's relative lack of "features" is meant to 
improve both its performance and its flexibility.

Apache::SimpleTemplate has no added programming syntax, relying simply
on perl itself for all programming logic in the templates. It should