DESCRIPTION

This is a simplistic, fast-parsing code-caching template system.

It takes a template, converts it into a perl subroutine and then runs the subroutine as

    $code->($view,$req,\%args); 

Practical upshot is, the CODE is cached, not the data, thereby making it possible to cache templates across multiple requests. On that note, one must be careful not to store data otherwise data will bleed across multiple requests.

Always use my() variables, don't create subroutines, etc..

TEMPLATE SYNTAX

Template syntax is really simple, asp/jsp like:

  <% 
    $req->out()->header("Content-Type: text/plain");
    my $foo = $req->param("FOO");
    my $title = $args->{title};
  %>

  = is a way of placing an implicit $req->out()->print($text), that is,
    it prints the result of the perl expression.

  Hello: FOO is:<%= $foo; %>

    <%-- This is a comment %>

Just comments, perl code and HTML.

TRAPS

• Run in the GenieMod::View::Template::Environ name space.

Everything is run in te GenieMod::View::Template::Environ package name space, under the strict pragma, so, all variables MUST be declared.

Don't hold on to data.

Templates can (and are) shared among multiple requests, therefore it is usually a mistake to attempt to hold on to any data.

If you hold on to data, there is the possibility it will bleed across web pages, which is very much not desired if for example, credit card numbers are used.

run IN a subroutine.

Don't create subs or do anything fancy within a template, as these may create memory leaks.

[adv]

VARIABLES

Each template has the following variables available:

• $tmpl

The template name.

• $source

The perl source code (what this template looks like after being parsed)

• $view

The View object.

• $req

The request object

• $args

The template arguments, either specified in the conf file in the args section, or, passed along via include()

In addition, you have the functions available from GenieMod::View::Template::Environ

FUNCTIONS

See GenieMod::View::Template::Environ

METHODS

• new()
• create()
• display()

These are the standard View methods.

• locate_path($template_name)

Look in the path for $template_name, returns the filename or nothing. Use this if you wanted to dump a files contents, for example.

• send_template($req,$file,%args)

Sends template data out through request. (Does NOT cache)

VIEW METHODS

These are available from within a template. They are not to be used on the object directly, but rather, from within the display() templates.

include_file($file,%args)

Like include() but uses no cache, uses no template path.

include($templ)

Include a template, with arguments. (So you can for example, set the title of a page you are including)

  $view->include("header.ptml",title => "Header Title Here");

Important: do not call outside of a template The right way is via the display() method, which needs to set up the request and some tracking variables.

varg()

This fetches the args section from the conf file. In practice, it is the same as:

    $v = $req->pad('View_Tpl_Args'); 
    %v = %{$v}; # You get %v

With an argument, it'll return that specific view argument.

    my $file = $view->varg('file');

viewname()

Get the name of the view (the one the controller returned)

viewfile()

Get the template file of this view. (same as varg(file) actually)

A handy debug string to have in the footer of a document is something like this:

    <%
        $req->out()->printf('action:%s file:%s view:%s',
                    $req->action(),$view->viewfile(),$view->viewname()
        );
    %>

Internal/Protected methods.

These aren't meant to be used inside templates, but may be useful of extending..

• load_template($tmpl)

Load a template. Looks in the template path and fetches the raw template data.

• code_cache($tmpl)

Maintains an internal code reference cache of templates. These are compiled subroutines.

[adv]
• parsed_cache($tmpl)
• remove_parsed_cache($tmpl)

These are for parsed templates and are not used here. The speed improvement is minimal, they are provided as hooks if it's ever required.

• parse($data)

parse template data.

returns a string that is fed to eval. Provided to allow over-riding, the returned value must be a perl string.

NAME GenieMod::View::Template::Environ

This is the package that templates are compiled in, it is not object oriented.

These functions are available to templates.

• urlencode($string)

UrlEncodes a string, so that it can be used as a URL, something like "Hello World" would be converted to "Hello%20World".

• escape($string)

This escapes the HTML characters &, < and >

OTHER FUNCTIONS

These aren't meant to be run inside of templates.

• compile($template_name,$perl_string)

Compiles code in $string. returns a code reference that can be run with the following arguments:

 $code->($view, $req, $out,\%args)

In addition, the variable $source and $tmpl are available as well. $source is the template in perl source form, and $tmpl is the template ID.

Any subroutines in this package are available to the compiled code.

Note: this code is meant to be cached! Assigning to $tmpl or $source is not advisable.