.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTML::Tiny 3pm" .TH HTML::Tiny 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTML::Tiny \- Lightweight, dependency free HTML/XML generation .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use HTML::Tiny; \& \& my $h = HTML::Tiny\->new; \& \& # Generate a simple page \& print $h\->html( \& [ \& $h\->head( $h\->title( \*(AqSample page\*(Aq ) ), \& $h\->body( \& [ \& $h\->h1( { class => \*(Aqmain\*(Aq }, \*(AqSample page\*(Aq ), \& $h\->p( \*(AqHello, World\*(Aq, { class => \*(Aqdetail\*(Aq }, \*(AqSecond para\*(Aq ) \& ] \& ) \& ] \& ); \& \& # Outputs \& \&
\&Hello, World
\&Second para
\& \& .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`HTML::Tiny\*(C'\fR is a simple, dependency free module for generating \&\s-1HTML\s0 (and \s-1XML\s0). It concentrates on generating syntactically correct \&\s-1XHTML\s0 using a simple Perl notation. .PP In addition to the \s-1HTML\s0 generation functions utility functions are provided to .IP "\(bu" 4 encode and decode \s-1URL\s0 encoded strings .IP "\(bu" 4 entity encode \s-1HTML\s0 .IP "\(bu" 4 build query strings .IP "\(bu" 4 \&\s-1JSON\s0 encode data structures .SH "INTERFACE" .IX Header "INTERFACE" .ie n .IP """new""" 4 .el .IP "\f(CWnew\fR" 4 .IX Item "new" Create a new \f(CW\*(C`HTML::Tiny\*(C'\fR. The constructor takes one optional argument: \f(CW\*(C`mode\*(C'\fR. \f(CW\*(C`mode\*(C'\fR can be either \f(CW\*(Aqxml\*(Aq\fR (default) or \f(CW\*(Aqhtml\*(Aq\fR. The difference is that in \s-1HTML\s0 mode, closed tags will not be closed with a forward slash; instead, closed tags will be returned as single open tags. .Sp Example: .Sp .Vb 2 \& # Set HTML mode. \& my $h = HTML::Tiny\->new( mode => \*(Aqhtml\*(Aq ); \& \& # The default is XML mode, but this can also be defined explicitly. \& $h = HTML::Tiny\->new( mode => \*(Aqxml\*(Aq ); .Ve .Sp \&\s-1HTML\s0 is a dialect of \s-1SGML,\s0 and is not \s-1XML\s0 in any way. \*(L"Orphan\*(R" open tags or unclosed tags are legal and in fact expected by user agents. In practice, if you want to generate \s-1XML\s0 or \s-1XHTML,\s0 supply no arguments. If you want valid \s-1HTML,\s0 use \f(CW\*(C`mode => \*(Aqhtml\*(Aq\*(C'\fR. .SS "\s-1HTML\s0 Generation" .IX Subsection "HTML Generation" .ie n .IP """tag( $name, ... )""" 4 .el .IP "\f(CWtag( $name, ... )\fR" 4 .IX Item "tag( $name, ... )" Returns \s-1HTML\s0 (or \s-1XML\s0) that encloses each of the arguments in the specified tag. For example .Sp .Vb 1 \& print $h\->tag(\*(Aqp\*(Aq, \*(AqHello\*(Aq, \*(AqWorld\*(Aq); .Ve .Sp would print .Sp .Vb 1 \&Hello
World
.Ve .Sp notice that each argument is individually wrapped in the specified tag. To avoid this multiple arguments can be grouped in an anonymous array: .Sp .Vb 1 \& print $h\->tag(\*(Aqp\*(Aq, [\*(AqHello\*(Aq, \*(AqWorld\*(Aq]); .Ve .Sp would print .Sp .Vb 1 \&HelloWorld
.Ve .Sp The [ and ] can be thought of as grouping a number of arguments. .Sp Attributes may be supplied by including an anonymous hash as the first element in the argument list (after the tag name): .Sp .Vb 1 \& print $h\->tag(\*(Aqp\*(Aq, { class => \*(Aqnormal\*(Aq }, \*(AqFoo\*(Aq); .Ve .Sp would print .Sp .Vb 1 \&Foo
.Ve .Sp Attribute values will be \s-1HTML\s0 entity encoded as necessary. .Sp Multiple hashes may be supplied in which case they will be merged: .Sp .Vb 4 \& print $h\->tag(\*(Aqp\*(Aq, \& { class => \*(Aqnormal\*(Aq }, \*(AqBar\*(Aq, \& { style => \*(Aqcolor: red\*(Aq }, \*(AqBang!\*(Aq \& ); .Ve .Sp would print .Sp .Vb 1 \&Bar
Bang!
.Ve .Sp Notice that the class=\*(L"normal\*(R" attribute is merged with the style attribute for the second paragraph. .Sp To remove an attribute set its value to undef: .Sp .Vb 4 \& print $h\->tag(\*(Aqp\*(Aq, \& { class => \*(Aqnormal\*(Aq }, \*(AqBar\*(Aq, \& { class => undef }, \*(AqBang!\*(Aq \& ); .Ve .Sp would print .Sp .Vb 1 \&Bar
Bang!
.Ve .Sp An empty attribute \- such as 'checked' in a checkbox can be encoded by passing an empty array reference: .Sp .Vb 1 \& print $h\->closed( \*(Aqinput\*(Aq, { type => \*(Aqcheckbox\*(Aq, checked => [] } ); .Ve .Sp would print .Sp .Vb 1 \& .Ve .Sp \&\fBReturn Value\fR .Sp In a scalar context \f(CW\*(C`tag\*(C'\fR returns a string. In a list context it returns an array each element of which corresponds to one of the original arguments: .Sp .Vb 1 \& my @html = $h\->tag(\*(Aqp\*(Aq, \*(Aqthis\*(Aq, \*(Aqthat\*(Aq); .Ve .Sp would return .Sp .Vb 4 \& @html = ( \& \*(Aqthis
\*(Aq, \& \*(Aqthat
\*(Aq \& ); .Ve .Sp That means that when you nest calls to tag (or the equivalent \s-1HTML\s0 aliases \- see below) the individual arguments to the inner call will be tagged separately by each enclosing call. In practice this means that .Sp .Vb 1 \& print $h\->tag(\*(Aqp\*(Aq, $h\->tag(\*(Aqb\*(Aq, \*(AqFoo\*(Aq, \*(AqBar\*(Aq)); .Ve .Sp would print .Sp .Vb 1 \&Foo
Bar
.Ve .Sp You can modify this behavior by grouping multiple args in an anonymous array: .Sp .Vb 1 \& print $h\->tag(\*(Aqp\*(Aq, [ $h\->tag(\*(Aqb\*(Aq, \*(AqFoo\*(Aq, \*(AqBar\*(Aq) ] ); .Ve .Sp would print .Sp .Vb 1 \&FooBar
.Ve .Sp 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. .Sp Here's an \s-1HTML\s0 table (using the tag-name convenience methods \- see below) that demonstrates it in more detail: .Sp .Vb 10 \& print $h\->table( \& [ \& $h\->tr( \& [ $h\->th( \*(AqName\*(Aq, \*(AqScore\*(Aq, \*(AqPosition\*(Aq ) ], \& [ $h\->td( \*(AqTherese\*(Aq, 90, 1 ) ], \& [ $h\->td( \*(AqChrissie\*(Aq, 85, 2 ) ], \& [ $h\->td( \*(AqAndy\*(Aq, 50, 3 ) ] \& ) \& ] \& ); .Ve .Sp which would print the unformatted version of: .Sp .Vb 6 \&Name | Score | Position |
---|---|---|
Therese | 90 | 1 |
Chrissie | 85 | 2 |
Andy | 50 | 3 |
Hello, World
.Ve .PP So the following are equivalent: .PP .Vb 1 \& print $h\->a({ href => \*(Aqhttp://hexten.net\*(Aq }, \*(AqHexten\*(Aq); .Ve .PP and .PP .Vb 1 \& print $h\->tag(\*(Aqa\*(Aq, { href => \*(Aqhttp://hexten.net\*(Aq }, \*(AqHexten\*(Aq); .Ve .SS "Utility Methods" .IX Subsection "Utility Methods" .ie n .IP """url_encode( $str )""" 4 .el .IP "\f(CWurl_encode( $str )\fR" 4 .IX Item "url_encode( $str )" \&\s-1URL\s0 encode a string. Spaces become '+' and non-alphanumeric characters are encoded as '%' + their hexadecimal character code. .Sp .Vb 1 \& $h\->url_encode( \*(Aq