/ 
Text-MiniTmpl-1.0.0
River stage zero No dependents
/ Text::MiniTmpl

NAME

Text::MiniTmpl - Compile and render templates

SYNOPSIS

use Text::MiniTmpl qw( render );

$html1 = render('template.html', %params1);
$html2 = render('template.html', %params2);

DESCRIPTION

Compile templates with embedded perl code into anonymous subroutines. These subroutines can be (optionally) cached, and executed to render these templates with (optional) parameters.

Perl code in templates will be executed with:

use warnings;
use strict;

Recursion in templates is supported (you can call render() or tmpl2code() inside template to "include" another template inside current one). Path name to included template can be set in several ways:

  • path relative to current template's directory: 'file', 'dir/file', '../file'

  • path relative to current working directory (where your script executed): './file', './dir/file'

  • absolute path: '/dir/file'

When you render top-level template (i.e. call render() from your script, not inside some template) paths 'file' and './file' , 'dir/file' and './dir/file' are same.

Correctly report compile errors in templates, with template name and line number.

Unicode support

Files with templates should be in UTF8. Parameters for templates should be perl Unicode scalars. Rendered template (returned by render() or by function returned by tmpl2code()) will be in UTF8.

Template syntax

Any template become perl function after parsing. This function will accept it parameters in %_ (it start with local %_ = @_; ). Of course, you can use my() and local() variables in template (their scope will be full template, not only placeholder's block where they was defined).

&~ PERL CODE ~&
<!--& PERL CODE -->

Execute PERL CODE but don't output anything.

@~ PERL CODE ~@

Execute PERL CODE and output it result (last calculated expression) escaped using HTML::Entities::encode_entities().

^~ PERL CODE ~^

Execute PERL CODE and output it result (last calculated expression) escaped using URI::Escape::uri_escape_utf8().

#~ PERL CODE ~#

Execute PERL CODE and output it result (last calculated expression) AS IS, without any escaping.

any other text ...

... will be output AS IS

Example templates:

To: #~ $_{email} ~#
Hello, #~ $username ~#. Here is items your asked for:
&~ for (@{ $_{items} }) { ~&
    #~ $_ ~#
&~ } ~&

---cut header.html---
<html>
<head><title>@~ $_{pagetitle} ~@</title></head>
<body>

---cut index.html---
#~ render('header.html', pagetitle=>'Home') ~#
<p>Hello, @~ $_{username} ~@.</p>
&~ # In HTML you may prefer <!--& instead of &~ for code blocks ~&
<!--& for (@{ $_{topics} }) { -->
<a href="news.cgi?topic=^~ $_ ~^&user=^~ $_{user} ~^">
    News about @~ $_ ~@
</a>
<!--& } -->
#~ render('footer.html') ~#

---cut footer.html---
</body>
</html>

EXPORTS

Nothing by default, but all documented functions can be explicitly imported.

INTERFACE

render( $filename, %params )

Render template from $filename with %params.

This is caching wrapper around tmpl2code(), which avoid calling tmpl2code() second time for same $filename.

Example:

$html = render( 'template/index.html',
    title   => $title,
    name    => $name,
);

Return STRING with rendered template.

tmpl2code( $filename )

Read template from $filename (may be absolute or relative to current template's directory or current working directory - see "DESCRIPTION"), compile it into ANON function.

This function can be executed with ( %params ) parameters, it will render $filename template with given %params and return SCALARREF to rendered text.

Example:

$code = tmpl2code( 'template/index.html' );
$html = ${ $code->( title=>$title, name=>$name ) };

Return CODEREF to that function.

encode_js( $scalar )

Encode $scalar (string or number) for inserting into JavaScript code (usually inside HTML templates).

Example:

<script>
var int_from_perl =  #~ encode_js($number) ~#;
var str_from_perl = '#~ encode_js($string) ~#';
</script>

Return encoded string.

encode_js_data( $complex )

Encode $complex data structure (HASHREF, ARRAYREF, etc. - any data type supported by JSON::XS) for inserting into JavaScript code (usually inside HTML templates).

Example:

<script>
var hash_from_perl  = #~ encode_js_data( \%hash ) ~#;
var array_from_perl = #~ encode_js_data( \@array ) ~#;
</script>

Return encoded string.

BUGS AND LIMITATIONS

No bugs have been reported.

SUPPORT

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

You can also look for information at:

AUTHOR

Alex Efros <powerman-asdf@ya.ru>

LICENSE AND COPYRIGHT

Copyright 2007-2010 Alex Efros <powerman-asdf@ya.ru>.

This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.