NAME

VERSION

ABSTRACT

HTML::Truncate attempts to account for those two problems by padding truncation for spacing and entities and closing any tags that remain open at the point of truncation.

SYNOPSIS

 use strict;
 use HTML::Truncate;

 my $html = '<p><i>We</i> have to test <b>something</b>.</p>';
 my $readmore = '... <a href="/full-article">[readmore]</a>';

 my $html_truncate = HTML::Truncate->new();
 $html_truncate->chars(20);
 $html_truncate->ellipsis($readmore);
 print $html_truncate->truncate($html);

 # or

 use Encode;
 my $ht = HTML::Truncate->new( utf8_mode => 1,
                               chars => 1_000,
                              );
 print Encode::encode_utf8( $ht->truncate($html) );

XHTML

WHITESPACE AND ENTITIES

  \n<p>\nthis     is   &#8216;text&#8217;\n\n</p>
  ^^^^^^^12345----678--9------01234------^^^^^^^^

METHODS

new

Can take all the methods as hash style args. "percent" and "chars" are incompatible so don't use them both. Whichever is set most recently will erase the other.

 my $ht = HTML::Truncate->new(utf8_mode => 1,
                              chars => 500, # default is 100
                              );
    

utf8_mode

Set/get, true/false. If "utf8_mode" is set, utf8_mode(1) is also set in the underlying HTML::Parser, entities will be transformed with decode and the default ellipsis will be a literal ellipsis and not the default of "…".

chars

Set/get. The number of characters remaining after truncation, excluding the "ellipsis".

Entities are counted as single characters. E.g., "©" is one character for truncation counts.

Default is "100." Side-effect: clears any "percent" that has been set.

percent

Set/get. A percentage to keep while truncating the rest. For a document of 1,000 chars, percent('15%') and chars(150) would be equivalent. The actual amount of character that the percent represents cannot be known until the given HTML is parsed.

Side-effect: clears any "chars" that has been set.

ellipsis

Set/get. Ellipsis in this case means --

    The omission of a word or phrase necessary for a complete
    syntactical construction but not necessary for understanding.
                         http://www.answers.com/topic/ellipsis
    

What it will probably mean in most real applications is "read more." The default is "…" which if the utf8 flag is true will render as a literal ellipsis, "chr(8230)".

The reason the default is "…" and not "..." is this is meant for use in HTML environments, not plain text, and "..." (dot-dot-dot) is not typographically correct or equivalent to a real horizontal ellipsis character.

truncate

It returns the truncated XHTML if asked for a return value.

 my $truncated = $ht->truncate($html);
    

It will truncate the string in place if no return value is expected (wantarray is not defined).

   $ht->truncate($html);
   print $html;
    

Also can be called with inline arguments-

   print $ht->truncate( $html,
                        $chars_or_percent,
                        $ellipsis );
    

No arguments are strictly required. Without HTML to operate upon it returns undef. The two optional arguments may be preset with the methods "chars" (or "percent") and "ellipsis".

Valid nesting of tags is required (alla XHTML). Therefore some old HTML habits like <p> without a </p> are not supported and may cause a fatal error. See "repair" for help with badly formed HTML.

Certain tags are omitted by default from the truncated output.

add_skip_tags( qw( tag list ) )

Put one or more new tags into the list of those to be omitted from truncated output. An example of when you might like to use this is if you're thumb-nailing articles and they start with "<h1>title</h1>" or such before the article body. The heading level would be absurd with a list of excerpts so you could drop it completely this way--

 $ht->add_skip_tags( 'h1' );
    

dont_skip_tags( qw( tag list ) )

Takes tags out of the current list to be omitted from truncated output.

repair

Set/get, true/false. If true, will attempt to repair unclosed HTML tags by adding close-tags as late as possible (eg. "<i><b>foobar</i>" becomes "<i><b>foobar</b></i>"). Unmatched close tags are dropped ("foobar</b>" becomes "foobar").

on_space

This will make the truncation back up to the first space it finds so it doesn't truncate in the the middle of a word. "on_space" runs before "cleanly" if both are set.

cleanly

Set/get -- a regular expression. This is on by default and the default cleaning regular expression is "cleanly(qr/[\s[:punct:]]+\z/)". It will make the truncation strip any trailing spacing and punctuation so you don't get things like "The End...." or "What? ..." You can cancel it with "$ht->cleanly(undef)" or provide your own regular expression.

COOKBOOK (well, a recipe)

 use Template;
 use HTML::Truncate;

 my %config =
    (
     FILTERS => {
         truncate_html => [ \&truncate_html_filter_factory, 1 ],
     },
     );

 my $tt = Template->new(\%config) or die $Template::ERROR;

 # ... etc ...

 sub truncate_html_filter_factory {
     my ( $context, $len, $ellipsis ) = @_;
     $len = 32 unless $len;
     $ellipsis = chr(8230) unless defined $ellipsis;
     my $ht = HTML::Truncate->new();
     $ht->add_skip_tags(qw( img ));
     return sub {
         my $html = shift || return '';
         return $ht->truncate( $html, $len, $ellipsis );
     }
 }

 [% FOR item IN search_results %]
   <div class="searchResult">
     <a href="[% item.uri %]">[% item.title %]</a><br />
     [% item.body | truncate_html(200) %]
   </div>
 [% END %]

AUTHOR

LIMITATIONS

BUGS, FEEDBACK, PATCHES

THANKS TO

Lorenzo Iannuzzi for the "on_space" functionality.

SEE ALSO

HTML::Scrubber and HTML::Sanitizer.

COPYRIGHT & LICENSE

This program is free software; you can redistribute it or modify it or both under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.