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

  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

"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.