NAME

HTML::EasyTags - Make proper HTML 4 tags/lists/parts

DEPENDENCIES

Perl Version

5.004

Standard Modules

I<none>

Nonstandard Modules

Class::ParamParser 1.01

SYNOPSIS

use HTML::EasyTags;

my $html = HTML::EasyTags->new();
$html->groups_by_default( 1 );	

print
	$html->prologue_tag,
	$html->html_start,
	$html->head_start,
	$html->title( 'This Is My Page' ),
	$html->style( $html->comment_tag( <<__endquote ) ),
\nBODY {
	background-color: #ffffff; 
	background-image: none;
}
__endquote
	$html->head_end,
	$html->body_start,
	$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->body_end,
	$html->html_end;

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).

This module's purpose is to be lightweight, easy to use, and whose results are syntactically correct and nicely formatted (should humans wish to read or debug it). At the same time, it is supportive of your existing knowledge of HTML and as such its interface closely mirrors the actual appearance of the resulting tags. This means that methods have the same name as the actual tags, and named parameters that you pass correspond directly to the tag attributes produced. This module saves you having to remember the little details on formatting. For your convenience, a majority of the methods and their arguments are backwards-compatible with those in CGI.pm, but you are saved 200K of code size.

As a reference, I strongly recommend that you check out Kevin Werbach's excellent "The Bare Bones Guide to HTML", which is available at http://werbach.com/barebones/. I found this document invaluable when making this module, as it provides a comprehensive list of all the HTML tags along with their formatting and extensions.

In this implementation, "standard format" means that tags are made as pairs (<TAG></TAG>) by default, unless they are known to be "no pair" tags. Tags that I know to be "no pair" are [basefont, img, area, param, br, hr, input, option, tbody, frame, comment, isindex, base, link, meta]. However, you can force any tag to be "pair" or "start only" or "end only" by appropriately modifying your call to the tag making method.

Also, "standard format" means that tag modifiers are formatted as "key=value" by default, unless they are known to be "no value" modifiers. Modifiers that I know to be "no value" are [ismap, noshade, compact, checked, multiple, selected, nowrap, noresize, param]. These are formatted simply as "key" because their very presence indicates positive assertion, while their absense means otherwise. For modifiers with values, the values will always become bounded by quotes, which ensures they work with both string and numerical quantities (eg: key="value").

Note that this class is a subclass of Class::ParamParser, and inherits all of its methods, "params_to_hash()" and "params_to_array()".

HTML CODE FROM SYNOPSIS PROGRAM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<HTML>
<HEAD>
<TITLE>This Is My Page</TITLE>
<STYLE>
<!-- 
BODY {
	background-color: #ffffff; 
	background-image: none;
}
 --></STYLE>
</HEAD>
<BODY>
<H1>A Simple Example</H1>
<P>Click 
<A HREF="http://search.cpan.org">here</A> for more.</P>
<HR>
<TABLE>
<TR>
<TH>Name</TH>
<TH>Count</TH>
<TH>URL</TH>
<TH>First Access</TH></TR>
<TR>
<TD>Old Page</TD>
<TD>33</TD>
<TD>http://www.domain.com</TD>
<TD>1999/04/23 13:55:02</TD></TR></TABLE>
<HR>
<FORM METHOD="post" ACTION="http://localhost">
<P>What's your name? 
<INPUT TYPE="text" NAME="name"></P>
<P>What's the combination?
<INPUT TYPE="checkbox" NAME="words" CHECKED VALUE="eenie">Eenie
<INPUT TYPE="checkbox" NAME="words" VALUE="meenie">Meenie
<INPUT TYPE="checkbox" NAME="words" CHECKED VALUE="minie">Minie
<INPUT TYPE="checkbox" NAME="words" VALUE="moe">Moe</P>
<P>What's your favorite colour? 
<SELECT NAME="color" SIZE="1">
<OPTION VALUE="red">Red
<OPTION VALUE="green">Green
<OPTION VALUE="blue">Blue
<OPTION VALUE="chartreuse">Chartreuse
</SELECT></P>
<INPUT TYPE="submit">
</FORM>
</BODY>
</HTML>

SYNTAX

This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().

Methods of this class always "return" their results, rather than printing them out to a file or the screen. Not only is this simpler, but it gives the calling code the maximum amount of control over what happens in the program. They may wish to do post-processing with the generated HTML, or want to output it in a different order than it is generated. By default, all results are returned as a scalar, but methods which generate a list of tags can optionally return an ARRAY ref, with each element containing a single tag. This can aid in post-processing and possibly speed up the program because there is less copying done.

Through the magic of autoloading, this class can make any html tag by calling a class method with the same name as the tag you want. For examples, use "hr()" to make a "<HR>" tag, or "p('text')" to make "<P>text</P>". 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 "<P>text" rather than "<P>text</P>". Similarly, calling "p_end()" will generate a "</P>" 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 "<BR></BR>" rather than the normal "<BR>". When using either of ['_start','_pair'], the arguments you pass the method are exactly the same as the unmodified method would use, and there are no other symantec differences. However, when using the '_end' suffix, any arguments are ignored, as the latter member of a tag pair never carries any attributes anyway.

If you call a class method whose name ends in "_group", this will be interpreted as an instruction to make a list of tags whose name are the part of the method name preceeding the "_group". For example, calling "td_group( ['here','we','are'] )" results in "<TD>here</TD><TD>we</TD><TD>are</TD>" 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 '<INPUT TYPE="checkbox" NAME="letters" VALUE="a"><INPUT TYPE="checkbox" NAME="letters" VALUE="b"><INPUT TYPE="checkbox" NAME="letters" VALUE="c">'.

All autoloaded methods require their parameters to be in named format. These names and values correspond to attribute names and values for the new tags. Since "no value" attributes are essentially booleans, they can have any true or false value associated with them in the parameter list, which won't be printed. If an autoloaded method is passed exactly one parameter, it will be interpreted as the "text" that goes between the tag pair (<TAG>text</TAG>) or after "start tags" (<TAG>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::EasyTags 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::EasyTags 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 '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">'.

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 "<!-- text -->" 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.

COMPARISONS WITH CGI.PM

The methods of this class and their parameters are designed to be compatible with any same-named methods in the popular CGI.pm class. This class will produce browser-compatible (and often identical) HTML from such methods, and this class can accept all the same argument formats. Exceptions to this include:

0

None of our methods are exported and must be called using object notation, whereas CGI.pm can export any of it's methods.

0

Autoloaded methods do not use the presence or absence of arguments to decide whether to make the new tag as a pair or as "start only". Also, CGI.pm does not do end-only tags.

0

Autoloaded methods that make html tags won't concatenate their arguments into a single argument under any circumstances, but in some cases the "shortcuts" of CGI.pm will do so.

0

Currently we don't html-escape any argument values passed to our tag making functions, whereas CGI.pm sometimes does. While we expect our caller to do the escaping themselves where necessary, perhaps using a CPAN module especially designed for HTML escaping, we may do it later in an update.

0

We go further to make the generated HTML human-readable by: 1. having each new tag start on a new line; 2. making all tag and attribute names uppercase; 3. ensuring that about 20 often-used tag attributes always appear in the same order (eg: 'type' is before 'name' is before 'value'), and before any others.

AUTHOR

Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications.

I am always interested in knowing how my work helps others, so if you put this module to use in any of your own code then please send me the URL. Also, if you make modifications to the module because it doesn't work the way you need, please send me a copy so that I can roll desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

CREDITS

Thanks very much to Kevin Werbach for publishing "The Bare Bones Guide to HTML", which I found to be an invaluable resource when writing this module (and at other times as well). The latest version of the document is available at http://werbach.com/barebones/.

This quick reference lists all the HTML tags that current browsers are likely to recognize, including all the elements of the official HTML 4.0 recommendation, and some Netscape and Microsoft extensions as well. Common attributes for these tags are also included in context, giving a good idea on how they are used.

When writing this module, I used the Bare Bones reference to verify the consistant formatting used by all HTML tags, including how tag attributes are formatted. I could see the proper formatting for prologue and comment tags as well; their formats are unique compared to all the other tags. The other main uses I had for the document was in determining all the HTML tags which were not used as a pair (most use pairs, few don't), and for determining which tag attributes made a positive assertion just by their presence, without need for any associated values (most have values, few don't).

Thanks to Lincoln D. Stein for setting a good interface standard in the HTML-related methods of his CGI.pm module. I was heavily influenced by his interfaces when designing my own. Thanks also because I borrowed ideas for my Synopsis program from his aforementioned module.

SEE ALSO

perl(1), Class::ParamParser, CGI.

cpanm HTML::EasyTags

perl -MCPAN -e shell
install HTML::EasyTags