Dotiac::DTL::Core - Common functions for Dotiac::DTL and Dotiac::DTL::Reduced
require Dotiac::DTL; $t=Dotiac::DTL->new("file.html") $t->print(); require Dotiac::DTL::Reduced; $t=Dotiac::DTL->new("compiled.html") #Works only with compiled templates $t->print();
This module includes the detailed documentation on the functions used by Dotiac::DTL and Dotiac::DTL::Reduced.
These are Settings that modify the behavior of Dotiac::DTL and should be set to your preferences.
Defines what value should be inserted if a variable is not found. Defaults to "";
require Dotiac::DTL; my $data="Hello, {{ asfdsfsdfasdf }}"; #asfdsfsdfasdf won't be defined. $t=Dotiac::DTL->new(\$data); $t->print(); #prints "Hello, " $Dotiac::DTL::TEMPLATE_STRING_IF_INVALID="[[Not found]]"; $t->print(); #prints "Hello, [[Not found]]";
Setting this to "1" allows methods of objects in the given variables to be called (without parameters).
Setting this to "0" makes the template slightly safer if you can't trust your variables.
Defaults to "1".
Setting this to "1" allows the unsafe ssi-tag to open any file on your filesystem.
Setting this to "2" also allows the tags include and extend to open files anywhere.
Defaults to "0", which allows only files to be opened in the current or subdirectories.
Enables or disables HTML-autoescaping for all templates. Defaults to enabled(1)
require Dotiac::DTL; my $data="Hello, {{ "<World>" }}"; $t=Dotiac::DTL->new(\$data); $t->print(); #prints "Hello, <World>" $Dotiac::DTL::AUTOESCAPING=0; $t->print(); #prints "Hello, <World>";
You could also use the safe filter for a single variable Dotiac::DTL::Filter, or the autoescape tag Dotiac::DTL::Tag::autoescape for an area.
Defines a list of directories in which the exported Template() should look for the template. Defaults to an empty list.
Default format for the {% now %}-tag if there is no format given. (Defaults to 'N j, Y, P')
Default format for the date-filter if there is no format given. (Defaults to 'N j, Y')
Default format for the time-filter if there is no format given. (Defaults to 'P')
Which parser Dotiac::DTL should use. Defaults to "Dotiac::DTL::Parser", the normal Dotiac parser.
You only should change this, if you know what you are doing.
This is used when called from a scalarref to define in what directory the template is (for include)
These are only important to people writing there own Tags. See Dotiac::DTL::Tag for details on that.
These variables are cleared every time print() or string() or similar on the main template is called.
This is used to save in what directory the template is (for include).
This is used for output (during the string()-call of Dotiac::DTL::Value). This defines how deep datastructures are printed if rendered as a Variable. Defaults to 3, set this to 0 to make Arrays and Hashes print as a space.
Contains the content of the named blocks, either as a Dotiac::DTL::Tag like object or a reference to a code reference.
sub eval() { $Dotiac::DTLs::blocks{"main"}=Dotiac::DTL->new("file.html")->{first}; my $sub={ return "Hello World"; }; $Dotiac::DTLs::blocks{"compiled"}=\$sub; }
Used by the cycle tag to store state information, there should be no need to play around with this
Storage space for other tags. You should never store any information that changes in the objects themselves, you should store it in here. The objects won't be resetted on every run.
#In your tag, lets call it counter sub print { $Dotiac::DTLs::globals{counter}->{$self}=1 unless $Dotiac::DTLs::globals{counter}->{$self}=1; print $Dotiac::DTLs::globals{counter}->{$self}++; #or named counters: $Dotiac::DTLs::globals{counter}->{$self->{name}}=1 unless $Dotiac::DTLs::globals{counter}->{$self->{name}}=1; print $Dotiac::DTLs::globals{counter}->{$self->{name}}++; $self->{n}->print(@_); } #And for the compiled output sub perlprint { my ($fh,$id,$level,$digest)=(shift(),shift(),shift(),shift()); #... my $name='"'.$digest."-".$id.'"'; #$digest will be unique in combination with $id. print $fh "\t" x $level,"\$Dotiac::DTLs::globals{counter}->{$name}=1 unless \$Dotiac::DTLs::globals{counter}->{$name}=1;\n"; print $fh "\t" x $level,"print \$Dotiac::DTLs::globals{counter}->{$name}++;\n"; # or named templates, which are even easier here: Just define \$name$id in perl() my ($fh,$id,$level,$digest)=(shift(),shift(),shift(),shift()); print $fh "\t" x $level,"\$Dotiac::DTLs::globals{counter}->{\$name$id}=1 unless \$Dotiac::DTLs::globals{counter}->{\$name$id}=1;\n"; print $fh "\t" x $level,"print \$Dotiac::DTLs::globals{counter}->{\$name$id}++;\n"; #... } #Same for string() of course.
See Dotiac::DTL::Tag for details on what those methods should do.
Stores information on which template is already included to detect cyclic includes. Used by the tags ssi and include. There shouldn't also be any need to change this.
This one differs if you are using Dotiac::DTL or Dotiac::DTL::Reduced, since Dotiac::DTL::Reduced will die on uncompiled Templates and can't compile them. See their documentation for details.
Same as new(), mostly used internally by include and extends. Accepts only relative pathes without leading ".." .
By setting $ALLOWED_INCLUDE_ROOTS to "2" this will be disabeled.
Also depends on if you are using Dotiac::DTL or Dotiac::DTL::Reduced.
Treats PACKAGENAME as a compiled template. See Dotiac::DTL::Compiled.
This is useful to insert perl code into templates.
Returns a Dotiac::DTL object
package MyTemplate; sub print { my ($vars,$escape)=(shift(),shift()); print "There are ".keys(%$vars)." parameters registered and x is $vars->{x}\n"; } sub string { my ($vars,$escape)=(shift(),shift()); return "There are ".keys(%$vars)." parameters registered and x is $vars->{x}\n"; } sub eval { #nothing for now. } package main; require Dotiac::DTL; my $mytemplate=Dotiac::DTL->compiled("MyTemplate"); # now you can use $mytemplate as a normal template. $mytemplate->print({x=>123}); # This doesn't seem quite useful you could easily just write the code here, until you do this: my $templatedata="{% for x in array %}{% include template %}{% endfor %}"; my $t = Dotiac::DTL->new(\$templatedata); #File templates work just as well. $t->print({array=>[1..100],template=>$mytemplate); # This will now include and print the above package a hundert times and # will be a lot faster, depending on the contents of that for loop.
Works like HTML::Templates param() method, will set a param that will be used for output generation.
my $t=Dotiac::DTL->new("file.html"); $t->param(FOO=>"bar"); $t->print(); #Its the same as: my $t=Dotiac::DTL->new("file.html"); $t->print({FOO=>"bar"});
Name of the parameter.
Value to set the parameter to.
Returns the value of the param NAME if VALUE is skipped.
Returns the templates output.
Parameters to give to the template. See Variables below.
Same as string(HASHREF) just for HTML::Template and Django syntax.
You can think of these two being equal:
print $t->string(HASHREF); $t->print(HASHREF);
But string() can cause a lot of memory to be used (on large templates), so print() will print to the default output handle as soon as it has some data, which uses a lot less memory.
Returns nothing.
Escapes a quoted string so it won't contain any special chars the parser might use.
The are for now: Space, tab, newline (Seperates variables in most tags), "," (spereates variables in for and filter arguments), "|" (seperates Filters), ":" (seperates filter and its arguments) and of course "+'.
This is used by Dotiac::DTL::get_variables() and doesn't need to be called anywhere else.
String literals in this implementation can contain:
\n #newline \t #tab \b #backspace \f #formfeed \r #carriage return \" # " \' # ' \{ # { \} # } \\ # \\ \xXX # character with hexadecimal charcode (00 - FF) \x20 = " " \uXXXX # Unicode 16Bit \u0020 = " " \UXXXXXXXX # Unicode 32Bit \u00000020 = " "
inversion of escap().
Called by devar() and apply_filters(), no need to call it anywhere else.
Spilts a string, as given by the parser, into variables, which can be given to devar.
If there are additional arguments, it returns a two dimensional list splitted at the arguments.
Also escapes the quoted strings for safe processing using escap().
This is best explained with some examples:
my @list = Dotiac::DTL::get_varibales("var1 var2|Filter \"String with spaces\""); #@list is then ("var1", "var2|Filter", "`String%20with%spaces`") my %list = Dotiac::DTL::get_varibales("foo|dictsort:'sort by some option' othervar by bar as newvar","as","by"); #%list is then (""=>["foo|dictsort:`sort%20by%20some%20option`","othervar"],as=>["bar"],by=>["newvar"]) #note the first " by " in the string is not being used for splitting #And now without the arguments: my @list = Dotiac::DTL::get_varibales("foo|dictsort:'sort by some option' othervar by bar as newvar"); #@list is then ("foo|dictsort:`sort%20by%20some%20option`","othervar","by","bar","as","newvar")
This is used in compiled templates for variables, it just escapes if ESCAPE is set or doesn't otherwise.
There should be no need to use this anywhere else.
About the same as CGI::escape(STRING), but doesn't work on EBCDIC
Returns a true Value if the object is true or filled (for array and hashrefs) and "" otherwise.
This is needed for the if, ifequal and ifnot equal tags to skip on a lot defineds().
It will return the size of the referenced container of an arrayref or hashref.
It will also try to run the count() method of an object, if available.
Applies FILTER1, FILTER2, ... on a variable and escapes it if needed.
VARS is a hashref which holds all the parameters (The same you would give to string() or print())
ESACPE gives the starting point for the auto-escape (1: autoescape, 0:no autoescape)
print Dotiac::DTL::apply_filters("foo",{},0,"cut:`o`");# prints "f"; print Dotiac::DTL::apply_filters("foo",{var=>"0"},0,"cut:var"); #Also prints "f"; print Dotiac::DTL::apply_filters("<foo>",{},1); #Prints "<foo>"; print Dotiac::DTL::apply_filters("<foo>",{},0); #Prints "<foo>"; print Dotiac::DTL::apply_filters("<foo>",{},1,"safe"); #Prints "<foo>" even when autoescape is on print Dotiac::DTL::apply_filters("<foo>",{},0,"escape"); #Prints "<foo>" # even when autoescape is off
Replaces a string (as returned from get_variables()) with the variable from the part of VARS it references.
VARS is a hashref as given to string() or print()
ESCAPE controls the autoescape behavior (0: off, 1:on)
Returns the resolved variable with all the filters applied, or $Dotiac::DTL::TEMPLATE_STRING_IF_INVALID if the produkt is undef.
print Dotiac::DTL::devar("FOO|lower",{FOO=>"Hello"},1); #prints "hello" print Dotiac::DTL::devar("FOO",{FOO=>"Hello"},1); #prints "Hello" print Dotiac::DTL::devar("`FOO`",{FOO=>"Hello"},1); #prints "FOO" print Dotiac::DTL::devar("`<FOO>`",{},1); #prints "<FOO>" print Dotiac::DTL::devar("`<FOO>`",{},0); #prints "<FOO>" print Dotiac::DTL::devar("`<FOO>|safe`",{},1); #prints "<FOO>" print Dotiac::DTL::devar("`<FOO>|escape`",{},0); #prints "<FOO>"
Same as devar() (see above), but returns undef if the generated variable is undef.
Same as devar() but returns the Dotiac::DTL::Value object.
Same as devar() but returns always the content and does no escaping or pretty printing.
Same as devar() but returns always the a representation without escaping. Use this, if the variable is not for printing or is going to be escaped some other way
Similar as devar(). But it won't accept filters in RAWVARIABLE and returns a Dotiac::DTL::Value object.
This is used by the Variable construct to cache filters and calling devar_var() and apply_filters() for increased performance.
This will return undef similar to devar_nodefault().
Similar as devar_var().
This will return $Dotiac::DTL::TEMPLATE_STRING_IF_INVALID if the result of devar_var() is undef.
http://www.djangoproject.com, Dotiac::DTL
If you find a bug, please report it.
Dotiac::DTL was built according to http://docs.djangoproject.com/en/dev/ref/templates/builtins/.
Marc-Sebastian Lucksch
perl@marc-s.de
To install Dotiac::DTL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dotiac::DTL
CPAN shell
perl -MCPAN -e shell install Dotiac::DTL
For more information on module installation, please visit the detailed CPAN module installation guide.