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

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>