HTML::Markup::HTML2 - HTML Construction Module
require HTML::Markup::HTML2;
$html = Create HTML::Markup::HTML2;
$table = Create HTML::Markup::HTML2 'TABLE';
$table->attr('value'); # <TABLE ATTR=``value''>
This module implements an object-oriented HTML construction language.
The HTML structure is built up by creating and linking together objects that represent various HTML elements. The structure can then be modified by manipulating the contents of the objects. You can then ask the object hierarchy to render itself as HTML.
Object structures need not be complete HTML documents, they can be HTML fragments which you can then render alone or link into more complex HTML structures. This allows you to write modules that build HTML fragments which can then be linked together and dynamically modified as required (e.g., you could write a calendar object that represents the days of the month in a table with functions to add, modify, or delete entries from the calendar; this object could then be linked into your document).
For simple documents it is easier and faster to simply output the HTML directly but for complex and dynamic structures the object-oriented approach is a win.
HTML::Markup::HTML2 inherits from HTML::Markup::Element (which in turn inherits from DataType::Linkable) and is used to represent the HTML2 specific elements (e.g., HTML, HEAD, BODY).
HTML::Markup::HTML2 has methods for building a recursive tree of elements and associating attributes with them.
There are also four special classes that are used:
HTML::Markup::Text -- text w/HTML markup encoded for you
HTML::Markup::Literal -- text wo/any encoding
HTML::Markup::Eval -- Content is eval'ed at realize() time
HTML::Markup::Comment -- SGML Comments <!-- ... -->
These inherit from DataType::Linkable although their content is not an object heirarchy.
DataType::Linkable is a generic Linkable class that is used to maintain the tree structure of the object hierarchy.
Comment Eval Literal Text
These methods create the associated HTML::Markup::Comment, HTML::Markup::Eval HTML::Markup::Literal, and HTML::Markup::Text objects and automatically link into the creating object. For example:
$html = Create HTML::Markup::HTML2;
$head = $html->HEAD;
$title = $head->TITLE;
$title->Text('This title is contained in an HTML::Markup::Text object');
Elements are indicated by calling a method with all uppercase letters.
The following elements are automatically minimized:
AREA BASE BASEFONT BGSOUND BR HR IMG INPUT ISINDEX LINK META NEXTID
RANGE ROOT SPOT TAB TABSTOP WBR
The programmer can request an element to be minimized by calling the minimize method on the object:
$obj->minimized;
Some perl reserved words cannot be created this way (e.g., DESTROY AUTOLOAD) so you must use the Create method to manually create them:
$parent->append(Create HTML::Markup::HTML2 'AUTOLOAD');
Elements created with a method can also link the new object into a user supplied hash table. This is useful for storing objects by name in a local hash table for later use. For example:
my $objs = { };
$html = Create HTML::Markup::HTML2;
$head = $html->HEAD($objs, 'head');
$title = $head->TITLE($objs, 'title');
$objs->{'title'}->Text('link some text into the title object');
Methods will all lowercase letters are treated as attributes.
$link = Create HTML::Markup::HTML2 'A';
$link->href('http://www.bsdi.com/');
The following list is words used in object manipulation so you cannot use them as attributes, to add attributes by these names you must use use the <KBD>attribute</KBD> function:
after all_children append attribute attributes before child children delete delete_all element empty first i_th last minimized next offleft offright position prefix previous realize replace string_attributes swapleft swapright
Inherits from DataType::Linkable.
If $rendering is present this method sets the rendering of
this element and returns the old rendering value:
$oldrendering = $object->element('MYTAG');
With no arguments it simply returns the current rendering:
$rendering = $object->element;
This can be set at Create time, for example:
$object = Create HTML::Markup::HTML2 'MYTAG';
or
$object = $other_object->TABLE('MYTABLE');
Returns an array REF of attributes set for the current object:
$attributes = $object->attributes;
@$attributes;
Sets $attributes to @value.
@value is joined with spaces and must be valid inside
single-quotes for an SGML attribute (<TAG ATTR=``value''>). Basically
the same as:
$element->attrname(@value);
Sets the element to be minimized (rendered with no SGML end-tag).
Render the object hierarchy as HTML and returns the resulting string.
$html_string = $object->realize;
Inherits from DataType::Linkable. Contents are escaped according to the HTML rules for &, <, and > (&, <, >).
Allows you to insert HTML entities into a HTML::Markup::Text object:
$object = Create HTML::Markup::Text;
$object->entity('&');
HTML::Markup::Text also inherits methods for all the entities defined in HTML::Markup::Entities so you can say:
$text_object->amp;
Render the object hierarchy as HTML and returns the resulting string.
$html_string = $object->realize;
Inherits from DataType::Linkable. Contents are not escaped.
Allows you to insert HTML entities into a HTML::Markup::Literal object:
$object = Create HTML::Markup::Literal;
$object->entity('&');
HTML::Markup::Literal inherits the HTML::Markup::Entities methods.
Render the object hierarchy as HTML and returns the resulting string.
$html_string = $object->realize;
Inherits from DataType::Linkable. Contents are eval'ed when the structure is realize'ed and the results returned. The caller is responsible for setting the correct package.
Render the object hierarchy as HTML and returns the resulting string.
$html_string = $object->realize;
Inherits from DataType::Linkable.
Render the object hierarchy as HTML and returns the resulting string.
$html_string = $object->realize;
Code example:
#!/usr/bin/perl5
require HTML::Markup::HTML2;
$html = Create HTML::Markup::HTML2;
$html->HEAD->TITLE->Text("Title String");
# The shortcut above is the same as saying:
# $head = $html->HEAD;
# $title = $head->TITLE;
# $title->Text("Title String");
$body = $html->BODY;
$p = $body->P;
$p->Text("Some text");
$form = $body->FORM;
$form->method("POST");
$form->action("/SysAdmin/Account");
$table = $form->TABLE;
$table->border(2);
$row = $table->TR;
$header = $row->TH;
$header->Text("UserID");
$data = $row->TD;
# You can chain attribute methods, they return $self
$input = $data->INPUT->name("userid")->size(26);
$body->append($p);
$newp = $p->Clone;
$text = $newp->Text("More Text");
$body->append($newp);
# This is just to show that order doesn't really matter,
# everything is defered until the object hierarchy is rendered.
$text->append("\nadd more text to an already existing text");
print $html->realize;
Yields the following (indentation not present in actual output):
<HTML>
<HEAD>
<TITLE>
Title String
</TITLE>
</HEAD>
<BODY>
<P>
Some text
</P>
<FORM method="POST" action="/SysAdmin/Account">
<TABLE border="2">
<TR>
<TH>
UserID
</TH>
<TD>
<INPUT name="userid" size="26">
</TD>
</TR>
</TABLE>
</FORM>
<P>
Some text
</P>
<P>
Some text
More Text
add more text to an already existing text
</P>
</BODY>
</HTML>
Initial implementation November 1995. Rewrite to present form April 1996.
Copyright (c) 1995,1996 Berkeley Software Design, Inc.
http://www.bsdi.com/