view release on metacpan or  search on metacpan

SimpleTemplate.pm  view on Meta::CPAN

  $s->escape($string)            -- html-escape the $string.
                                    &Apache::SimpleTemplate::escape($string)
  $s->quote_escape($string)      -- single-quote-escape the $string.
                                    &Apache::SimpleTemplate::quote_escape($string)
  $s->js_escape($string)         -- single-quote and newline escape (for javascript)
                                    &Apache::SimpleTemplate::quote_escape($string)

  $s->preload($file)             -- preload the template in $file, a full
                                    path which must match the DOCUMENT_ROOT.
                                    (for use in a startup.pl file.)

  $s->include('/dir/file')       -- include another document/template.
                                    the path is relative to the DOCUMENT_ROOT

  $s->print(...)                 -- print out something from within <% %>.
  $s->flush()                    -- flush the print buffer (within <% %>).
                                    (sends HTTP headers on the first call.)

=head2 deprecated and removed vars and functions.

  $out          - deprecated template variable.
                  a <%: %> block of code could use this for the output, 
                  instead of the last value returned by the block. 
                  use <% %> or <%= %> blocks as needed instead.

  $headerref    - removed, use $s->header() instead.
  $status       - removed, use $s->status() instead.
  $content_type - removed, use $s->content_type() instead.

  Apache::SimpleTemplate::include() -- static calls no longer work.
                  instantiate if necessary, and use $s->include() instead.
                  (shouldn't have been included in the first place, as they
                  would not follow any settings other than defaults.)


=head2 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? [1]
  SimpleTemplateReload        -- check templates for changes? [1]
  SimpleTemplateDebug         -- level of debug msgs in error_log (0-3) [0]
                                 (if >= 1, compile errors go to the browser.)

  SimpleTemplateContentType   -- the default content_type ['text/html']
  SimpleTemplateCascadeStatus -- set to 0 if you do not want included 
                                 templates to affect the response status.
  SimpleTemplateFile          -- template file location (w/in doc_root)
                                 probably useful only within a <Location>.
                                 [the incoming request path]


=head1 OTHER TIDBITS

=head2 template processing

  Any errors in evaluating a code block should get logged to the error_log.
  The compilation process tries to keep the line numbers consistent with
  the template, but <%! %> declarations/definitions that are not at the
  top of the template may throw line numbers off.

  Any additional variables you wish to use must be declared (with 'my').
  If you declare them in <%! %> or <% %> blocks, they will be accessible
  in later blocks.

  Included sub-templates receive the same instance of $s, so they have the 
  same $inref, etc. Thus, they can also set headers, change status, etc.
  (Turn off "cascade_status" to prevent the latter.)


=head2 template debugging

  SimpleTemplateDebug / $s->debug() values have the following meanings
    0 quiet, errors logged to error_log
    1 quiet, errors also sent to browser
    2 info on requests, includes, status codes, etc.
    3 info on template compilation. (noisy)
    4 verbose info on template compilation. (extremely noisy)

  You can also always log your own messages to the error_log from 
  within your templates, eg: <% print STDERR "some message" %>.


=head2 performance notes

  Templates are compiled into perl packages (or anonymous subroutines if
  there is no <%! %> block.) Caching of templates, which is on by default,
  will help speed performance greatly. The only reason you might want to
  turn it off is if you have many, many templates and don't want them 
  always kept around in memory.

  Preloading via preload() in a startup.pl file is a way to save more 
  memory (the template will get loaded before the webserver forks its
  children, thus keeping the template in memory shared by all the procs.)
  This also will improve speed a bit, as each newly spawned webserver
  proc will not need to load the template anew. 

  preload() may be used even with caching off (0), if you have a handful of
  templates you want to cache but many others you do not.

  Turning SimpleTemplateReload to off (0) will speed things a little bit,
  as SimpleTemplate will not check the file for updates with every request.
  However, if you are using caching/preloading and SimpleTemplateCache is 
  off (0), Apache must be restarted to see template changes.

  Finally, the regular CGI mode will probably be very slow, so you may
  want only to use it when testing something (a cached template or another
  module/subclass), or when using a host without mod_perl installed.

=head2 New in 0.04

  $s->print and $s->flush methods. Option to have errors in included 
  templates not bubble up and cause whole page to fail.

  Defaults delims are now the more conventional '<%' and '%>'.
  Users still wanting '{{' and '}}' can set the 
  SimpleTemplateBlockBegin and SimpleTemplateBlockEnd variables.

  $status, $headerref, $content_type not supported in templates.