Denis Petrov > Text-Templet > Text::Templet

Download:
Text-Templet-3.0.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 3.0   Source  

NAME ^

Text::Templet - general purpose text template processor

SYNOPSIS ^

Iterating through a list

 use Text::Templet;
 use vars qw( $dataref $counter );
 $dataref = ["Money For Nothing","Communique","Sultans Of Swing"];

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% $counter = -1 %>
 <%SONG_LIST%>
 <% $counter++; return "SONG_LIST_END" if $counter >= scalar(@$dataref); '' %>
 <div>
 $counter: $dataref->[$counter]
 </div>
 <%"SONG_LIST"%><%SONG_LIST_END%>
 </body>
 EOT
 );

Iterating through a list using asterisk label

 use Text::Templet;
 use vars qw( $dataref $counter );
 $dataref = ["Money For Nothing","Communique","Sultans Of Swing"];

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% $counter = -1 %>
 <%SONG_LIST%><% $counter++; return "*SONG_LIST" if $counter >= scalar(@$dataref); '' %>
 <div>
 $counter: $dataref->[$counter]
 </div>
 <%*SONG_LIST%>
 </body>
 EOT
 );

Conditional inclusion

 use Text::Templet;
 use vars qw($super_user);
 $super_user = 1;

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% "SKIP_CP" unless $super_user %>
 Admin Options: <a href="control_panel.pl">Control Panel</a>
 <%SKIP_CP%>
 </body>
 EOT
 );

Alternative inclusion

 use Text::Templet;
 use vars qw($super_user);
 $super_user = 1;

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% "*SKIP_CP" unless $super_user %>
 Admin Options: <a href="control_panel.pl">Control Panel</a>
 <%*SKIP_CP%>
 No Admin options available.
 <%SKIP_CP%>
 </body>
 EOT
 );

Switch-like construct

 use Text::Templet;
 use vars qw($super_user);
 $select = 1;

 $select = 0 if ( int($select) < 0 or int($select) > 2 );

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% "*SEL".int($select) %>
 <%*SEL0%>
 Select is 0
 <%SEL0%>
 <%*SEL1%>
 Select is 1
 <%SEL1%>
 <%*SEL2%>
 Select is 2
 <%SEL2%>
 </body>
 EOT
 );

Calling a Perl subroutine from inside a template

 use Text::Templet;

 sub hello_world()
 {
     print "Hello, World!";
 }

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% hello_world(); '' %>
 </body>
 EOT
 );

Using subroutine return value as a label

 use Text::Templet;

 sub give_me_label()
 {
     return 'L1';
 }

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <% give_me_label(); %>
 This text will be omitted.
 <%L1%>
 </body>
 EOT
 );

A simple form

 use Text::Templet;
 use CGI;
 use vars qw( $title $desc );
 $title = "Title here!";
 $desc = "Description Here!";
 $title = &CGI::escapeHTML($title||'');
 $desc = &CGI::escapeHTML($desc||'');

 Templet(<<'EOT'
 Content-type: text/html

 <body>
 <form method="POST" action="submit.pl">
 <input name="title" size="60" value="$title">
 <textarea name="desc" rows="3" cols="60">$desc</textarea>
 <input type="submit" name="submit" value="Submit">
 </form>
 </body>
 EOT
 );

Sending output to a disk file

 use Text::Templet;
 local *FILE;
 open( FILE, '>page.html' ) or warn("Unable to open file page.html: $!"), return 1;
 my $saved_stdout = select(*FILE);

 Templet(<<'EOT'
 <body>
 Hello, World!
 </body>
 EOT
 );

 select($saved_stdout);
 close FILE;

Saving output in a variable

 use Text::Templet;

 my $output = Templet(<<'EOT'
 <body>
 Hello, World!
 </body>
 EOT
 );

 print $output;

Includes

 use Text::Templet;
 use vars qw($title $text);
 $title = 'Page Title';
 $text = 'Page Body';

 sub header
 {
   Templet('<html><head><title>$title</title></head><body>');
   ''
 }

 sub footer
 {
   Templet('</body></html>');
   ''
 }


 Templet(<<'EOT'
 Content-type: text/html

 <% header() %>
 <h1>$title</h1>
 <div>
 $text
 </div>
 <% footer() %>
 EOT
 );

A structured application

 use CGI;
 use Text::Templet;
 use vars qw($body_sub $title);

 $Q = new CGI;

 if ( $Q->param('p') eq 'page1' )
 {
   $title = 'Page 1';
   $body_sub = sub
   {
     Templet('Page 1');
   }
 }
 elseif ( $Q->param('p') eq 'page2' )
 {
   $title = 'Page 2';
   $body_sub = sub
   {
     Templet('Page 2');
   }
 }
 else
 {
   $title = 'Default Page';
   $body_sub = sub
   {
     Templet('Default Page');
   }
 }

 Templet(<<'EOT'
 Content-type: text/html

 <html><head><title>$title</title></head>
 <body>
 <h1>$title</h1>
 <div>
 <% &$body_sub(); '' %>
 </div>
 </body></html>
 EOT
 );

Using &Text::Templet::Use

File Module.pm:

 package Module;

 use vars qw($title);

 $title = 'Page Title';

File script.pl:

 use lib qw(.);
 use Text::Templet;

 Templet(<<'EOT'
 Content-type: text/html

 <% Text::Templet::Use("Module");'' %>
 <html><head><title>$title</title></head>
 <body>
 <h1>$title</h1>
 </body></html>
 EOT
 );

DESCRIPTION ^

RATIONALE

I was motivated to create Text::Templet when I was looking for a templating system for a project. A bit of research revealed several major shortcomings of most if not all existing modules: they are bloated, slow, complex and often poorly documented. I did not want to learn a whole new programming language and environment just to create a simple web application, and I felt it was unnecessary to drag thousands of lines of Perl modules along. Looking at Template Toolkit or Mason I was thinking there has to be a better way.

Text::Templet employs Perl's eval() function which allows you to use Perl syntax for all of its functionality, which greatly simplifies and speeds up processing of the template.

DOCUMENTATION

Text::Templet is a Perl module implementing a very efficient and fast template processor that allows you to embed Perl variables and snippets of Perl code directly into HTML, XML or any other text.

In the examples above the template text is embedded into the Perl code, but it could just as easily be loaded from a file or a database. Text::Templet does not impose any particular application framework or CGI library or information model on you. You can pick any of the existing systems or integrate Text::Templet into your own.

When called, Templet() applies a regular expression matching text enclosed within <% %> to create a list of sections. These sections are then passed to the eval() function. Sections containing text outside <% %> ("Template text sections") are wrapped into double quotes and passed to eval() for variable expansion. In void context, the value returned by the eval() is printed to the standard output, otherwise it is appended to the return value stored in $_outt.

Sections with text inside <% %> are handled in two different ways. If the text contains only alphanumeric characters without spaces, and the first character is an asterisk, a letter or an underscore, Text::Templet recognizes the section as a "label", which is then added to the internal list of labels. Labels are used to pass template processing point to the section immediately following the label, very similar to the way labels used in many programming languages to move the execution point of a program.

If it is not a label, then it is a template code section, which is passed to eval() for execution as Perl code. The return value of a code section is then used as the name of the label to jump to, allowing you to implement loops, conditionals and any other control statements using Perl code. A warning is produced if the label with that name is not found in the template, and the text that does not represent a valid label name is discarded.

When a portion of a template is contained between two labels, named identically except the first one pre-pended with "*" (asterisk), this portion will be skipped in the normal flow of template processing, and can only be reached by returning the name of the label with the asterisk from a code section. This simplifies the syntax of conditionals, switches and other types of constructs. The following two examples are equivalent, one is written using an asterisk label and the other is not:

 <% "*SKIP" unless $condition %>
 Text displayed when the condition is true
 <%*SKIP%>
 Text displayed when the condition is false
 <%SKIP%>

 <% "ELSE" unless $condition %>
 Text displayed when the condition is true
 <%"ELSE_END"%><%ELSE%>
 Text displayed when the condition is false
 <%ELSE_END%>

All package variables that you plan to use in the template must be declared with use vars - code and variable names embedded into the template are evaluated in the namespace of the calling package, but are contained in the lexical scope of Templet.pm. This means that lexical variables declared with my, our or local are inaccessible from "inside" the template.

The following variable names are used internally by Text::Templet and will mask variables declared in your program, making their values inaccessible in the template: %_labels, @_tpl_parsed, @_tpl_compiled, $_isect, $_outt

FUNCTIONS

&Templet()

Exported. Takes one or two arguments: first argument is the template text, second argument is optional and contains the name of the package to use when evaluating section text and code.

In void context, prints processing result to the default output, otherwise accumulates it in an internal variable $_outt and returns it to the caller. If a compilation error occurs in a code section of the template, calls die() with the error code, which allows you to put a call to Templet() into an eval block to process compilation errors. You should check the server's error log to find out which section it is.

&Text::Templet::Use()

Accepts one argument containing the name of the package to use when evaluating template sections. The value will be used when calling code and interpolating text sections to set the context for any code and variables used in the template. This function can be called either prior to Templet() call or from within the template text, in which case the package name will be used from the code section containing the call onwards until the end of the template or the next call to Text::Templet::Use().

To cancel, call Text::Templet::Use(undef). Package specified in the call to Templet() takes precedence over package specified in Use().

NOTES AND TIPS

AUTHOR ^

Denis Petrov <dp@denispetrov.com>

For more examples and support, visit Text::Templet Home at http://www.denispetrov.com/magic/

syntax highlighting: