=encoding utf8

=head1 NAME

Html::FromMail::Default::Previewers - produce smaller versions of data items

=head1 SYNOPSIS

=head1 DESCRIPTION

These functions define the default algorithms to produce previews for
message bodies.  When a message part is inlined, and there is an
htmlifier defined for it, that will be prevailed
(see HTML::FromMail::Default::HTMLifiers).  When inlining is not possible
or not requested, there may be a preview constructed.  The defaults are
defined in this module.

Any function here shall return something reasonable, even if the conversion
fails for some reason.  Each fuction returns the data for a referenve to a
hash of values, which are accessible in the output formatter.  Each HASH
must define either

  image => {}, html => ''     # an image is produced, or
  image => '', html => {}     # html was produced

Each of the functions is called with five arguments: C<$page>, C<$message>,
C<$part>, C<\%attach>, and C<\%options>.
The C<$page> is the object which produces pages,
an extension of L<HTML::FromMail::Page|HTML::FromMail::Page>.  The C<$message> is the main message
which is displayed (a Mail::Message object).  The C<$part> is either
the whole C<$message> or a part within a multipart or nested message (a
Mail::Message::Part object).  The C<$part> information is to be processed.

As C<\%attach>, a reference to a HASH with information about the created
attachement is passed. This information is needed to produce the preview.
That same hash is extended with more information from the previewer, and
then accessible via the formatter.

The C<\%options> is a wild combination of information about the formatter
and information defined by it.  For instance, the arguments which are
passed with the tag in the template file can be found in there.  Print the
content of the hash to see how much information you get... (sorry for this
rough description)

=head1 FUNCTIONS

=over 4

=item B<previewHtml>($page, $mssage, $part, \%attach, \%options)

Produce a small preview of the html, where first the title is taken
and put in bold. The rest of the header is removed.  Then the first
characters of the rest of the content are displayed.

 -Option        --Default
  text_max_chars  250

=over 2

=item text_max_chars => INTEGER

=back

» example: of a plain text preview with the Text::MagicTemplate formatter

  <!--{preview text_max_chars => 120}-->
     <!--{html}-->
        <blockquote><cite>
        <!--{text}-->&nbsp;...
        </cite></blockquote>
     <!--{/html}-->
  <!--{/preview}-->

=item B<previewImage>($page, $mssage, $part, \%attach, \%options)

Produce a small preview of the html, where first the title is taken
and put in bold. The rest of the header is removed.  Then the first
characters of the rest of the content are displayed.

 -Option        --Default
  img_max_height  250
  img_max_width   250

=over 2

=item img_max_height => INTEGER

=item img_max_width => INTEGER

=back

» example: of a plain text preview with the Text::MagicTemplate formatter

  <!--{preview img_max_width => 200, img_max_height => 200}-->
     <!--{image}-->
     <!--{/image}-->
  <!--{/preview}-->

=item B<previewText>($page, $mssage, $part, \%attach, \%options)

Produce a small preview of the text, where all wrappig is removed.

 -Option        --Default
  text_max_chars  250

=over 2

=item text_max_chars => INTEGER

=back

» example: of a plain text preview with the Text::MagicTemplate formatter

  <!--{preview text_max_chars => 120}-->
     <!--{html}-->
        <blockquote><cite>
        <!--{text}-->&nbsp;...
        </cite></blockquote>
     <!--{/html}-->
  <!--{/preview}-->

=back

=head1 SEE ALSO

This module is part of HTML-FromMail version 3.01,
built on November 21, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

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

