1 package HTML::String::TT;
6 if ($INC{"Template.pm"} and !$INC{"UNIVERSAL/ref.pm"}) {
7 warn "Template was loaded before we could load UNIVERSAL::ref"
8 ." - this means you're probably going to get weird errors."
9 ." To avoid this, use HTML::String::TT before loading Template."
11 require UNIVERSAL::ref;
15 use HTML::String::TT::Directive;
22 my $orig_blessed = Template::Stash->can('blessed');
23 no warnings 'redefine';
24 *Template::Stash::blessed = sub ($) {
25 my $val = $orig_blessed->($_[0]);
26 return undef if defined($val) and $val eq 'HTML::String::Value';
34 PARSER => Template::Parser->new(
35 FACTORY => 'HTML::String::TT::Directive'
37 STASH => Template::Stash->new,
38 FILTERS => { no_escape => sub {
39 $_[0]->$_isa('HTML::String::Value')
40 ? HTML::String::Value->new(map $_->[0], @{$_[0]->{parts}})
41 : HTML::String::Value->new($_)
43 (ref($_[0]) eq 'HASH' ? %{$_[0]} : @_)
53 HTML::String::TT - HTML string auto-escaping for L<Template Toolkit|Template>
57 my $tt = HTML::String::TT->new(\%normal_tt_args);
59 or, if you're using L<Catalyst::View::TT>:
61 use HTML::String::TT; # needs to be loaded before TT to work
64 CLASS => 'HTML::String::TT',
67 Then, in your template -
70 [% title %] <-- this will be automatically escaped
73 [% some_html | no_escape %] <-- this won't
75 [% html_var = '<foo>'; html_var %] <-- this won't anyway
77 (but note that the C<content> key in wrappers shouldn't need this).
81 L<HTML::String::TT> is a wrapper for L<Template Toolkit|Template> that
82 installs the following overrides:
86 =item * The directive generator is replaced with
87 L<HTML::String::TT::Directive> which ensures L<HTML::String::Overload> is
88 active for the template text.
90 =item * The stash is forced to be L<Template::Stash> since
91 L<Template::Stash::XS> gets utterly confused if you hand it an object.
93 =item * A filter C<no_escape> is added to mark outside data that you don't
98 The override happens to B<all> of the plain strings in your template, so
99 even things declared within directives such as
101 [% html_var = '<h1>' %]
103 will not be escaped, but any string coming from anywhere else will be. This
104 can be a little bit annoying when you then pass it to things that don't
105 respond well to overloaded objects, but is essential to L<HTML::String>'s
106 policy of "always fail closed" - I'd rather it throws an exception than
107 lets a value through unescaped, and if you care about your HTML not having
108 XSS (cross site scripting) vulnerabilities then I hope you'll agree.
110 We mark a number of TT internals namespaces as "don't escape when called by
111 these", since TT has a tendency to do things like
115 which really don't work if it gets converted to C<" $name> while you
118 Additionally, since TT often calls C<ref> to decide e.g.
119 if something is a string or a glob, it's important that L<UNIVERSAL::ref>
120 is loaded before TT is. We check to see if the latter is loaded and the
121 former not, and warn loudly that you're probably going to get weird errors.
123 This warning is not joking. "Probably" is optimistic. Load this module first.
129 The C<no_escape> filter marks the filtered input to not be escaped,
130 so that you can provide HTML chunks from externally and still render them
135 See L<HTML::String> for authors.
137 =head1 COPYRIGHT AND LICENSE
139 See L<HTML::String> for the copyright and license.