/ 
String-Tagged-HTML-0.03
River stage one • 1 direct dependent • 1 total dependent
/ String::Tagged::HTML

NAME

String::Tagged::HTML - handle HTML content using String::Tagged

SYNOPSIS

use String::Tagged::HTML;

my $st = String::Tagged::HTML->new( "An important message" );

$st->apply_tag( 3, 9, b => 1 );

print $st->as_html( "h1" );

DESCRIPTION

This subclass of String::Tagged provides a method, as_html, for rendering the string as an HTML fragment, using the tags to provide formatting. For example, the SYNOPSIS example will produce the output

<h1>An <b>important</b> message</h1>

With the exception of tags named raw, a tag applied to an extent of the String::Tagged::HTML will be rendered using start and end HTML tags of the same name. If the tag's value is a HASH reference, then this hash will be used to provide additional attributes for the HTML element. Tags whose names begin with _ will be ignored for this purpose.

my $str = String::Tagged::HTML->new( "click " )
   ->append_tagged( "here", a => { href => "/see/other.html" } );

print $str->as_html( "p" );

<p>click <a href="/see/other.html">here</a></p>

If it is not a HASH reference, then its value ought to be a simple boolean true value, such as 1.

The special tag named raw disables HTML entity escaping over its extent.

my $str = String::Tagged::HTML->new( "This <content> is escaped" );

my $br = String::Tagged::HTML->new_tagged( "<br/>", raw => 1 );

print +( $str . $br )->as_html( "p" );

<p>This &lt;content&gt; is escaped<br/></p>

Automatic <span> Generation

Tags whose names begin _span_style_... are used to create a style attribute for an implied span tag.

All tags with this name prefix are collected together. The part of the name following this prefix is used as the style property name and the value of the tag used for its value. These are all joined into a single string, and that is then used to generate the style tag.

As an extra convenience, any remaining underscores in the tag name will be converted to hyphens in the style property name.

my $str = String::Tagged::HTML->new( "Some big text" );
$str->apply_tag( 5, 3, _span_style_font_size => "large" );

print $str->as_html

Some <span style="font-size: large;">big</span> text

Tag Nesting

Because of the arbitrary way that String::Tagged tags may be applied, as compared to the strict nesting requirements in HTML, the as_html method may have to break a single String::Tagged tag into multiple regions. In the following example, the i tag has been split in two to allow it to overlap correctly with b.

my $str = String::Tagged::HTML->new( "bbb b+i iii" );
$str->apply_tag( 0, 7, b => 1 );
$str->apply_tag( 4, 7, i => 1 );

print $str->as_html

<b>bbb <i>b+i</i></b><i> iii</i>

String::Tagged::Formatting SUPPORT

String::Tagged::Formatting specifes a standard way that subclasses of String::Tagged can express a variety of simple formatting styles. HTML is a lot more flexible than this (and CSS doubly so). Certain limited support is provided for converting String::Tagged::Formatting tags into a form that can be rendered into standalone HTML.

The following tag conversions are supported:

bold                 <strong>
under                <u>
italic               <em>
strike               <strike>
monospace            <tt>

sizepos = "super"    <sup>
sizepod = "sub"      <sub>

fg                   <span style="color: #rrggbb">
bg                   <span style="background-color: #rrggbb">

link                 <a href="uri">

CONSTRUCTORS

As well as the standard new and new_tagged constructors provided by String::Tagged, the following is provided.

new_raw

$st = String::Tagged::HTML->new_raw( $str );

Returns a new String::Tagged::HTML instance with the raw tag applied over its entire length. This convenience is provided for creating objects containing already-rendered HTML fragments.

new_from_formatting

$st = String::Tagged::HTML->new_from_formatting( $fmt, %params );

Returns a new instance by converting String::Tagged::Formatting standard tags, as described above.

The following additional named arguments are recognised:

convert_linefeeds => BOOL

Optional. If true, linefeeds in the source string will be converted into <br/> HTML tags in the result. Defaults to true if absent, but the behaviour can be disabled by passing a defined-but-false value.

parse_html

$st = String::Tagged::HTML->parse_html( $html );

Returns a new String::Tagged::HTML instance by parsing the given HTML content and composing the plaintext parts of the content, with tags applied over the appropriate ranges of it.

This parsing is currently performed using HTML::TreeBuilder, and will not work if that module is not available.

METHODS

The following methods are provided in addition to those provided by String::Tagged.

as_html

$html = $st->as_html( $element );

Returns a string containing an HTML rendering of the current contents of the object. If $element is provided, the output will be wrapped in an element of the given name. If not defined, no outer wrapping will be performed.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>