/ 
HTML-GenerateUtil-1.02
River stage one • 1 direct dependent • 1 total dependent
/ HTML::GenerateUtil

NAME

HTML::GenerateUtil - Routines useful when generating HTML output

SYNOPSIS

use HTML::GenerateUtil qw(escape_html generate_attributes generate_tag :consts);

my $Html = "text < with > things & that need \x{1234} escaping";
$Html = escape_html($Html, 0);

... or ...

escape_html($Html, EH_INPLACE);

... also ...

my $Attr = generate_attributes({ href => 'http://...', title => 'blah' });
$Html = "<a $Attr>$Html</a>";

... but even better ...

$Html = generate_tag('a', { href => 'http://...', title => 'blah' }, $Html, 0);

DESCRIPTION

Provides a number of functions that make generating HTML output easier and faster. All written in XS for speed.

CONTEXT

When creating a web application in perl, you've got a couple of main choices on how to actually generate the HTML that gets output:

  • Programatically generating the HTML in perl

  • Using some template system for the HTML and inserting the data calculated in perl as appropriate

Your actual application, experience and environment will generally determine which is the best way to.

If you go the programatic route, then you generally need some way of generating the actual HTML output in perl. Again, there's generally a couple of ways of doing this.

  • Just joining together text strings in perl as appropriate.

    Eg. $link = "<a href="$ref">$text</a>";

  • Or using some function module like CGI

    Eg. $line = a({ href => $ref }, $text);

  • More complex object systems like HTML::Table

The first seems easy, but it gets harder when you have to manually escape each string to avoid placing special HTML chars (eg <, etc) in strings like $text above.

With the CGI, most of this is automatically taken care of, and most strings are automatically escaped to replace special HTML chars with their entity equivalents.

While this is nice, CGI is written in pure perl, and can end up being a bit slow, especially if you already have a fast system that generates pages very heavy in tags (eg lots of table elements, links, etc)

That's where this module comes it. It provides functions useful for escaping html and generating HTML tags, but it's all written in XS to be very fast. It's also fully UTF-8 aware.

FUNCTIONS

escape_html($Str, $Mode)

Escapes the contents of $Str to change the chars [<>&"] to '&lt;', '&gt;', '&amp;' and '&quot;' repectively.

$Mode is a bit field with the additional options or'd together:

  • EH_INPLACE - modify in-place, otherwise return new copy

  • EH_LFTOBR - convert \n to <br>

  • EH_SPTONBSP - convert ' ' to ' &nbsp;'

Useful for turning text into similar to <pre> form without actually being in <pre> tags

generate_attributes($HashRef)

Turns the contents of $HashRef of the form:

{
  aaa => 'bbb',
  ccc => undef
}

Into a string of the form:

q{aaa="bbb" ccc}

Useful for generating HTML tags. The values of each hash entry are escaped with escape_html() before being added to the final string.

If you want to use a raw value unescaped, pass it as an array ref with a single item. Eg.

{
  aaa => [ '<blah>' ],
  bbb => '<blah'>
}

Is turned into:

q{aaa="<blah>" bbb="&lt;blah&gt;"}
generate_tag($Tag, $AttrHashRef, $Value, $Mode)

Creates an HTML tag of the basic form:

<$Tag %$AttrHashRef>$Value</$Tag>

If $AttrHashRef is undef, then no attributes are created. Otherwise generate_attributes() is called to stringify the hash ref.

If $Value is undef, then no $Value is included, and no </$Tag> is added.

$Mode is a bit field with the additional options:

  • GT_ESCAPEVAL - call escape_html on $Value

  • GT_ADDNEWLINE - append \n to output of string

SEE ALSO

Apache::Util, HTML::Entities, CGI

Latest news/details can also be found at:

http://cpan.robm.fastmail.fm/htmlgenerateutil/

AUTHOR

Rob Mueller <cpan@robm.fastmail.fm>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by FastMail IP Partners

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.