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;
24 PARSER => Template::Parser->new(
25 FACTORY => 'HTML::String::TT::Directive'
27 STASH => Template::Stash->new,
28 FILTERS => { no_escape => sub {
29 $_[0]->$_isa('HTML::String::Value')
30 ? HTML::String::Value->new(map $_->[0], @{$_[0]->{parts}})
31 : HTML::String::Value->new($_)
33 (ref($_[0]) eq 'HASH' ? %{$_[0]} : @_)
43 HTML::String::TT - HTML string auto-escaping for L<Template Toolkit|Template>
47 my $tt = HTML::String::TT->new(\%normal_tt_args);
49 or, if you're using L<Catalyst::View::TT>:
51 use HTML::String::TT; # needs to be loaded before TT to work
54 CLASS => 'HTML::String::TT',
57 Then, in your template -
60 [% title %] <-- this will be automatically escaped
63 [% some_html | no_escape %] <-- this won't
65 [% html_var = '<foo>'; html_var %] <-- this won't anyway
67 (but note that the C<content> key in wrappers shouldn't need this).
71 L<HTML::String::TT> is a wrapper for L<Template Toolkit|Template> that
72 installs the following overrides:
76 =item * The directive generator is replaced with
77 L<HTML::String::TT::Directive> which ensures L<HTML::String::Overload> is
78 active for the template text.
80 =item * The stash is forced to be L<Template::Stash> since
81 L<Template::Stash::XS> gets utterly confused if you hand it an object.
83 =item * A filter C<no_escape> is added to mark outside data that you don't
88 The override happens to B<all> of the plain strings in your template, so
89 even things declared within directives such as
91 [% html_var = '<h1>' %]
93 will not be escaped, but any string coming from anywhere else will be. This
94 can be a little bit annoying when you then pass it to things that don't
95 respond well to overloaded objects, but is essential to L<HTML::String>'s
96 policy of "always fail closed" - I'd rather it throws an exception than
97 lets a value through unescaped, and if you care about your HTML not having
98 XSS (cross site scripting) vulnerabilities then I hope you'll agree.
100 We mark a number of TT internals namespaces as "don't escape when called by
101 these", since TT has a tendency to do things like
105 which really don't work if it gets converted to C<" $name> while you
108 Additionally, since TT often calls C<ref> to decide e.g.
109 if something is a string or a glob, it's important that L<UNIVERSAL::ref>
110 is loaded before TT is. We check to see if the latter is loaded and the
111 former not, and warn loudly that you're probably going to get weird errors.
113 This warning is not joking. "Probably" is optimistic. Load this module first.
119 The C<no_escape> filter marks the filtered input to not be escaped,
120 so that you can provide HTML chunks from externally and still render them
125 See L<HTML::String> for authors.
127 =head1 COPYRIGHT AND LICENSE
129 See L<HTML::String> for the copyright and license.