Class
Class
Mode
Enabled
| CleanCode Perl Libraries |
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| Multi-Lingual Library | Maintainability | ||||||||||||
|
Perl | |
Java | |
JavaScript | |
Certified Class |
|
Testable Class |
|
Standalone Mode |
|
Diagnostic Enabled |
HTML::Generator - Provides HTML formatting for output.
use HTML::Generator;
$gen = HTML::Generator->new();
print $gen->format("my title", $body, $headClauses);
print $gen->start("my title", $headClauses);
. . .
print $gen->end();
$section = $gen->section("section title", 3);
$cell = $gen->cell("abc");
$cell = $gen->toggleCell( "a", "evenCell", "oddCell" );
$row = $gen->row($cell1.$cell2.$cell3);
$row = $gen->toggleRow($twocells, "evenRow", "oddRow");
$table = $gen->table($row1.$row2.$row3.$row4);
$table = $gen->genTable(
[ ["col1","col2","col3"],
["1cell1","1cell2","1cell3"],
["2cell1","2cell2","2cell3"] ],
{ border=>4, cellspacing=>0 }
);
print $gen->anchor
( "display name", "javascript:gotoPage(5)", {onclick=>'stuff()'} );
print $gen->include("stylesheet", "styles/validate.css", "text/css");
print $gen->genTextSelect([ qw(one two three) ], "two", 0, "mySelect");
print $gen->genNumSelect(4, 2, "mySelect");
print $gen->genInputElement("password", 'myPwd', "", 10);
print $gen->option("display name", "key", 1);
print $gen->select($option1.$option2.$option3, "choices");
print $gen->line("a message here...");
print $gen->line("a message...", { "class"=>"stuff", style=>"border:1"} );
print $gen->styleLine("a message here...","someType");
print $gen->emphasis("a bold message here...");
print $gen->exception("WARNING: ". $myWarnMsg);
print $gen->exception("ERROR--some error...");
print $gen->generic("span", $text, \%attrs);
print $gen->genericNL("p", $text, \%attrs);
if ($gen->isFormatted($stuff)) { ... }
Perl5.005, Data::Handy
This module provides output formatted for web browsers using HTML. It is akin to the functions in the CGI package with these differences:
-- Provides just HTML formatting methods, while the CGI package serves multiple purposes.
-- Provides format-neutral method names, rather than method names which match specific HTML tags, making it more flexible. For example, instead of having an img method for the HTML img tag, HTML::Generator has an include method which includes not only images, but script files and style sheets.
-- Does not require STDIN input as the CGI package does, which makes this well-suited for non-CGI applications. That is, the CGI package, if used on the command-line will always stop and ask the user for inputs if they are not provided with the command invocation. This is not always desirable.
The remainder of this commentary describes the formatting methods, grouped by function. Note: For brevity in the examples below, each method is shown as just method() instead of object->method().
A basic document frame consists of start, followed by other routines, then end. For HTML, this generates
<!DOCTYPE...><HTML><HEAD>...</HEAD><BODY>...</BODY></HTML>By default the HTML 4.0 transitional doctype is used. (See also the subclass HTML::XGenerator which uses an XHMTL 1.0 doctype.) Alternately, the format method provides exactly the same utility with one call, when all of the data is available at one time.
The section method, on the other hand, is just a convenience method for specifying a major or minor header (e.g. H1, H2, etc.).
The genTable method is the preferred construction method. It provides complete separation between content and layout (almost--see below). The remaining methods provide lower level access, if needed.
A basic table could be constructed with:
table( row(cell().cell()...) . row(cell().cell()...) ... );
To produce a table with alternating style columns use toggleCell rather than cell, as in:
toggleCell("xyz", "evenCell", "oddCell")The second and third parameters are CSS style names from your stylesheet. Similarly, to produce a table with alternating style rows use toggleRow rather than row, as in:
toggleRow($someCells, "evenRow", "oddRow")A standard hyperlink is created with the anchor method. When selected on a web page this will navigate to the target of the link.
These kinds of files are supported by the include method:
links support code (JavaScript, PerlScript, etc.)
links cascading style sheets
links graphic files (typically .gif, .jpg, etc.)
The genTextSelect and genNumSelect are the preferred methods for creating a selection element. The select and option methods are available, though, and are used in concert to create a form selection element.
For genTextSelect, provide a list reference of strings to enumerate. The return value may be either the string itself, or a 0-based index, depending on the returnIndex flag. The initially selected item is specified as the selectedItem.
For genNumSelect, the selection element consists of sequential numbers, starting with 0, up to the specified limit. The initially selected item is specified as the selectedItem.
The line method simply outputs a line as a paragraph. The variant styleLine also outputs a line, but allows specifying a style as well as differing attributes. The emphasis method applies italics to its argument. The exception method displays its argument with a predefined prefix (***) in bold and with a CSS style of either errMsg or warnMsg (depending on whether the message contains the phrase ERROR or not).
For tags which are not specifically coded, use the generic and genericNL methods. Examples:
generic("xyz", "data") => <xyz>data</xyz>
generic("abc", "data") => <abc>data
genericNL("xyz", "data") => <xyz>
data
</xyz>As shown, an ending bracket may or may not appear; this is controlled by inclusion in the list of singleton tags. The genericNL method performs the same, but adds a couple newlines for HTML source formatting.
The isFormatted method indicates whether a message already has formatting by this formatter.
Current version of this class.
PACKAGE->new()
Creates an HTML::Generator object which can be used to generate HTML output.
a newly created object
OBJ->isFormatted(msg)
Returns a boolean indicating whether the msg is already formatted by this formatter class. This determination is made just by checking whether the first character is a less-than (<) symbol. Probably should enhance this to look for <x>...</x> | <x...>.
msg - string
boolean indicating whether already formatted
OBJ->generic(tag, s, attributes)
For tags which are not specifically provided for by other methods of this class, use the generic and genericNL methods. Returns <tag>s or <tag>s</tag> controlled by inclusion in the list of singleton tags.
tag - string; an arbitrary HTML tag
s - string to display between the <tag>...</tag> brackets.
attributes - optional; hash reference; attributes of the tag; each is inserted in the <tag> brackets as <tag attr="val">
<tag>s or <tag>s</tag>
OBJ->genericNL(tag, s, attributes)
For tags which are not specifically provided for by other methods of this class, use the generic and genericNL methods. Returns <tag>\ns\n or <tag>\ns</tag>\n controlled by inclusion in the list of singleton tags.
tag - string; an arbitrary HTML tag
s - string to display between the <tag>...</tag> brackets.
attributes - optional; hash reference; attributes of the tag; each is inserted in the <tag> element as <tag attr:"val">
<tag>s or <tag>s</tag>
OBJ->include(kind, file, filetype, attributes)
Creates a LINK, SCRIPT, or IMAGE element depending on the parameters.
kind - string; either stylesheet, script, or image
file - string; file name to insert in the appropriate attribute for the tag
filetype - string; file type to insert in the appropriate attribute for the tag; not used for image kind
attributes - optional; hash reference; additional attributes of the tag
a LINK, SCRIPT, or IMAGE element
OBJ->format(title, body, headClauses)
Creates a complete, valid html text from the DOCTYPE through the </html> tag.
title - string; inserted in a title element in the head element and an h1 element in the body element
body - string; inserted in the body element after the h1 element
headClauses - string; inserted in the head element after the title element
valid HTML text
OBJ->start(title, headClauses)
Creates an initial portion of html text including: DOCTYPE, HEAD element, opening BODY tag, and h1 element containing the title. Use in conjunction with the end method which concludes the BODY tag and the HTML tag.
title - string; inserted in a title element in the head element and an h1 element in the body element
headClauses - optional; string; inserted in the head element after the title element
docType - optional; string; document-type-definition; if none supplied 4.0 transitional is assumed.
initial portion of valid HTML text
OBJ->end()
Creates a final portion of html text including: closing BODY tag and closing HTML tag.
final portion of valid HTML text
OBJ->section(s, level)
Creates a heading element containing the specified string for the given level. Level should be between 1 and 6 inclusive, to generate H1 through H6 elements.
s - string; display text
level - integer; ...
a heading element H1 through H6
OBJ->line(s, attributes)
Creates one or more paragraphs. If multiple arguments are provided, each is put into a separate paragraph.
s - string; display text
attributes - optional; hash reference; attribute list for element
a P element
OBJ->styleLine(s, style, attributes)
Creates a paragraph with the specified CSS style and other attributes.
s - string; display text
style - string; CSS stylesheet selector name
attributes - optional; hash reference; attribute list for element
a P element containing a class plus other attributes
OBJ->exception(s)
Creates a DIV element for errors and warnings. The string s should contain the literal phrase WARNING or ERROR; these will give the div element the class warnMsg or errMsg, respectively. The string s is then output in bold, with a leading "*** ".
s - string; display text
a DIV element for an exception
OBJ->emphasis(s)
Creates an italic I element.
s - string; display text
an I element
OBJ->genTable(list, tableAttrs, rowOptions, cellOptions, cellFmt, tableName)
Creates a table from a list of data and a series of attributes and options, providing complete separation of data and structure. The list parameter specifies the data; the remaining ones affect the layout.
For the list parameter, each list element defines a row. Each row is again a list of cells in the row. Each cell is simply a string, the contents of the cell to be formatted and displayed.
The tableAttrs is an attribute list applied to the table element itself.
rowOptions and cellOptions are attribute lists which further refine the table layout. Each may contain these properties:
| Property | Description |
|---|---|
| toggle | if true, indicates to use alternating color rows or cells with default CSS styles of evenRow and oddRow |
| evenStyle | overrides the default evenRow CSS style for alternating rows |
| oddStyle | overrides the default oddRow CSS style for alternating rows |
| attributes | provide global attributes applied to every row or cell element |
Local attributes may further be applied to any cell, overriding the global attributes described above. This is the one case, however, which comingles data and layout. To use local attributes, simply insert an attribute list in the list of cell data as if it were a "zero-width" cell. Insert the attribute list just before the cell to receive the local attributes. The local attributes will remain in effect until the end of the row, or until explicitly changed or turned off by another local attribute list.
list - an array reference of array references of strings
tableAttrs - optional; a hash reference of attributes applied to the table element
rowOptions - optional; a hash reference of attributes from the table above
cellOptions - optional; a hash reference of attributes from the table above
cellFmt - optional; a formatter object providing a format method; if present, the contents of the cell is processed with this.
tableName - optional; string; display name for table; this will appear as the first row, spanning the width of the table.
a TABLE element
OBJ->table(s, attributes)
Creates a TABLE element with the specified string as its contents.
s - string; display text
attributes - optional; hash reference; attribute list for element
a TABLE element
OBJ->toggleRow(s, evenStyle, oddStyle, attributes)
Creates a TR element using alternating style names to achieve an alternating row effect.
s - string; display text
evenStyle - string; name of CSS style for even rows
oddStyle - string; name of CSS style for odd rows
attributes - optional; hash reference; attribute list for element
a TR element
OBJ->row(s, attributes)
Creates a TR element with the specified attributes.
s - string; display text
attributes - optional; hash reference; attribute list for element
a TR element
OBJ->toggleCell(s, evenStyle, oddStyle, attributes)
Creates a TD element using alternating style names to achieve an alternating column effect.
s - string; display text
evenStyle - string; name of CSS style for even columns
oddStyle - string; name of CSS style for odd columns
attributes - optional; hash reference; attribute list for element
a TD element
OBJ->cell(s, attributes)
Creates a TD element with the specified attributes.
s - string; display text
attributes - optional; hash reference; attribute list for element
a TD element
OBJ->anchor(s, target, attributes)
Creates an A element with the specified link target and attributes. Alternately, creates a named anchor for linking to; add an attribute called name to the attributes list and omit the target.
s - string; display text
target - optional; string; link target URL
attributes - optional; hash reference; attribute list for element
an A element
OBJ->option(s, val, selected)
Creates an OPTION element; if selected is true, sets it as selected.
s - string; display text
val - string; value to return if the option is chosen
selected - optional; boolean; whether to mark this one as initially selected
an OPTION element
OBJ->select(s, name, attributes)
Creates a SELECT element containing a series of OPTION element in s.
s - string; display text
name - string; name of DOM element
attributes - optional; hash reference; attribute list for element
a SELECT element
OBJ->genTextSelect(list, selectedItem, returnIndex, name, attributes)
Creates a SELECT element containing an OPTION element for each string in the supplied list.
list - array reference of strings
selectedItem - string; item to mark as selected by default
returnIndex - boolean; sets value of each OPTION element to an integer index if true; otherwise, sets value to the display string
name - string; name of DOM element
attributes - optional; hash reference; attribute list for element
a SELECT element
OBJ->genNumSelect(limit, selectedItem, name, attributes)
Creates a SELECT element containing an OPTION element for each integer from 0 to the specified limit.
limit - integer; upper bound of option list (lower bound is 0)
selectedItem - integer; item to mark as selected by default
name - string; name of DOM element
attributes - optional; hash reference; attribute list for element
a SELECT element
OBJ->genInputElement("text", name, value, maxlength, size)
OBJ->genInputElement("text", name, value, maxlength)
OBJ->genInputElement("password", name, value, maxlength, size)
OBJ->genInputElement("password", name, value, maxlength)
OBJ->genInputElement("radio", name, value, checked)
OBJ->genInputElement("radio", name, value)
OBJ->genInputElement("checkBox", name, value, checked)
OBJ->genInputElement("checkBox", name, value)
OBJ->genInputElement("button", name, value)
OBJ->genInputElement("textarea", name, value, rows, cols)
Creates an INPUT element for a form.
name - string; name of input element
value - string; initial value of element
maxlength - string; maximum number of characters which may be entered in field
size - optional; string; size of the displayed field (in characters); if omitted, maxlength is used
checked - optional; boolean; indicates whether input element is initially selected
rows - integer; number of rows to display for element
cols - integer; number of columns to display for element
an INPUT element
--Add indenting capability.
--Add configurable doctype.
None
Michael Sorens
$Revision: 278 $ $Date: 2008-05-26 22:44:56 -0700 (Mon, 26 May 2008) $
CleanCode 0.9
Hey! The above document had some coding errors, which are explained below:
=back doesn't take any parameters, but you said =back -- end of CLASS VARIABLES section
=back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR section
=back doesn't take any parameters, but you said =back -- end of METHODS section
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| CleanCode Perl Libraries | Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 |