HTML::Tiny - Lightweight, dependency free HTML/XML generation
This document describes HTML::Tiny version 0.9
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>
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.
HTML::Tiny
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
new
Create a new HTML::Tiny. No arguments
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']);
<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');
<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!' );
<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!' );
<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 => [] } );
<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:
tag
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'));
<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') ] );
<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.
open( $name, ... )
Generate an opening HTML or XML tag. For example:
print $h->open('marker');
<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 });
<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');
<marker />
As for tag and open attributes may be provided as hash references:
open
print $h->closed('marker', { lat => 57.0 }, { lon => -2 });
<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.
closed
The format of tags generated by auto_tag (i.e. tags created by a direct call to auto_tag or to one of the tag-named convenience methods) may be modified in a number of ways.
auto_tag
Use set_open / set_closed to control whether the tags default to open (<br></br>) or closed (<br />).
set_open
set_closed
Use set_prefix / set_suffix to inject the specific string before / after each generated tag. Typically set_suffix is used to control which tags automatically have a newline appended after them.
set_prefix
set_suffix
Note: These settings only affect tags generated by auto_tag and the tag-named convenience methods. tag, open, close and closed provide a more primitive interface for tag creation which bypasses the auto-decoration stage.
close
set_open( $tagname, ... )
Specify a list of tags that will be generated in open form (<tag></tag>).
set_closed( $tagname, ... )
Specify a list of tags that will be generated in closed form (<tag />).
set_prefix( $prefix, $tagname, ... )
Set a prefix string to be added to the named tags.
set_suffix( $suffix, $tagname, ... )
Set a suffix string to be added to the named 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" />
This default behaviour can be overridden by calling set_open or set_closed with a list of tag names.
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');
url_encode( $str )
URL encode a string. Spaces become '+' and unprintable 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.
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 })
a=1&b=2
entity_encode( $str )
Encode the characters '<', '>', '&', '\'' and '"' as their HTML entity equivalents:
print $h->entity_encode( '<>\'"&' );
<>'"&
json_encode
Encode a data structure in JSON (Javascript) format:
print $h->json_encode( { ar => [ 1, 2, 3, { a => 1, b => 2 } ] } )
{"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>
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.
validate_tag
HTML::Tiny requires no configuration files or environment variables.
By design HTML::Tiny has no non-core dependencies.
None reported.
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.
bug-html-tiny@rt.cpan.org
Andy Armstrong <andy@hexten.net>
<andy@hexten.net>
Copyright (c) 2007, 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.
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.
To install HTML::Tiny, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Tiny
CPAN shell
perl -MCPAN -e shell install HTML::Tiny
For more information on module installation, please visit the detailed CPAN module installation guide.