Template toolkit lowercase

It is disabled by default and any attempt to load a template by such a name will cause a ' file ' exception to be raised. On Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to also detect filenames that start with a driver letter and colon, such as:.

It is also disabled by default, and will raise a ' file ' error if such template names are encountered. Note that the DEFAULT template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. These should be specified as a reference to a hash array mapping template names to template text, subroutines or Template::Document objects.

They can be specified as a reference to a hash array or list reference. Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition.

This ensures that any BLOCK s defined within a template will only persist until that template is finished processing. This prevents BLOCK s defined in one processing request from interfering with other independent requests subsequently processed by the same context object.

The template processor will raise a file exception if it detects direct or indirect recursion into a template. Setting this option to any true value will allow templates to include each other recursively.

These variables are resolved once when the template is compiled, and thus don't require further resolution at runtime. This results in significantly faster processing of the compiled templates and can be used for variables that don't change from one request to the next. Constant variables are accessed via the constants namespace by default. The constant folding mechanism described above is an example of a namespace handler.

Namespace handlers can be defined to provide alternate parsing mechanisms for variables in different namespaces. Under the hood, the Template module converts a constructor configuration such as:. You can use this mechanism to define multiple constant namespaces, or to install custom handlers of your own. See Template::Namespace::Constants for an example of what a namespace handler looks like on the inside. The following options are used to specify any additional templates that should be processed before, after, around or instead of the template passed as the first argument to the Template process method.

These options can be perform various useful tasks such as adding standard headers or footers to all pages, wrapping page output in other templates, pre-defining variables or performing initialisation or cleanup tasks, automatically generating page summary information, navigation elements, and so on. The task of processing the template is delegated internally to the Template::Service module which, unsurprisingly, also has a process method. WRAPPER templates don't need to worry about explicitly processing the template because it will have been done for them already.

If the main template throws an exception during processing then any relevant template s defined via the ERROR option will be processed instead. Multiple templates may be specified as a reference to a list. Each is processed in the order defined. Alternately, multiple template may be specified as a single string, delimited by ' : '. Metadata items defined via the META directive may be accessed accordingly. A reference to the original template is available in the template variable.

Metadata items can be inspected and the template can be processed by specifying it as a variable reference i. The WRAPPER option can be used to specify one or more templates which should be used to wrap around the output of the main page template. The WRAPPER templates will be processed in reverse order with the output of each being passed to the next or previous, depending on how you look at it as the 'content' variable. It sounds complicated, but the end result is that it just "Does The Right Thing" to make wrapper templates nest in the order you specify.

You can use this to good effect in allowing page templates to set pre-defined values which are then used in the wrapper templates. For example, our main page template 'foo' might look like this:. The foo template is processed before the wrapper template meaning that the page data structure will be defined for use in the wrapper template.

It achieves the same effect as defining META items which are then accessed via the template variable which you are still free to use within WRAPPER templates , but gives you more flexibility in the type and complexity of data that you can define. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed.

If specified as a single value then that template will be processed for all uncaught exceptions. If the ERROR item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected.

A default template may be provided for the general case. Note that exception types are hierarchical and a foo handler will catch all foo. Be sure to quote any exception types that contain periods to prevent Perl concatenating them into a single string i. Similarly, a user. This is automagically caught and converted to an exception of ' undef ' type which can then be handled in the usual way.

Note that the ' undef ' we're talking about here is a literal string rather than Perl's undef used to represent undefined values. At some point in the future, using a different invocation of the Template Toolkit, you may come to process such a pre-compiled template. Regular PERL blocks are a little more cautious, however. Thus you can compile templates to include PERL blocks, but optionally disable them when you process them later.

Otherwise you must accept the fact that there's no bulletproof way to prevent any included code from trampling around in the living room of the runtime environment, making a real nuisance of itself if it really wants to. Default output location or handler. GLOB or IO::Handle opened for writing; a reference to a text string to which the output is appended the string isn't cleared ; a reference to a subroutine which is called, passing the output text as an argument; as a reference to an array, onto which the content will be push ed; or as a reference to any object that supports the print method.

This can be specified as any of the above argument types. By default the Template Toolkit will silently ignore the use of undefined variables a bad design decision that I regret. You can also specify expressions using the logical and , or , not ,? The div operator returns the integer result of division.

This can be useful when a variable is bound to a sub-routine or object method which you want to call but aren't interested in the value returned. The SET directive allows you to assign new values to existing variables or create new temporary variables. Variables may be assigned the values of other variables, unquoted numbers 2.

In the latter case, any variable references within the text will be interpolated when the string is evaluated. Multiple variables may be assigned in the same directive and are evaluated in the order specified. Thus, the above could have been written:. In Perl 5, the. Note that the operator must be specified with surrounding whitespace which, as Larry says, is construed as a feature:.

You can, of course, achieve a similar effect with double quoted string interpolation. This can be particularly useful in common template components to ensure that some sensible default are provided for otherwise undefined variables.

No attempt to parse or process the file is made. The contents, possibly including any embedded template directives, are inserted intact.

Absolute i. Both these options are disabled by default. For convenience, the filename does not need to be quoted as long as it contains only alphanumeric characters, underscores, dots or forward slashes. Names containing any other characters should be quoted. All files should be unquoted names or quoted strings. Any variables should be interpolated into double-quoted strings.

If a BLOCK of the specified name is defined in the same file, or in a file from which the current template has been called i. Any template directives embedded within the file will be processed accordingly. All variables currently defined will be visible and accessible from within the included template. Local variable definitions may be specified after the template name, temporarily masking any existing variables.

Insignificant whitespace is ignored within directives so you can add variable definitions on the same line, the next line or split across several line with comments interspersed, if you prefer. Any changes made within the included template will not affect variables in the including template.

Technical Note: the localisation of the stash that is, the process by which variables are copied before an INCLUDE to prevent being overwritten is only skin deep. The top-level variable namespace hash is copied, but no attempt is made to perform a deep-copy of other structures hashes, arrays, objects, etc. Therefore, a foo variable referencing a hash will be copied to create a new foo variable but which points to the same hash array. Thus, if you update compound variables e. If you're not worried about preserving variable values, or you trust the templates you're including then you might prefer to use the PROCESS directive which is faster by virtue of not performing any localisation.

However, be aware that because of the localisation issues explained above if you skipped the previous Technical Note above then you might want to go back and read it or skip this section too , the variables might not actually be "local".

If the first element of the variable name already references a hash array then the variable update will affect the original variable. This behaviour can be a little unpredictable and may well be improved upon in a future version. If you know what you're doing with it and you're sure that the variables in question are defined nor not as you expect them to be, then you can rely on this feature to implement some powerful "global" data sharing techniques.

Otherwise, you might prefer to steer well clear and always pass simple undotted variables as parameters to INCLUDE and other similar directives. The variable stash is localised once and then the templates specified are processed in order, all within that same variable context. This makes it slightly faster than specifying several separate INCLUDE directives because you only clone the variable stash once instead of n times , but not quite as "safe" because any variable changes in the first file will be visible in the second, third and so on.

This might be what you want, of course, but then again, it might not. Any changes made to variables within the included template will be visible in the including template. It's not unusual to find yourself adding common headers and footers to pages or sub-sections within a page. Something like this:. The individual template components being included might look like these:. It encloses a block up to a matching END directive, which is first processed to generate some output. The specification order indicates outermost to innermost wrapper templates.

For example, given the following template block definitions:. A BLOCK definition can be used before it is defined, as long as the definition resides in the same file. The block definition itself does not generate any output. Like a named block, it can contain any other template directives which are processed when the block is defined.

The output generated by the block is then assigned to the variable julius. The enclosing block is processed each time the macro is called. Conditions may be arbitrarily complex and are evaluated with the same precedence as in Perl.

Parenthesis may be used to explicitly determine evaluation order. Each CASE directive should contain a single value or a list of values which should match. When the FOREACH directive is used without specifying a target variable, any iterated values which are hash references will be automatically imported.

Note that this particular usage creates a localised variable context to prevent the imported hash keys from overwriting any existing variables. The imported definitions and any other variables defined in such a FOREACH loop will be lost at the end of the loop, when the previous context and variable values are restored. However, under normal operation, the loop variable remains in scope after the FOREACH loop has ended caveat: overwriting any variable previously in scope.

This is useful as the loop variable is secretly an iterator object see below and can be used to analyse the last entry processed by the loop. Each entry in the hash is returned in sorted order based on the key as a hash array containing 'key' and 'value' items. The LAST directive can be used to prematurely exit the loop. The following methods can be called on the loop iterator.

See Template::Iterator for further details. Nested loops will work as expected, with the loop variable correctly referencing the innermost loop and being restored to any previous value i. The iterator plugin can also be used to explicitly create an iterator object. This can be useful within nested loops where you need to keep a reference to the outer iterator within the inner loop.

The iterator plugin effectively allows you to create an iterator by a name other than loop. See Template::Plugin::Iterator for further details. The WHILE directive can be used to repeatedly process a template block while a conditional expression evaluates true. An assignment can be enclosed in parenthesis to evaluate the assigned value.

If the loop exceeds iterations then an undef exception will be thrown, reporting the error:. A number of standard filters are provided with the Template Toolkit. Up My name is Meles Meles , but you can call me "Badger".

Next About the Template Toolkit. The Badger Book The Template Toolkit is a fast, flexible and highly extensible template processing system. All Rights Reserved. The Template Toolkit is Open Source software.