[Jifty-commit] r7484 - Template-Declare/trunk/lib/Template/Declare
Jifty commits
jifty-commit at lists.jifty.org
Mon Sep 7 01:09:10 EDT 2009
Author: theory
Date: Mon Sep 7 01:09:10 2009
New Revision: 7484
Modified:
Template-Declare/trunk/lib/Template/Declare/TagSet.pm
Log:
Cleaned up the documentation of Template::Declare::TagSet.
Modified: Template-Declare/trunk/lib/Template/Declare/TagSet.pm
==============================================================================
--- Template-Declare/trunk/lib/Template/Declare/TagSet.pm (original)
+++ Template-Declare/trunk/lib/Template/Declare/TagSet.pm Mon Sep 7 01:09:10 2009
@@ -26,7 +26,7 @@
=head1 NAME
-Template::Declare::TagSet - Base class for tag set classes used by Template::Declare::Tags
+Template::Declare::TagSet - Base class for tag sets used by Template::Declare::Tags
=head1 SYNOPSIS
@@ -35,15 +35,16 @@
# returns an array ref for the tag names
sub get_tag_list {
- [ qw/ html body tr td table
- base meta link hr
- / ]
+ [ qw(
+ html body tr td table
+ base meta link hr
+ )]
}
# prevents potential naming conflicts:
sub get_alternate_spelling {
my ($self, $tag) = @_;
- return 'row' if $tag eq 'tr';
+ return 'row' if $tag eq 'tr';
return 'cell' if $tag eq 'td';
}
@@ -51,59 +52,72 @@
# combined to "<tag />":
sub can_combine_empty_tags {
my ($self, $tag) = @_;
- $tag =~ /^ base | meta | link | hr $/x;
+ $tag =~ /^ (?: base | meta | link | hr ) $/x;
}
+=head1 DESCRIPTION
+
+Template::Declare::TagSet is the base class for declaring packages of
+Template::Delcare tags. If you need to create new tags for use in your
+temlates, this is the base class for you! Review the source code of
+L<Template::Declare::TagSet::HTML|Template::Declare::TagSet::HTML> for a
+useful example.
+
=head1 METHODS
-=over
+=head2 new( \%PARAMS )
-=item C<< $obj = Template::Declare::TagSet->new({ package => 'Foo::Bar', namespace => undef }); >>
+ my $tag_set = Template::Declare::TagSet->new({
+ package => 'Foo::Bar',
+ namespace => undef,
+ });
-Constructor created by C<Class::Accessor::Fast>,
-accepting an optional option list.
+Constructor created by C<Class::Accessor::Fast>, accepting an optional hash
+reference of parameters.
-=item C<< $list = $obj->get_tag_list() >>
+=head2 get_tag_list
-Returns an array ref for the tag names.
+ my $list = $tag_set->get_tag_list();
-=item C<< $bool = $obj->get_alternate_spelling($tag) >>
+Returns an array ref for the tag names offered by a tag set.
-Returns whether a tag has an alternative spelling. Basically
-it provides a way to work around naming conflicts, for
-examples, the C<tr> tag in HTML conflicts with the C<tr>
-operator in Perl and the C<template> tag in XUL conflicts
-with the C<template> sub exported by C<Template::Declare::Tags>.
+=head2 get_alternate_spelling( TAG )
-=item C<< $bool = $obj->can_combine_empty_tags($tag) >>
+ $bool = $obj->get_alternate_spelling($tag);
-Specifies whether "<tag></tag>" can be combined into a single
-token "<tag />".
+Returns true if a tag has an alternative spelling. Basically it provides a way
+to work around naming conflicts. For example, the C<tr> tag in HTML conflicts
+with Perl's C<tr> operator, and the C<template> tag in XUL conflicts with the
+C<template> sub exported by C<Template::Declare::Tags>.
-Always returns true (value 1) in this base class.
+=head2 can_combine_empty_tags( TAG )
-But there's some cases where you want to override the
-deafault implementation. For example,
-C<< Template::Declare::TagSet::HTML->can_combine_empty_tags('img') >> returns true (1) since C<< <img src="..." /> >> is always
-required for HTML pages.
+ $bool = $obj->can_combine_empty_tags($tag);
-=back
+Specifies whether C<< <tag></tag> >> can be combined into a single token, C<<
+<tag /> >>. By default, all tags can be combined into a single token; override
+in a subclass to change this value where appropriate. For example,
+C<< Template::Declare::TagSet::HTML->can_combine_empty_tags('img') >> returns
+true since C<< <img src="..." /> >> is always required for HTML pages.
+C<< Template::Declare::TagSet::HTML->can_combine_empty_tags('script') >>, on
+the other hand, returns false, since some browsers can't handle a single
+script token.
=head1 ACCESSORS
This class has two read-only accessors:
-=over
+=head2 package
+
+ my $package = $obj->package();
-=item C<< $obj->package() >>
+Retrieves the value of the C<package> option set via the constructor.
-Retrieves the value of the C<package> option set via
-the constructor.
+=head2 namespace
-=item C<< $obj->namespace() >>
+ my $namespace = $obj->namespace();
-Retrieves the value of the C<namespace> option set by
-the constructor.
+Retrieves the value of the C<namespace> option set via the constructor.
=back
More information about the Jifty-commit
mailing list