lib/HTML/String/TT.pm

   1 package HTML::String::TT;
   2
   3 use strictures 1;
   4
   5 BEGIN {
   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."
  10     }
  11     require UNIVERSAL::ref;
  12 }
  13
  14 use HTML::String;
  15 use HTML::String::TT::Directive;
  16 use Safe::Isa;
  17 use Template;
  18 use Template::Parser;
  19 use Template::Stash;
  20
  21 BEGIN {
  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';
  27     return $val;
  28   };
  29 }
  30
  31 sub new {
  32     shift;
  33     my @args = (ref($_[0]) eq 'HASH' ? %{$_[0]} : @_);
  34     Template->new(
  35         PARSER => Template::Parser->new(
  36             FACTORY => 'HTML::String::TT::Directive',
  37             @args,
  38         ),
  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($_)
  44         } },
  45         @args,
  46     );
  47 }
  48
  49 1;
  50
  51 __END__
  52
  53 =head1 NAME
  54
  55 HTML::String::TT - HTML string auto-escaping for L<Template Toolkit|Template>
  56
  57 =head1 SYNOPSIS
  58
  59   my $tt = HTML::String::TT->new(\%normal_tt_args);
  60
  61 or, if you're using L<Catalyst::View::TT>:
  62
  63   use HTML::String::TT; # needs to be loaded before TT to work
  64
  65   __PACKAGE__->config(
  66     CLASS => 'HTML::String::TT',
  67   );
  68
  69 Then, in your template -
  70
  71   <h1>
  72     [% title %] <-- this will be automatically escaped
  73   </h1>
  74   <div id="main">
  75     [% some_html | no_escape %] <-- this won't
  76   </div>
  77   [% html_var = '<foo>'; html_var %] <-- this won't anyway
  78
  79 (but note that the C<content> key in wrappers shouldn't need this).
  80
  81 =head1 DESCRIPTION
  82
  83 L<HTML::String::TT> is a wrapper for L<Template Toolkit|Template> that
  84 installs the following overrides:
  85
  86 =over 4
  87
  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.
  91
  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.
  94
  95 =item * A filter C<no_escape> is added to mark outside data that you don't
  96 want to be escaped.
  97
  98 =back
  99
 100 The override happens to B<all> of the plain strings in your template, so
 101 even things declared within directives such as
 102
 103   [% html_var = '<h1>' %]
 104
 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.
 111
 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
 114
 115   open FH, "< $name";
 116
 117 which really don't work if it gets converted to C<&quot; $name> while you
 118 aren't looking.
 119
 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.
 124
 125 This warning is not joking. "Probably" is optimistic. Load this module first.
 126
 127 =head1 FILTERS
 128
 129 =head2 no_escape
 130
 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
 133 within the TT code.
 134
 135 =head1 AUTHORS
 136
 137 See L<HTML::String> for authors.
 138
 139 =head1 COPYRIGHT AND LICENSE
 140
 141 See L<HTML::String> for the copyright and license.
 142
 143 =cut