NAME
HTML::Truncate - (beta software) truncate HTML by percentage or character count while preserving well-formedness.
VERSION
0.08
ABSTRACT
When working with text it is convenient and common to want to truncate strings to make them fit a desired context. E.g., you might have a menu that is only 100px wide and prefer text doesn't wrap so you'd truncate it around 15-30 characters, depending on preference and typeface size. This is trivial with plain text using substr but with HTML it is somewhat difficult because whitespace has fluid significance and open tags that are not properly closed destroy well-formedness and can wreck an entire layout.
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
my $ht = HTML::Truncate->new(utf => 1,
chars => 1_000,
);
print $ht->truncate($html), $/;XHTML
This module is designed to only work on XHTML-style nested tags. More below.
WHITESPACE & ENTITIES
Repeated natural whitespace (i.e., "\s+" and not " ") in HTML -- with rare exception (pre tags or user defined styles) -- is not meaningful. Therefore it is normalized when truncating. Entities are also normalized. The following is only counted 14 chars long.
\n<p>\nthis is ‘text’\n\n</p>
^^^^^^^12345----678--9------01234------^^^^^^^^METHODS
HTML::Truncate->new
Can take all the methods as hash style args. "percent" will always override "chars" so don't use them both.
my $ht = HTML::Truncate->new(utf8 => 1,
chars => 500, # default is 100
);$ht->style
Set/get. Either the default "text" or "html." (N.b.: only "text" is supported so far.) This determines which characters will counted for the truncation point. The reason why "html" is probably a poor choice is that you might set what you believe to be a reasonable truncation length of 20 chars and get an HTML tag like <a href="http://blah.blah.boo/longish/path/to/resource... and end up with no useful output.
Another problem is that the truncate might fall inside an attribute, like the "href" above, which means that attribute will necessarily be excluded, quite probably rendering the remaining tag invalid so the entire tag must be tossed out to preserve well-formedness.
But the best reason not to use "html" right now is it's not supported yet. It probably will be sometime in the future but unless you send a patch to do it, it will be awhile. It would be useful, for example to keep fixed length database records containing HTML truncated validly, but it's not something I plan to use personally so it will come last.
$ht->utf8
Set/get, true/false. If utf8 is set, entities will be transformed with HTML::Entity::decode and the default ellipsis will be a literal ellipsis and not the default of ….
$ht->chars
Set/get. The number of characters remaining after truncation, including the ellipsis. The style attribute determines whether the chars will only count text or HTML and text. Only "text" is supported currently.
Entities are counted as single characters. E.g., © is one character for truncation counts.
Default is "100."
$ht->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. If you ever add a truncate percent it will override any chars settings. The actual amount of character that the percent represents cannot be known until the given HTML is parsed.
$ht->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/ellipsisWhat 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.
$ht->truncate($html)
Also can be called with arguments--
$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<gt> without a </Pa<gt> are not supported and will cause a fatal error.
Certain tags are omitted by default from the truncated output. There will be a mechanism to custom tailor these--
-
<head>...</head> <script>...</script> <form>...</form> <iframe></iframe> <title>...</title> <style>...</style> <base/> <link/> <meta/> -
<br/> <img/> <hr/> <input/> <link/> <base/>
$ht->add_skip_tags( qw( tag list ) )
Put one or more new tags into the list of those to be ommitted from truncated output. An example of when you might like to use this is if you're thumbnailing 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' );$ht->dont_skip_tags( qw( tag list ) )
Takes tags out of the current list to be omitted from truncated output.
TO DO
Many more tests. Allow new stand alone tags to be added. Go through entire dist and make sure everything is kosher (autogenerated with the lovely Module::Starter). Reorganize POD to read in best learning order. Make sure the padding check is working across wide range of cases. POD to describe various ways to use it including a TT2 filter. "html" style truncating.
AUTHOR
Ashley Pond V, <ashley@cpan.org>.
LIMITATIONS
There are places where this will break down right now. I'll pad out possible edge cases as I find them or they are sent to me via the CPAN bug ticket system.
This is not an HTML filter
Although this happens to do some crude HTML filtering to achieve its end, it is not a fully featured filter. If you are looking for one, check out HTML::Scrubber and HTML::Sanitizer.
BUGS, FEEDBACK, PATCHES
Please report any bugs or feature requests to bug-html-truncate@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-Truncate. I will get the ticket, and then you'll automatically be notified of progress as I make changes.
SEE ALSO
HTML::Entities, HTML::TokeParser, the "truncate" filter in Template, and Text::Truncate.
HTML::Scrubber and HTML::Sanitizer.
HTML::FillInForm (note about...).
COPYRIGHT & LICENSE
Copyright 2005 Ashley Pond V, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.