Nonstandard Modules
-------------------
Class::ParamParser
SYNOPSIS
========
use HTML::TagMaker;
my $html = HTML::TagMaker->new();
$html->groups_by_default( 1 );
print
'Content-type: text/html'."\n\n",
$html->start_html(
-title => "This Is My Page",
-style => { -code => <<__endquote },
\nBODY {
background-color: #ffffff;
background-image: none;
}
__endquote
),
$html->h1( 'A Simple Example' ),
$html->p(
"Click " .
$html->a( href => 'http://search.cpan.org', text => 'here' ) .
" for more."
),
$html->hr,
$html->table(
$html->tr( [
$html->th( [ 'Name', 'Count', 'URL', 'First Access' ] ),
$html->td( [ 'Old Page', 33, 'http://www.domain.com',
'1999/04/23 13:55:02' ] )
] )
),
$html->hr,
$html->form_start( method => 'post', action => 'http://localhost' ),
$html->p(
"What's your name? " .
$html->input( type => 'text', name => 'name' )
),
$html->p(
"What's the combination?" .
$html->input_group(
-type => 'checkbox',
-name => 'words',
-value => ['eenie', 'meenie', 'minie', 'moe'],
-checked => [1, 0, 1, 0],
-text => ['eenie', 'meenie', 'minie', 'moe'] ),
),
$html->p(
"What's your favorite colour? " .
$html->select_start( -size => 1, -name => 'color' ) .
$html->option_group(
-value => ['red', 'green', 'blue', 'chartreuse'],
-text => ['Red', 'Green', 'Blue', 'Chartreuse'] ) .
$html->select_end
),
$html->input( type => 'submit' ),
$html->form_end,
$html->end_html;
DESCRIPTION
===========
This Perl 5 object class can be used to generate any HTML tags in a
format that is consistent with the W3C HTML 4.0 standard. There are no
restrictions on what tags are named, however; you can ask for any new or
unsupported tag that comes along from Netscape or Microsoft, and it will
be made. Additionally, you can generate lists of said tags with one
method call, or just parts of said tags (but not both at once).
In this implementation, "standard format" means that tags are made as
pairs (This Is My Page
A Simple Example
Click
here for more.
Name
Count
URL
First Access
Old Page
33
http://www.domain.com
1999/04/23 13:55:02
text
". This also means that if you mis-spell any method name, it
will still make a new tag with the mis-spelled name. For autoloaded
methods only, the method names are case-insensitive.
If you call a class method whose name ends in either of ['_start',
'_end', '_pair'], this will be interpreted as an instruction to make just
part of one tag whose name are the part of the method name preceeding that
suffix. For example, calling "p_start( 'text' )" results in "text"
rather than "
text
". Similarly, calling "p_end()" will generate a
"" only. Using the '_pair' suffix will force tags to be made as a
pair, whether or not they would do so naturally. For example, calling
"br_pair" would produce a "here we are " being generated. The arguments
that you call this method are exactly the same as for calling a method to
make a single tag of the same name, except that the extra optional
parameter "list" can be used to force an ARRAY ref of the new tags to be
returned instead of a scalar. The symantec difference is that any
arguments whose values are ARRAY refs are interpreted as a list of values
where each one is used in a separate tag; for a single tag, the literal
ARRAY ref itself would be used. The number of tags produced is equal to
the length of the longest ARRAY ref passed as an argument. For any other
arguments who have fewer than this count, their last value is replicated
and appended enough times as necessary to make them the same length. The
value of a scalar argument is used for all the tags. For example, calling
"input_group( type => checkbox, name => 'letters', value => ['a','b','c']
)" produces 'text ) or after "start tags" (text). The same result
can be had explicitely by passing the named parameter "text". Most static
(non-autoloaded) methods require positional parameters, except for
start_html(), which can take either format. The names of any named
parameters can optionally start with a "-".
FUNCTIONS AND METHODS
=====================
Note that all the methods defined below are static, so information
specific to autoloaded methods won't likely apply to them. All of these
methods take positional arguments unless otherwise specified.
new()
-----
This function creates a new HTML::TagMaker object (or subclass thereof)
and returns it.
initialize()
------------
This method is used by new() to set the initial properties of an object,
that it creates. All page attributes are wiped clean, resulting in an
empty page.
clone([ CLONE ])
----------------
This method initializes a new object to have all of the same properties
of the current object and returns it. This new object can be provided in
the optional argument CLONE (if CLONE is an object of the same class as
the current object); otherwise, a brand new object of the current class is
used. Only object properties recognized by HTML::TagMaker are set in the
clone; other properties are not changed.
groups_by_default([ VALUE ])
----------------------------
This method is an accessor for the boolean "automatic grouping"
property of this object, which it returns. If VALUE is defined, this
property is set to it. In cases where we aren't told explicitely that
autoloaded methods are making a single or multiple tags (using ['_start',
'_end', '_pair'] and '_group' respectively), we look to this property to
determine what operation we guess. The default is "single". When this
property is true, we can make both single and groups of tags by using a
suffix-less method name; however, making single tags this way is slower
than when this property is false. Also, be aware that when we are making
a "group", arguments that are ARRAY refs are always flattened, and when we
are making a "single", ARRAY ref arguments are always used literally.
positional_by_default([ VALUE ])
--------------------------------
This method is an accessor for the boolean "positional arguments"
property of this object, which it returns. If VALUE is defined, this
property is set to it. With methods whose parameters could be either
named or positional, when we aren't sure what we are given, do we guess
positional? Default is named.
prologue_tag()
--------------
This method returns a prologue tag, which is meant to be the very first
thing in an HTML document. It tells the web browser such things as what
version of the HTML standard we are adhering to, version 4.0 in this case.
The prologue tag we make looks like ''.
comment_tag( TEXT )
-------------------
This method returns a comment tag, which is only visible to people
viewing the HTML source of a document, and not otherwise. It can take
either a scalar or a list or an Array ref as its TEXT argument. If a
single item of text is passed, then a comment tag that looks like "" is made. If more than one item of text is passed, then a
multi-line comment is made, which has each item of text on its own line
and indented with a single tab. The latter is suitable for displaying CSS
or JavaScript code in an elegant manner.
make_html_tag( NAME[, PARAMS[, TEXT[, PART]]] )
-----------------------------------------------
This method is used internally to do the actual construction of single
html tags. You can call it directly when you want faster code and/or
more control over how tags are made. The first argument, NAME, is a
scalar that defines the actual name of the tag we are making (eg: 'br');
it is case-insensitive. The optional second argument, PARAMS, is a HASH
ref containing attribute names and values for the new tag; the names
(keys) are case-insensitive. The attribute values are all printed
literally, so they should be scalars. The optional third argument, TEXT,
is a scalar containing the text that goes between the tag pairs; it is not
a tag attribute. The optional fourth argument, PART, is a scalar which
indicates we should make just a certain part of the tag; acceptable values
are ['pair', 'start', 'end'], and it is case-insensitive. This method
knows which HTML tags are normally paired or not, which tag attributes
take specified values or not, and acts accordingly.
make_html_tag_group( NAME[, PARAMS[, TEXT[, LIST]]] )
-----------------------------------------------------
This method is used internally to do the actual construction of html
tag groups. You can call it directly when you want faster code and/or
more control over how tags are made. The first argument, NAME, is a
scalar that defines the actual name of the tag we are making (eg: 'br');
it is case-insensitive. The optional second argument, PARAMS, is a HASH
ref containing attribute names and values for the new tag; the names
(keys) are case-insensitive. Any attribute values which are ARRAY refs
are flattened, and the number of tags made is determined by the length of
the longest one. The optional third argument, TEXT, is a HASH ref (or
scalar) containing the text that goes between the tag pairs; it is not a
tag attribute, but if its an ARRAY ref then its length will influence the
number of tags that are made as the length of tag attribute arrays do.
The optional fourth argument, LIST, is a boolean/scalar which indicates
whether this method returns the new tags in an ARRAY ref (one tag per
element) or as a scalar (tags are concatenated together); a true value
forces an ARRAY ref, scalar is the default. This method knows which HTML
tags are normally paired or not, which tag attributes take specified
values or not, and acts accordingly.
start_html([ TITLE[, AUTHOR[, META[, STYLE[, HEAD[, BODY]]]]] ])
----------------------------------------------------------------
This method returns a canned HTML template that is suitable for use as
the top of an HTML page. It consists of the prologue tag (' tag is
made if AUTHOR is present. The third argument, META, is a HASH ref
containing name/value pairs of meta information, and a '