The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Text-EasyTemplate-0.01
River stage zero No dependents
/ Text::EasyTemplate

NAME

Text::EasyTemplate - A simple text template system.

VERSION

Version 0.01

SYNOPSIS

A simple text template system without a lot of complex and unnecessary features present in other existing template systems. It aims at ease of use without the need of setting up lots of configurations or complex frameworks. Ideal for simple applications, it can be used for any type of purpose: web, merge mail, or any other type of text.

Here is an example:

        use Text::EasyTemplate;

        my $template = Text::EasyTemplate->new("templates_dir/template_file.txt");
        my $data = {
                VALUE1 => "value",
                VALUE2 => 2,
                CONDITIONAL => 1,
                VALUE3 => localtime()
        };
        my $string = $template->replace($data);

DESCRIPTION

This module is a simple and straightforward alternative to much more complex template toolkits and frameworks. I began development on it because existing Perl modules for handling templates were too complex to use in simple applications.

Templates are used to separate content from presentation. EasyTemplate is simple enough and does not care where the template will be used, so it is not just for web templates; it can be used anyplace dynamic values need to be placed over a pre-defined page layout. A placeholder label is used wherever the dynamic text will appear. These placeholders are in the form [[PLACEHOLDER]]. Although the label can be in either case, uppercase is recommended to make it stand out more from the contents of the template. Double square brackets where chosen since these characters are rarely used this way in documents.

A simple template would look like:

        Hello [[WHO]]!

To create a new EasyTemplate instance, the constructor new() is used and supply as an argument the name of the file containing the template:

        my $template = Text::EasyTemplate->new("hello_template.txt");

A simple hash needs to be created with all the pair-values of placeholder labels and their corresponding value to be replaced within the template. For the example above, the following hash would be used:

        my %data = ( WHO => 'World' );

The replace() method takes as argument a reference to such hash and returns a string containing the resulting text string:

        my $text = $template->replace(\%data);

A slightly better way to do this would be;

        my $data = { WHO => 'World' };
        my $text = $template->replace($data);

The resulting text string would be, as expected,

        Hello World!

Simple conditionals can also be used with EasyTemplate:

        Good [[IF MORNING]]morning[[ELSE]]day[[ENDIF]]!

and when creating the hash with the label-value pairs, any true value will do:

        my $data = { MORNING => 1 };

The end result:

        Good morning!

Complex document layouts can be achieved by concatenating the results from several template replacements:

        my $header = Text::EasyTemplate->new("header.txt");
        my $body = Text::EasyTemplate->new("body.txt");
        my $row = Text::EasyTemplate->new("row.txt");
        my $footer = Text::EasyTemplate->new("footer.txt");
        
        ...

        my $string = "";
        $string .= $header->replace($header_data);
        my $rows = "";
        foreach my element (@rowset) {
                $rows .= $row->replace($current_row_data);
        }
        $string .= $body->replace($body_data);
        $string .= $footer->replace($footer_data);

METHODS

new

You can create a new instance with this constructor. It takes as an argument the name of the template file. This name is in string form and can contain either the absolute or relative path to the file. The contents of the file are kept in memory in case the same template will be used multiple times on the same page.

        my $template = Text::EasyTemplate->new("templates_dir/template_file.txt");

replace

Takes as an argument a reference to a hash. Each key in the hash is the placeholder used in the template file and will be replaced with its value. If using conditionals, the values for true and false are the same as those used in Perl.

        my $text = $template->replace($data);

AUTHOR

Luis Chavez, <lchavez at andrew.cmu.edu>

TODO

Things that needs to be done in future versions:

  • Better error handling and syntax checking for labels and if-else-endif structures.

  • Nested conditionals.

  • Supply template as string, as an additional option to a file.

BUGS

Please report any bugs or feature requests to bug-simpletemplate at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SimpleTemplate. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::EasyTemplate

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2006 Luis Chavez, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html