|
NAMETemplate::Simple - A simple and very fast template moduleVERSIONVersion 0.03SYNOPSISuse Template::Simple; my $tmpl = Template::Simple->new(); # here is a simple template store in a scalar # the header and footer templates will be included from the cache or files. my $template_text = <<TMPL ; [%INCLUDE header%] [%START row%] [%first%] - [%second%] [%END row%] [%INCLUDE footer%] TMPL # this is data that will be used to render that template the keys # are mapped to the chunk names (START & END markups) in the # template the row is an array reference so multiple rows will be # rendered usually the data tree is generated by code instead of # being pure data. my $data = { header => { date => 'Jan 1, 2008', author => 'Me, myself and I', }, row => [ { first => 'row 1 value 1', second => 'row 1 value 2', }, { first => 'row 2 value 1', second => 'row 2 value 2', }, ], footer => { modified => 'Aug 31, 2006', }, } ; # this call renders the template with the data tree my $rendered = $tmpl->render( \$template_text, $data ) ; # here we add the template to the cache and give it a name $tmpl->add_templates( { demo => $template_text } ) ; # this compiles and then renders that template with the same data # but is much faster $tmpl->compile( 'demo' ) ; my $rendered = $tmpl->render( 'demo', $data ) ; DESCRIPTIONTemplate::Simple is a very fast template rendering module with a simple markup. It can do almost any templating task and is extendable with user callbacks. It can render templates directly or compile them for more speed.CONSTRUCTORnewYou create a Template::Simple by calling the class method new:my $tmpl = Template::Simple->new() ; All the arguments to "new()" are key/value options that change how the object will render templates. pre_delimThis option sets the string or regex that is the starting delimiter for all markups. You can use a plain string or a qr// but you need to escape (with \Q or \) any regex metachars if you want them to be plain chars. The default is qr/\[%/.my $tmpl = Template::Simple->new( pre_delim => '<%', ); my $rendered = $tmpl->render( '<%FOO%]', 'bar' ) ; post_delimThis option sets the string or regex that is the ending delimiter for all markups. You can use a plain string or a qr// but you need to escape (with \Q or \) any regex metachars if you want them to be plain chars. The default is qr/%]/.my $tmpl = Template::Simple->new( post_delim => '%>', ); my $rendered = $tmpl->render( '[%FOO%>', 'bar' ) ; token_reThis option overrides the regular expression that is used match a token or name in the markup. It should be a qr// and you may need to escape (with \Q or \) any regex metachars if you want them to be plain chars. The default is qr/\w+?/.my $tmpl = Template::Simple->new( token_re => qr/[\w-]+?/, ); my $rendered = $tmpl->render( '[% id-with-hyphens %]', { 'id-with-hyphens' => 'bar' } ) ; greedy_chunkThis boolean option will cause the regex that grabs a chunk of text between the "START/END" markups to become greedy (.+). The default is a not-greedy grab of the chunk text. (UNTESTED)templatesThis option lets you load templates directly into the cache of the Template::Simple object. See <TEMPLATE CACHE> for more on this.my $tmpl = Template::Simple->new( templates => { foo => <<FOO, [%baz%] is a [%quux%] FOO bar => <<BAR, [%user%] is not a [%fool%] BAR }, ); search_dirs, include_pathsThis option lets you set the directory paths to search for template files. Its value is an array reference with the paths. Its default is 'templates'.my $tmpl = Template::Simple->new( search_dirs => [ qw( templates templates/deeper ) ], ) ; NOTE: This option was called "include_paths" but since it is used to locate named templates as well as included ones, it was changed to "search_dirs". The older name "include_paths" is still supported but new code should use "search_dirs". METHODSrenderThis method is passed a template and a data tree and it renders it and returns a reference to the resulting string.If the template argument is a scalar reference, then it is the template text to be rendered. A scalar template argument is first assumed to be a template name which is searched for in the template cache and the compiled template caches. If found in there it is used as the template. If not found there, it is searched for in the directories of the "search_dirs". Finally if not found, it will be used as the template text. The data tree argument can be any value allowed by Template::Simple when rendering a template. It can also be a blessed reference (Perl object) since "Scalar::Util::reftype" is used instead of "ref" to determine the data type. Note that the author recommends against passing in an object as this breaks encapsulation and forces your object to be (most likely) a hash. It would be better to create a simple method that copies the object contents to a hash reference and pass that. But other current templaters allow passing in objects so that is supported here as well. my $rendered = $tmpl->render( $template, $data ) ; compileThis method takes a template and compiles it to make it run much faster. Its only argument is a template name and that is used to locate the template in the object cache or it is loaded from a file (with the same search technique as regular rendering). The compiled template is stored in its own cache and can be rendered by a call to the render method and passing the name and the data tree.$tmpl->compile( 'foo' ) ; my $rendered = $tmpl->render( 'foo', $data ) ; There are a couple of restrictions to compiled templates. They don't support code references in the data tree (that may get supported in the future). Also since the include expansion happens one time during the compiling, any changes to the template or its includes will not be detected when rendering a compiled template. You need to re-compile a template to force it to use changed templates. Note that you may need to delete templates from the object cache (with the delete_templates method) to force them to be reloaded from files. add_templatesThis method adds templates to the object cache. It takes a list of template names and texts just like the "templates" constructor option. These templates are located by name when compiling or rendering.$tmpl->add_templates( { foo => \$foo_template, bar => '[%include bar%]', } ) ; delete_templatesThis method takes a list of template names and will delete them from the template cache in the object. If you pass no arguments then all the cached templates will be deleted. This can be used when you know a template file has been updated and you want to get it loaded back into the cache.# this deletes only the foo and bar templates from the object cache $tmpl->delete_templates( qw( foo bar ) ; # this deletes all of templates from the object cache $tmpl->delete_templates() ; get_source$tmpl->get_source( 'bar' ) ; This method is passed a compiled template name and returns the generated Perl source for a compiled template. You can compile a template and paste the generated source (a single sub per template) into another program. The sub can be called and passed a data tree and return a rendered template. It saves the compile time for that template but it still needs to be compiled by Perl. This method is also useful for debugging the template compiler. TEMPLATE CACHEThis cache is stored in the object and will be searched to find any template by name. It is initially loaded via the "templates" option to new and more can be added with the "add_templates" method. You can delete templates from the cache with the "delete_templates" method. Compiled templates have their own cache in the module. Deleting a template also deletes it from the compiled cache.INCLUDE EXPANSIONBefore a template is either rendered or compiled it undergoes include expansion. All include markups are replaced by a templated located in the cache or from a file. Included templates can include other templates. This expansion keeps going until no more includes are found.LOCATING TEMPLATESWhen a template needs to be loaded by name (when rendering, compiling or expanding includes) it is first searched for in the object cache (and the compiled cache for compiled templates). If not found there, the "templates_paths" are searched for files with that name and a suffix of .tmpl. If a file is found, it used and also loaded into the template cache in the object with the searched for name as its key.MARKUPAll the markups in Template::Simple use the same delimiters which are "[%" and "%]". You can change the delimiters with the "pre_delim" and "post_delim" options in the "new()" constructor.TokensA token is a single markup with a "\w+" Perl word inside. The token can have optional whitespace before and after it. A token is replaced by a value looked up in a hash with the token as the key. The hash lookup keeps the same case as parsed from the token markup. You can override the regular expression used to match a token with the "token_re" option.[% foo %] [%BAR%] Those will be replaced by "$href-"{foo}> and "$href-"{BAR}> assuming $href is the current data for this rendering. Tokens are only parsed out during hash data rendering so see Hash Data for more. ChunksChunks are regions of text in a template that are marked off with a start and end markers with the same name. A chunk start marker is "[%START name%]" and the end marker for that chunk is "[%END name%]". "name" is matched with "\w+?" and that is the name of this chunk. The whitespace between "START/END" and "name" is required and there is optional whitespace before "START/END" and after the "name". "START/END" are case insensitive but the "name"'s case is kept. Chunks are the primary way to markup templates for structures (sets of tokens), nesting (hashes of hashes), repeats (array references) and callbacks to user code. By default a chunk will be a non-greedy grab but you can change that in the constructor by enabling the "greedy_chunk" option. You can override the regular expression used to match the chunk name with the "token_re" option.[%Start FOO%] [% START bar %] [% field %] [% end bar %] [%End FOO%] IncludesWhen a markup "[%include name%]" is seen, that text is replaced by the template of that name. "name" is matched with "\w+?" which is the name of the template. You can override the regular expression used to match the include "name" with the "token_re" option.See "INCLUDE EXPANSION" for more on this. RENDERING RULESTemplate::Simple has a short list of rendering rules and they are easy to understand. There are two types of renderings, include rendering and chunk rendering. In the "render" method, the template is an unnamed top level chunk of text and it first gets its "INCLUDE" markups rendered. The text then undergoes a chunk rendering and a scalar reference to that rendered template is returned to the caller.Include RenderingAll include file rendering happens before any other rendering is done. After this phase, the rendered template will not have "[%include name%]" markups in it.Chunk RenderingA chunk is the text found between matching "START" and "END" markups and it gets its name from the "START" markup. The top level template is considered an unamed chunk and also gets chunk rendered.The data for a chunk determines how it will be rendered. The data can be a scalar or scalar reference or an array, hash or code reference. Since chunks can contain nested chunks, rendering will recurse down the data tree as it renders the chunks. Each of these renderings are explained below. Also see the IDIOMS and BEST PRACTICES section for examples and used of these renderings.
DESIGN GOALS
BUGSPlease report any bugs or feature requests to "bug-template-simple at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Simple>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
ACKNOWLEDGEMENTSI wish to thank Turbo10 for their support in developing this module.LICENSESame as Perl. COPYRIGHTCopyright 2011 Uri Guttman, all rights reserved.SEE ALSOAn article on file slurping in extras/slurp_article.pod. There is also a benchmarking script in extras/slurp_bench.pl.AUTHORUri Guttman, <uri@stemsystems.com>
Visit the GSP FreeBSD Man Page Interface. |