Re: Template::Plugin::HTML

--- /usr/local/lib/perl/5.10.1/Template/Plugin/HTML.pm	2009-05-20 10:57:04.000000000 -0700
+++ /usr/local/share/perl/5.10.0/Template/Plugin/HTML.pm	2010-04-21 06:31:06.000000000 -0700
@@ -3,6 +3,7 @@
 # Template::Plugin::HTML
 #
 # DESCRIPTION
+#
 #   Template Toolkit plugin providing useful functionality for generating
 #   HTML.
 #
@@ -10,53 +11,123 @@
 #   Andy Wardley   <[email protected]>
 #
 # COPYRIGHT
-#   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
+#   Copyright (C) 1996-2006 Andy Wardley.  All Rights Reserved.
+#   Copyright (C) 1998-2001 Canon Research Centre Europe Ltd.
 #
 #   This module is free software; you can redistribute it and/or
 #   modify it under the same terms as Perl itself.
 #
+# REVISION
+#   $Id: HTML.pm 1055 2007-04-27 11:50:40Z abw $
+#
 #============================================================================
 
 package Template::Plugin::HTML;
 
 use strict;
 use warnings;
 use base 'Template::Plugin';
 
-our $VERSION = 2.62;
+our $VERSION = 2.63;
 
 sub new {
-    my ($class, $context, @args) = @_;
-    my $hash = ref $args[-1] eq 'HASH' ? pop @args : { };
-    bless {
-        _SORTED => $hash->{ sorted } || 0,
+    my ( $class, $context, @args ) = @_;
+    my $hash = ref $args[-1] eq 'HASH' ? pop @args : {};
+    return bless {
+        _SORTED => ( $hash->{sorted} || 0 ),
+        attributes => {},
     }, $class;
 }
 
+sub add_attributes {
+    my ( $self, $attr ) = @_;
+
+    return unless ref $attr eq 'HASH';
+
+    my $cur = $self->{attributes};
+
+    for ( keys %{$attr} ) {
+        $cur->{$_} = exists $cur->{$_}
+            ? $cur->{$_} . " $attr->{$_}"
+            : $attr->{$_};
+
+    }
+
+    return;
+}
+
+*add_attribute = \&add_attributes;
+*add           = \&add_attributes;
+
+sub replace_attributes {
+
+    my ( $self, $attr ) = @_;
+
+    return unless ref $attr eq 'HASH';
+
+    my $cur = $self->{attributes};
+
+    for ( keys %{$attr} ) {
+        $cur->{$_} = $attr->{$_};
+    }
+
+    return;
+}
+
+*replace_attribute = \&replace_attributes;
+*replace           = \&replace_attributes;
+
+sub clear_attributes {
+    my $self = shift;
+
+    $self->{attributes} = {};
+    return;
+}
+
+
 sub element {
-    my ($self, $name, $attr) = @_;
-    ($name, $attr) = %$name if ref $name eq 'HASH';
+    my ( $self, $name, $attr ) = @_;
+    ( $name, $attr ) = %$name if ref $name eq 'HASH';
     return '' unless defined $name and length $name;
-    $attr = $self->attributes($attr);
+    $attr = $self->attributes( $attr );
     $attr = " $attr" if $attr;
     return "<$name$attr>";
 }
 
+sub closed_element {
+    my ( $self, $name, $attr ) = @_;
+    ( $name, $attr ) = %$name if ref $name eq 'HASH';
+    return '' unless defined $name and length $name;
+    $attr = $self->attributes( $attr );
+    $attr = " $attr" if $attr;
+    return "<$name$attr />";
+}
+
 sub attributes {
-    my ($self, $hash) = @_;
-    return '' unless ref $hash eq 'HASH';
+    my ( $self, $hash ) = @_;
+    $hash ||= $self->{attributes};
 
     my @keys = keys %$hash;
-    @keys = sort @keys if $self->{ _SORTED };
 
-    join(' ', map { 
-        "$_=\"" . $self->escape( $hash->{ $_ } ) . '"';
-    } @keys);
+    return unless @keys;
+
+
+    @keys = sort @keys if $self->{_SORTED};
+
+    join( ' ', map {
+            "$_=\"" . $self->escape( $hash->{$_} ) . '"';
+    } @keys );
 }
 
 sub escape {
-    my ($self, $text) = @_;
-    for ($text) {
+    my ( $self, $text ) = @_;
+    for ( $text ) {
         s/&/&amp;/g;
         s/</&lt;/g;
         s/>/&gt;/g;
@@ -66,7 +137,7 @@
 }
 
 sub url {
-    my ($self, $text) = @_;
+    my ( $self, $text ) = @_;
     return undef unless defined $text;
     $text =~ s/([^a-zA-Z0-9_.-])/uc sprintf("%%%02x",ord($1))/eg;
     return $text;
@@ -77,6 +148,18 @@
 
 __END__
 
+
+#------------------------------------------------------------------------
+# IMPORTANT NOTE
+#   This documentation is generated automatically from source
+#   templates.  Any changes you make here may be lost.
+# 
+#   The 'docsrc' documentation source bundle is available for download
+#   from http://www.template-toolkit.org/docs.html and contains all
+#   the source templates, XML files, scripts, etc., from which the
+#   documentation for the Template Toolkit is built.
+#------------------------------------------------------------------------
+
 =head1 NAME
 
 Template::Plugin::HTML - Plugin to create HTML elements
@@ -84,24 +167,26 @@
 =head1 SYNOPSIS
 
     [% USE HTML %]
-    
+
     [% HTML.escape("if (a < b && c > d) ..." %]
-    
+
     [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
-    
+
     [% HTML.attributes(border => 1, cellpadding => 2) %]
 
 =head1 DESCRIPTION
 
-The C<HTML> plugin is a very basic plugin, implementing a few useful
-methods for generating HTML.  
+The HTML plugin is very new and very basic, implementing a few useful
+methods for generating HTML.  It is likely to be extended in the future
+or integrated with a larger project to generate HTML elements in a generic
+way (as discussed recently on the mod_perl mailing list).
 
 =head1 METHODS
 
 =head2 escape(text)
 
 Returns the source text with any HTML reserved characters such as 
-C<E<lt>>, C<E<gt>>, etc., correctly esacped to their entity equivalents.
+E<lt>, E<gt>, etc., correctly esacped to their entity equivalents.
 
 =head2 attributes(hash)
 
@@ -119,11 +204,45 @@
     [% HTML.element('table', border=1, cellpadding=2) %]
     [% HTML.element(table => attribs) %]
 
+=head2 add_attribute(attributes)
+
+This provides a way to incrementally add attributes to the object.
+The values passed in are stored in the object.  Calling
+L<element> with just a tag or L<attributes> without an parameters
+will used the saved attributes.
+
+    USE tag = HTML;
+    tag.add_attributes( { class => 'navbar' } );
+    tag.add_attributes( { id => 'foo' } );
+    tag.add_attributes( { class => 'active' } );
+
+    tag.element( 'li' ); # <li class="navbar active" id="foo">
+
+This method has two aliases: add_attribute() and add().
+
+=head2 replace_attribute(attributes)
+
+This will replace an attribute value instead of add to existing.
+
+
+    USE tag = HTML;
+    tag.add_attributes( { class => 'navbar' } );
+    tag.add_attributes( { id => 'foo' } );
+    tag.replace_attributes( { class => 'active' } );
+
+    tag.element( 'li' ); # <li class="active" id="foo">
+
+This method has two aliases: replace_attribute() and replace().
+
+=head2 clear_attributes
+
+Clears and saved attributes
+
 =head1 DEBUGGING
 
-The HTML plugin accepts a C<sorted> option as a constructor argument
+The HTML plugin accepts a 'sorted' option as a constructor argument
 which, when set to any true value, causes the attributes generated by
-the C<attributes()> method (either directly or via C<element()>) to be
+the attributes() method (either directly or via element()) to be
 returned in sorted order.  Order of attributes isn't important in
 HTML, but this is provided mainly for the purposes of debugging where
 it is useful to have attributes generated in a deterministic order
@@ -139,18 +258,29 @@
 
 =head1 AUTHOR
 
-Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/>
+Andy Wardley E<lt>[email protected]<gt>
+
+L<http://wardley.org/|http://wardley.org/>
+
+
+
+
+=head1 VERSION
+
+2.62, distributed as part of the
+Template Toolkit version 2.19, released on 27 April 2007.
 
 =head1 COPYRIGHT
 
-Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
+  Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
+
 
 This module is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself.
 
 =head1 SEE ALSO
 
-L<Template::Plugin>
+L<Template::Plugin|Template::Plugin>
 
 =cut