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