NAME

Site::Template - magical template library, mostly for html but useful for most any text processing


SYNOPSIS

        use Site::Template;
        $t = Site::Template -> new();
        $t -> load( "mytemplate.tmpl" );
        $t -> register( Something => $s,
                        Else => $e );
        $t -> display();


DESCRIPTION

The Site::Template library allows simple text expansion. Mostly useful for websites or other text-oriented jobs.

        new             Return a new empty template object
        register        Register objects and names with the template
        registerdefault Takes whatever the arg was and makes it the
                        current namespace in the template.  This
                        means if it was an object the methods are
                        directly accessable and if it's a hashref
                        that you don't need to redirect.
        crush           Set to 1 or 0, if set to 1 it will auto-eliminate
                        white space in the output document.
        print           Set to 1 or 0, if false it will generate output
                        to the Output() method.
        decodeentities  If set to true it will automatically decode
                        all &*; entities while generating output,
                        this could be used to generate other types
                        of text files than HTML and allow escaping
                        the control characters.
        load            Load a template from disk.  If there is a
                        ./cache directory, it will check to see
                        if the cached version is newer than the
                        template to load, if so it will use the cached
                        version.  This is just a Data::Dumper printout
                        that can be loaded, that allows the template
                        to skip re-parsing the on-disk template file for
                        keywords.
        display         Display the template output, unless the Print
                        flag is set to false, then it will generate the
                        output into the Output member and also return
                        if on this call.
        addlib          Adds a library to the list of template libraries.
                        By default the list includes "." and "Site".  You
                        can add as many libs as you need, the file used
                        will be the first file that matches the name for
                        the load function in the library list.
        setlibs         Takes an array and overwrites the entire lib list
                        with whatever is passed.


TEMPLATES

Templates are just plain text files, though they will usually contain HTML and other markup for the template. All template directives are called by using <t:*/> syntax. Notice that if there is no closing tag that you must include the /> like with XML.

        <t:var name=NAME/>
                Output the value of a variable bound to NAME.
                Object methods can be referenced using ':'s, like

        <t:var name=MyObject:Foo:Bar/>

                Is essentially the same as $MyObject -> Foo() -> Bar();
                You can also specify an optional escape style:

                escape=html     Encode HTML entities
                escape=uri      Encode as URI
                escape=custom   Use custom escape handler

                If an object method prints something and you don't
                want the return value of the method printed,
                set display=no.

                If you prefix the name with a $, it performs a level
                of indirection.  Like if you have $foo, and foo=bar,
                then you get the value of bar not foo.

        <t:loop name=NAME></t:loop>
                Loops through the arrayref called NAME.  The values of
                the arrayref should be hashrefs, for example:

        $t -> register( names => [
                                        {
                                                first => 'Jeff',
                                                last => 'Jeffries'
                                        }, {
                                                first => 'Bob',
                                                last => 'Barker'
                                        }
                                ] );

                And the template code to reference it might look like:

        <t:loop name=names>
        First name: <t:var name=first/>
        Last name: <t:var name=last/>
        </t:loop>

                Any other t:* directives can be nested inside the t:loop

                Within a loop there are some special variables.  !loop
                is the current loop count, !.. will take you back
                a namespace level, and !_ is the current value.

        <t:with name=object></t:with>

                Shifts the namespace.  For example, if you have
                registered:

                {
                        colors =>
                                {
                                        red => 'ff0000',
                                        blue => '0000ff'
                                }
                        default => 'ff00ff'
                }

                You can:
        <t:with name=colors>
        Red is <t:var name=red/> and blue is <t:var name=blue/>
        </t:with>
        Default is <t:var name=default/>

        <t:set name=variable value=newvalue/>

                Sets a variable in the current scope.  You should
                avoid this if possible.  Better to set the code in
                the script.

        <t:lcount value=when></t:lcount>

                Runs the code when loopcount is equal to 'when'.  Count
                starts from 1.

        <t:lmod ></t:lmod>

                Shows the code in >< if the current loop count mod N
                if equal to 0.  Good for making every other row of
                a table grey, etc.


AUTHOR

Copyright (c) 2001 Steve Slaven <bpk@hoopajoo.net> All rights reserved.

This program is free software and is provided ``as is'' without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.