The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Dotiac-addon-html_template-0.1
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

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