The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dotiac-addon-html_template-0.4
River stage zero No dependents
++
/ Dotiac::DTL::Addon::html_template_pure

NAME

Dotiac::DTL::Addon::html_template_pure - Render pure HTML::Template in Dotiac::DTL

SYNOPSIS

Load in Perl file for all templates:

        use Dotiac::DTL::Addon::html_template_pure;

Unload again:

        no Dotiac::DTL::Addon::html_template_pure;

Load from a Dotiac::DTL-template (only Dotiac::DTL 0.8 and up)

        {% load html_template_pure %}<TMPL_VAR NaME=Foo>....

You also might want make the whole thing case insensitive if the HTML::Template template's need it.

        use Dotiac::DTL::Addon::html_template_pure;
        use Dotiac::DTL::Addon::case_insensitive;

or in the template ( > Dotiac::DTL 0.8 ):

        {% load html_template_pure case_insensitive %}<TMPL_VAR NaME=Foo>....

INSTALLATION

via CPAN:

        perl -MCPAN -e "install Dotiac::DTL::Addon::html_template"

or get it from https://sourceforge.net/project/showfiles.php?group_id=249411&package_id=306751, extract it and then run in the extracted folder:

        perl Makefile.PL
        make test
        make install

DESCRIPTION

This makes Dotiac::DTL render templates written for HTML::Template. There are three ways to do this:

Dotiac::DTL::Addon::html_template_pure

This exchanges the parser of Dotiac::DTL with one that can read HTML::Template templates.

It can't render Django Templates anymore, so those will not work.

Dotiac::DTL::Addon::html_template

This also exchanges the parser, but with one that can read both Django and HTML::Template templates.

This way HTML::Template templates can import/extend Django templates and be imported/extended from them.

This means currently working HTML::Template templates can be extended with some Django/Dotiac tags and it will still work like expected

        <!-- Large web project -->
        ....
        <TMPL_IF time><div id="time">{# <TMPL_VAR time> Now Django #}{{ time|date:"Y-m-d H:M" }}</TMPL_IF>
        ....

But there will be a problem if the HTML::Template template contains not Django {{, {% or {# tags, but this is rarely the case.

Dotiac::DTL::Addon::html_template::Convert

This replaces HTML::Template and converts the templates before giving them to Dotiac::DTL. It can work with both pure and combined Django/HTML::Template templates.

So even here Django and HTML::Template tags can be mixed, and there is just one different line in the script

        # use HTML::Template # Not anymore
        use Dotiac::DTL::Addon::html_template::Convert qw/combine/ #Now using Dotiac

See Dotiac::DTL::Addon::html_template::Convert

Dotiac::DTL::Addon::html_template::Replace

Same as Convert, behaves like HTML::Template to the script, but uses Dotiac::DTL internally. Also supports mixed templates.

This is faster than Convert when using scalarrefs and such as template data.

Convert on the other hand is more stable with filenames, Replace might get confused when using different options on the same template.

See Dotiac::DTL::Addon::html_template::Replace

OPTIONS

Since Django has no concept of options to a template, there are a few HTML::Template options that can't be ignored:

filter

This won't work at all, the templates will need to have the filter applied beforehand. There are a lot of things that HTML::Template requires a filter for, but Django supports in a different way, for example: Includes from variables, n-sstage templating (Dotiac::DTL::Addon::unparsed).

associate

There is also no corresponding thing in Dotiac, but there is an easy solution that almost does the same thing (at least for CGI):

        #Perl
        my $template=Dotiac::DTL->new(...);
        $cgi=new CGI;
        $template->param(cgi=>$cgi->Vars);
        #And then in the template:
        Hello, <TMPL_VAR cgi.name>

It this won't work you need (because of existsing templates), do this:

        #Perl
        # $obj is the associate object.
        foreach my $p ($obj->param()) {
                $template->param($p,$obj->param($p));
        }
        # In the template:
        Hello, <TMPL_VAR name>

case_sensitive

This option defaults to off in HTML::Template, but in Django it defaults to on.

This is quite bad for most templates, so you can use the case_insensitive addon from CPAN for this. (It should already be installed when this module is installed):

In the perl script that calls it:

        use Dotiac::DTL::Addon::case_insensitive;

In the template (before any {% load html_template_pure %}) with Dotiac::DTL 0.8 and up:

        {% load case_insensitive %}

But remember, this makes Dotiac::DTL slower, so this should be avoided and all variables should be in the right case.

loop_context_vars

This one defaults to off in HTML::Template, but is set to on here, because it probably won't disrupt any templates.

It can be set to off if there are some problems:

        use Dotiac::DTL::Addon::html_template_pure loop_context_vars=>0;

global_vars

This one defaults to off in HTML::Template, but it is also set to on here, because it probably won't disrupt any templates.

It can be set to off if there are some problems:

        use Dotiac::DTL::Addon::html_template_pure global_vars=>0;

default_escape

This is set to off in HTML::Template (which is not that good), but set to HTML in Django. Therefore this parser has to fiddle about with it a lot.

        use Dotiac::DTL::Addon::html_template_pure default_escape=>"HTML";
        use Dotiac::DTL::Addon::html_template_pure default_escape=>"JS";
        use Dotiac::DTL::Addon::html_template_pure default_escape=>"URL";

Combine options

        use Dotiac::DTL::Addon::html_template_pure global_vars=>0, loop_context_vars=>0, default_escape=>"HTML";

Setting options during runtime:

Options are save in %Dotiac::DTL::Addon::html_template_pure::OPTIONS (no matter if you use Dotiac::DTL::Addon::html_template_pure or Dotiac::DTL::Addon::html_template).

Changes are only applied to the following new() calls or included templates during print().

        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{default_escape}="html"
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{default_escape}="js"
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{default_escape}="url"
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{default_escape}="" #off
        
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{global_var}=0
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{global_var}=1

        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{loop_context_vars}=1
        $Dotiac::DTL::Addon::html_template_pure::OPTIONS{loop_context_vars}=0

Note: Changing options for the same template might not work because of the caching routines.

It works fine for different templates.

Also note: Once a template is compiled, these options are ignored. In fact the whole module wouldn't be needed anymore. (Unless there is a {% load html_template(_pure) %} in there)

A NOTE ON COMBINED TEMPLATES

It is possible for Django tags close Html::Template tags and reverse, but it is not very pretty:

        <h1>My posts</h1>
        <TMPL_LOOP posts>
                <h2>
                {% if title %}
                        {{ title }}
                <!-- TMPL_ELSE -->
                        A post
                </TMPL_IF>
                </h2>
                {{ text|linebreaksbr}}
        {% endimportloop %}

But sometimes it might be useful to add an {% empty %} tag to an existing template:

        Updated on :
        <TMPL_LOOP updated>
                {{ time|date }}
        {% empty %}
                <b>Never</b>
        </TMPL_LOOP>

BUGS

Please report any bugs or feature requests to https://sourceforge.net/tracker2/?group_id=249411&atid=1126445

SEE ALSO

Dotiac::DTL, Dotiac::DTL::Addon, http://www.dotiac.com, http://www.djangoproject.com

AUTHOR

Marc-Sebastian Lucksch

perl@marc-s.de