HTML::Tiny(3) User Contributed Perl Documentation HTML::Tiny(3)NAMEHTML::Tiny - Lightweight, dependency free HTML/XML generation
VERSION
This document describes HTML::Tiny version 1.05
SYNOPSIS
use HTML::Tiny;
my $h = HTML::Tiny->new;
# Generate a simple page
print $h->html(
[
$h->head( $h->title( 'Sample page' ) ),
$h->body(
[
$h->h1( { class => 'main' }, 'Sample page' ),
$h->p( 'Hello, World', { class => 'detail' }, 'Second para' )
]
)
]
);
# Outputs
<html>
<head>
<title>Sample page</title>
</head>
<body>
<h1 class="main">Sample page</h1>
<p>Hello, World</p>
<p class="detail">Second para</p>
</body>
</html>
DESCRIPTION
"HTML::Tiny" is a simple, dependency free module for generating HTML
(and XML). It concentrates on generating syntactically correct XHTML
using a simple Perl notation.
In addition to the HTML generation functions utility functions are
provided to
· encode and decode URL encoded strings
· entity encode HTML
· build query strings
· JSON encode data structures
INTERFACE
"new"
Create a new "HTML::Tiny". The constructor takes one optional
argument: "mode". "mode" can be either 'xml' (default) or 'html'.
The difference is that in HTML mode, closed tags will not be closed
with a forward slash; instead, closed tags will be returned as
single open tags.
Example:
# Set HTML mode.
my $h = HTML::Tiny->new( mode => 'html' );
# The default is XML mode, but this can also be defined explicitly.
$h = HTML::Tiny->new( mode => 'xml' );
HTML is a dialect of SGML, and is not XML in any way. "Orphan" open
tags or unclosed tags are legal and in fact expected by user
agents. In practice, if you want to generate XML or XHTML, supply
no arguments. If you want valid HTML, use "mode => 'html'".
HTML Generation
"tag( $name, ... )"
Returns HTML (or XML) that encloses each of the arguments in the
specified tag. For example
print $h->tag('p', 'Hello', 'World');
would print
<p>Hello</p><p>World</p>
notice that each argument is individually wrapped in the specified
tag. To avoid this multiple arguments can be grouped in an
anonymous array:
print $h->tag('p', ['Hello', 'World']);
would print
<p>HelloWorld</p>
The [ and ] can be thought of as grouping a number of arguments.
Attributes may be supplied by including an anonymous hash in the
argument list:
print $h->tag('p', { class => 'normal' }, 'Foo');
would print
<p class="normal">Foo</p>
Attribute values will be HTML entity encoded as necessary.
Multiple hashes may be supplied in which case they will be merged:
print $h->tag('p',
{ class => 'normal' }, 'Bar',
{ style => 'color: red' }, 'Bang!'
);
would print
<p class="normal">Bar</p><p class="normal" style="color: red">Bang!</p>
Notice that the class="normal" attribute is merged with the style
attribute for the second paragraph.
To remove an attribute set its value to undef:
print $h->tag('p',
{ class => 'normal' }, 'Bar',
{ class => undef }, 'Bang!'
);
would print
<p class="normal">Bar</p><p>Bang!</p>
An empty attribute - such as 'checked' in a checkbox can be encoded
by passing an empty array reference:
print $h->closed( 'input', { type => 'checkbox', checked => [] } );
would print
<input checked type="checkbox" />
Return Value
In a scalar context "tag" returns a string. In a list context it
returns an array each element of which corresponds to one of the
original arguments:
my @html = $h->tag('p', 'this', 'that');
would return
@html = (
'<p>this</p>',
'<p>that</p>'
);
That means that when you nest calls to tag (or the equivalent HTML
aliases - see below) the individual arguments to the inner call
will be tagged separately by each enclosing call. In practice this
means that
print $h->tag('p', $h->tag('b', 'Foo', 'Bar'));
would print
<p><b>Foo</b></p><p><b>Bar</b></p>
You can modify this behavior by grouping multiple args in an
anonymous array:
print $h->tag('p', [ $h->tag('b', 'Foo', 'Bar') ] );
would print
<p><b>Foo</b><b>Bar</b></p>
This behaviour is powerful but can take a little time to master. If
you imagine '[' and ']' preventing the propagation of the 'tag
individual items' behaviour it might help visualise how it works.
Here's an HTML table (using the tag-name convenience methods - see
below) that demonstrates it in more detail:
print $h->table(
[
$h->tr(
[ $h->th( 'Name', 'Score', 'Position' ) ],
[ $h->td( 'Therese', 90, 1 ) ],
[ $h->td( 'Chrissie', 85, 2 ) ],
[ $h->td( 'Andy', 50, 3 ) ]
)
]
);
which would print the unformatted version of:
<table>
<tr><th>Name</th><th>Score</th><th>Position</th></tr>
<tr><td>Therese</td><td>90</td><td>1</td></tr>
<tr><td>Chrissie</td><td>85</td><td>2</td></tr>
<tr><td>Andy</td><td>50</td><td>3</td></tr>
</table>
Note how you don't need a td() for every cell or a tr() for every
row. Notice also how the square brackets around the rows prevent
tr() from wrapping each individual cell.
Often when generating nested HTML you will find yourself writing
corresponding nested calls to HTML generation methods. The table
generation code above is an example of this.
If you prefer these nested method calls can be deferred like this:
print $h->table(
[
\'tr',
[ \'th', 'Name', 'Score', 'Position' ],
[ \'td', 'Therese', 90, 1 ],
[ \'td', 'Chrissie', 85, 2 ],
[ \'td', 'Andy', 50, 3 ]
]
);
In general a nested call like
$h->method( args )
may be rewritten like this
[ \'method', args ]
This allows complex HTML to be expressed as a pure data structure.
See the "stringify" method for more information.
"open( $name, ... )"
Generate an opening HTML or XML tag. For example:
print $h->open('marker');
would print
<marker>
Attributes can be provided in the form of anonymous hashes in the
same way as for "tag". For example:
print $h->open('marker', { lat => 57.0, lon => -2 });
would print
<marker lat="57.0" lon="-2">
As for "tag" multiple attribute hash references will be merged. The
example above could be written:
print $h->open('marker', { lat => 57.0 }, { lon => -2 });
"close( $name )"
Generate a closing HTML or XML tag. For example:
print $h->close('marker');
would print:
</marker>
"closed( $name, ... )"
Generate a closed HTML or XML tag. For example
print $h->closed('marker');
would print:
<marker />
As for "tag" and "open" attributes may be provided as hash
references:
print $h->closed('marker', { lat => 57.0 }, { lon => -2 });
would print:
<marker lat="57.0" lon="-2" />
"auto_tag( $name, ... )"
Calls either "tag" or "closed" based on built in rules for the tag.
Used internally to implement the tag-named methods.
"stringify( $obj )"
Called internally to obtain string representations of values.
It also implements the deferred method call notation (mentioned
above) so that
my $table = $h->table(
[
$h->tr(
[ $h->th( 'Name', 'Score', 'Position' ) ],
[ $h->td( 'Therese', 90, 1 ) ],
[ $h->td( 'Chrissie', 85, 2 ) ],
[ $h->td( 'Andy', 50, 3 ) ]
)
]
);
may also be written like this:
my $table = $h->stringify(
[
\'table',
[
\'tr',
[ \'th', 'Name', 'Score', 'Position' ],
[ \'td', 'Therese', 90, 1 ],
[ \'td', 'Chrissie', 85, 2 ],
[ \'td', 'Andy', 50, 3 ]
]
]
);
Any reference to an array whose first element is a reference to a
scalar
[ \'methodname', args ]
is executed as a call to the named method with the specified args.
Methods named after tags
In addition to the methods described above "HTML::Tiny" provides all of
the following HTML generation methods:
a abbr acronym address area b base bdo big blockquote body br
button caption cite code col colgroup dd del div dfn dl dt em
fieldset form frame frameset h1 h2 h3 h4 h5 h6 head hr html i
iframe img input ins kbd label legend li link map meta noframes
noscript object ol optgroup option p param pre q samp script select
small span strong style sub sup table tbody td textarea tfoot th
thead title tr tt ul var
The following methods generate closed XHTML (<br />) tags by default:
area base br col frame hr img input meta param
So:
print $h->br; # prints <br />
print $h->input({ name => 'field1' });
# prints <input name="field1" />
print $h->img({ src => 'pic.jpg' });
# prints <img src="pic.jpg" />
All other tag methods generate tags to wrap whatever content they are
passed:
print $h->p('Hello, World');
prints:
<p>Hello, World</p>
So the following are equivalent:
print $h->a({ href => 'http://hexten.net' }, 'Hexten');
and
print $h->tag('a', { href => 'http://hexten.net' }, 'Hexten');
Utility Methods
"url_encode( $str )"
URL encode a string. Spaces become '+' and non-alphanumeric
characters are encoded as '%' + their hexadecimal character code.
$h->url_encode( ' <hello> ' ) # returns '+%3chello%3e+'
"url_decode( $str )"
URL decode a string. Reverses the effect of "url_encode".
$h->url_decode( '+%3chello%3e+' ) # returns ' <hello> '
"query_encode( $hash_ref )"
Generate a query string from an anonymous hash of key, value pairs:
print $h->query_encode({ a => 1, b => 2 })
would print
a=1&b=2
"entity_encode( $str )"
Encode the characters '<', '>', '&', '\'' and '"' as their HTML
entity equivalents:
print $h->entity_encode( '<>\'"&' );
would print:
<>'"&
"json_encode"
Encode a data structure in JSON (Javascript) format:
print $h->json_encode( { ar => [ 1, 2, 3, { a => 1, b => 2 } ] } );
would print:
{"ar":[1,2,3,{"a":1,"b":2}]}
Because JSON is valid Javascript this method can be useful when
generating ad-hoc Javascript. For example
my $some_perl_data = {
score => 45,
name => 'Fred',
history => [ 32, 37, 41, 45 ]
};
# Transfer value to Javascript
print $h->script( { type => 'text/javascript' },
"\nvar someVar = " . $h->json_encode( $some_perl_data ) . ";\n " );
# Prints
# <script type="text/javascript">
# var someVar = {"history":[32,37,41,45],"name":"Fred","score":45};
# </script>
If you attempt to json encode a blessed object "json_encode" will
look for a "TO_JSON" method and, if found, use its return value as
the structure to be converted in place of the object. An attempt to
encode a blessed object that does not implement "TO_JSON" will
fail.
Subclassing
An "HTML::Tiny" is a blessed hash ref.
"validate_tag( $closed, $name, $attr )"
Subclass "validate_tag" to throw an error or issue a warning when
an attempt is made to generate an invalid tag.
CONFIGURATION AND ENVIRONMENTHTML::Tiny requires no configuration files or environment variables.
DEPENDENCIES
By design HTML::Tiny has no non-core dependencies.
To run the tests you will require Test::More.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests to
"bug-html-tiny@rt.cpan.org", or through the web interface at
<http://rt.cpan.org>.
AUTHOR
Andy Armstrong "<andy@hexten.net>"
Aristotle Pagaltzis "<pagaltzis@gmx.de>"
LICENCE AND COPYRIGHT
Copyright (c) 2008, Andy Armstrong "<andy@hexten.net>". All rights
reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
perl v5.14.0 2009-03-08 HTML::Tiny(3)
