local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Plugin/HTML.pm

   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
  20 package Template::Plugin::HTML;
  21
  22 use strict;
  23 use warnings;
  24 use base 'Template::Plugin';
  25
  26 our $VERSION = 2.62;
  27
  28 sub 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
  36 sub 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
  45 sub 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
  57 sub 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
  68 sub 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
  76 1;
  77
  78 __END__
  79
  80 =head1 NAME
  81
  82 Template::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
  96 The C<HTML> plugin is a very basic plugin, implementing a few useful
  97 methods for generating HTML.
  98
  99 =head1 METHODS
 100
 101 =head2 escape(text)
 102
 103 Returns the source text with any HTML reserved characters such as
 104 C<E<lt>>, C<E<gt>>, etc., correctly esacped to their entity equivalents.
 105
 106 =head2 attributes(hash)
 107
 108 Returns the elements of the hash array passed by reference correctly
 109 formatted (e.g. values quoted and correctly escaped) as attributes for
 110 an HTML element.
 111
 112 =head2 element(type, attributes)
 113
 114 Generates an HTML element of the specified type and with the attributes
 115 provided as an optional hash array reference as the second argument or
 116 as 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
 124 The HTML plugin accepts a C<sorted> option as a constructor argument
 125 which, when set to any true value, causes the attributes generated by
 126 the C<attributes()> method (either directly or via C<element()>) to be
 127 returned in sorted order.  Order of attributes isn't important in
 128 HTML, but this is provided mainly for the purposes of debugging where
 129 it is useful to have attributes generated in a deterministic order
 130 rather than whatever order the hash happened to feel like returning
 131 the keys in.
 132
 133     [% USE HTML(sorted=1) %]
 134     [% HTML.element( foo => { charlie => 1, bravo => 2, alpha => 3 } ) %]
 135
 136 generates:
 137
 138     <foo alpha="3" bravo="2" charlie="1">
 139
 140 =head1 AUTHOR
 141
 142 Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
 143
 144 =head1 COPYRIGHT
 145
 146 Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
 147
 148 This module is free software; you can redistribute it and/or
 149 modify it under the same terms as Perl itself.
 150
 151 =head1 SEE ALSO
 152
 153 L<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: