1#============================================================= -*-Perl-*-
2#
3# Template::Plugin::HTML
4#
5# DESCRIPTION
6#   Template Toolkit plugin providing useful functionality for generating
7#   HTML.
8#
9# AUTHOR
10#   Andy Wardley   <abw@wardley.org>
11#
12# COPYRIGHT
13#   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
14#
15#   This module is free software; you can redistribute it and/or
16#   modify it under the same terms as Perl itself.
17#
18#============================================================================
19
20package Template::Plugin::HTML;
21
22use strict;
23use warnings;
24use base 'Template::Plugin';
25
26our $VERSION = 2.62;
27
28sub new {
29    my ($class, $context, @args) = @_;
30    my $hash = ref $args[-1] eq 'HASH' ? pop @args : { };
31    bless {
32        _SORTED => $hash->{ sorted } || 0,
33    }, $class;
34}
35
36sub element {
37    my ($self, $name, $attr) = @_;
38    ($name, $attr) = %$name if ref $name eq 'HASH';
39    return '' unless defined $name and length $name;
40    $attr = $self->attributes($attr);
41    $attr = " $attr" if $attr;
42    return "<$name$attr>";
43}
44
45sub attributes {
46    my ($self, $hash) = @_;
47    return '' unless ref $hash eq 'HASH';
48
49    my @keys = keys %$hash;
50    @keys = sort @keys if $self->{ _SORTED };
51
52    join(' ', map {
53        "$_=\"" . $self->escape( $hash->{ $_ } ) . '"';
54    } @keys);
55}
56
57sub escape {
58    my ($self, $text) = @_;
59    for ($text) {
60        s/&/&amp;/g;
61        s/</&lt;/g;
62        s/>/&gt;/g;
63        s/"/&quot;/g;
64    }
65    $text;
66}
67
68sub url {
69    my ($self, $text) = @_;
70    return undef unless defined $text;
71    $text =~ s/([^a-zA-Z0-9_.-])/uc sprintf("%%%02x",ord($1))/eg;
72    return $text;
73}
74
75
761;
77
78__END__
79
80=head1 NAME
81
82Template::Plugin::HTML - Plugin to create HTML elements
83
84=head1 SYNOPSIS
85
86    [% USE HTML %]
87
88    [% HTML.escape("if (a < b && c > d) ..." %]
89
90    [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
91
92    [% HTML.attributes(border => 1, cellpadding => 2) %]
93
94=head1 DESCRIPTION
95
96The C<HTML> plugin is a very basic plugin, implementing a few useful
97methods for generating HTML.
98
99=head1 METHODS
100
101=head2 escape(text)
102
103Returns the source text with any HTML reserved characters such as
104C<E<lt>>, C<E<gt>>, etc., correctly esacped to their entity equivalents.
105
106=head2 attributes(hash)
107
108Returns the elements of the hash array passed by reference correctly
109formatted (e.g. values quoted and correctly escaped) as attributes for
110an HTML element.
111
112=head2 element(type, attributes)
113
114Generates an HTML element of the specified type and with the attributes
115provided as an optional hash array reference as the second argument or
116as named arguments.
117
118    [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
119    [% HTML.element('table', border=1, cellpadding=2) %]
120    [% HTML.element(table => attribs) %]
121
122=head1 DEBUGGING
123
124The HTML plugin accepts a C<sorted> option as a constructor argument
125which, when set to any true value, causes the attributes generated by
126the C<attributes()> method (either directly or via C<element()>) to be
127returned in sorted order.  Order of attributes isn't important in
128HTML, but this is provided mainly for the purposes of debugging where
129it is useful to have attributes generated in a deterministic order
130rather than whatever order the hash happened to feel like returning
131the keys in.
132
133    [% USE HTML(sorted=1) %]
134    [% HTML.element( foo => { charlie => 1, bravo => 2, alpha => 3 } ) %]
135
136generates:
137
138    <foo alpha="3" bravo="2" charlie="1">
139
140=head1 AUTHOR
141
142Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
143
144=head1 COPYRIGHT
145
146Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
147
148This module is free software; you can redistribute it and/or
149modify it under the same terms as Perl itself.
150
151=head1 SEE ALSO
152
153L<Template::Plugin>
154
155=cut
156
157# Local Variables:
158# mode: perl
159# perl-indent-level: 4
160# indent-tabs-mode: nil
161# End:
162#
163# vim: expandtab shiftwidth=4:
164