=encoding utf8

=head1 NAME

HTML::FromMail::Message - output a message as HTML

=head1 INHERITANCE

 HTML::FromMail::Message
   is a HTML::FromMail::Page
   is a HTML::FromMail::Object
   is a Mail::Reporter

=head1 SYNOPSIS

=head1 DESCRIPTION

THIS MODULE IS UNDER CONSTRUCTION.  However, a lot of things already
work.  Best take a look at the examples directory.

Extends L<"DESCRIPTION" in HTML::FromMail::Page|HTML::FromMail::Page/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in HTML::FromMail::Page|HTML::FromMail::Page/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in HTML::FromMail::Page|HTML::FromMail::Page/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Z<>

 -Option  --Defined in            --Default
  settings  HTML::FromMail::Object  {}
  topic     HTML::FromMail::Object  'message'

=over 2

=item settings => \%map

=item topic => STRING

=back

=back

=head2 Attributes

Extends L<"Attributes" in HTML::FromMail::Page|HTML::FromMail::Page/"Attributes">.

=over 4

=item $obj-E<gt>B<fields>()

Returns the field text producing object.

=item $obj-E<gt>B<header>()

Returns the header text producting object.

=item $obj-E<gt>B<settings>( [TOPIC] )

Inherited, see L<HTML::FromMail::Object/"Attributes">

=item $obj-E<gt>B<topic>()

Inherited, see L<HTML::FromMail::Object/"Attributes">

=back

=head2 Other methods

Extends L<"Other methods" in HTML::FromMail::Page|HTML::FromMail::Page/"Other methods">.

=over 4

=item $obj-E<gt>B<createAttachment>($message, $part, \%options)

Create an attachment file, and return a HASH with information about
that file.  Returns C<undef> if creation fails.

This method is used by L<htmlAttach()|HTML::FromMail::Message/"Other methods"> and L<htmlPreview()|HTML::FromMail::Message/"Other methods"> to create
an actual attachment file.  It defines C<url>, C<size> and C<type>
tags for the template.

 -Option--Default
  outdir  <required>

=over 2

=item outdir => $directory

The name of the C<$directory> where the external file will be produced.

=back

=item $obj-E<gt>B<disposition>($message, $part, \%options)

Returns a string, which is either C<inline>, C<attach>, or C<preview>,
which indicates how the C<$part> of the C<$message> should be formatted.
This can be changed with setting C<disposition>.

=item $obj-E<gt>B<htmlAddresses>($message, \%options)

Produce data about addresses which are in the field.  This method uses
L<HTML::FromMail::Field::htmlAddresses()|HTML::FromMail::Field/"Other methods"> for that.

=item $obj-E<gt>B<htmlAttach>($message, \%options)

The C<attach> container defines C<url>, C<size> and C<type>
tags for the template.

» example: using HTML::FromMail::Format::Magic

  <!--{message}-->
    <!--{attach}-->
    <!--{/attach}-->
  <!--{/message}-->

=item $obj-E<gt>B<htmlBody>($message, \%options)

Produce the body of a field.  This tag can only be used inside a field
container. See L<HTML::FromMail::Field::htmlBody()|HTML::FromMail::Field/"Other methods"> for the use and
options.

=item $obj-E<gt>B<htmlField>($message, \%options)

Returns the field definition for the currently active message part. When
the formatter sees this is a final token, then only the body of the
field is returned (and the options of L<HTML::FromMail::Field::htmlBody()|HTML::FromMail::Field/"Other methods">
are accepted as well).  Otherwise, the information about the field is
captured to be used later.

 -Option--Default
  decode  true if possible
  from    'PART'
  name    <required>

=over 2

=item decode => BOOLEAN

=item from => 'PART'|'PARENT'|'MESSAGE'

The source of this field: the currently active 'PART' (which may be the
main message), the 'PARENT' of the active part (defaults to the message),
or the main C<$message> itself.

=item name => STRING

=back

» example: using HTML::FromMail::Format::Magic

  <!--{field name => To, content => REFOLD, wrap => 20}-->

  <!--{field name => To}-->
     <!--{name capitals => WELLFORMED}-->
     <!--{body wrap => 30}-->
  <!--{/field}-->

=item $obj-E<gt>B<htmlForeachPart>($message|$part, \%options)

Produces html for the parts of a multipart body.  Each C<$part>
may be a multipart too.  For each part, the C<message> container
code is applied recursively.

This container defines a C<part_number>, and enables the use of the
C<part> tag.

» example: using HTML::FromMail::Format::Magic

  <!--{message}-->
    <!--{multipart}-->
      <ul>
      <!--{foreachPart}-->
      <li>This is part <!--{part_number}-->
          <!--{part}-->
      </li>
      <!--{/foreachPart}-->
      </ul>
    <!--{/multipart}-->
  <!--{message}-->

=item $obj-E<gt>B<htmlHead>($message, \%options)

Defines the fields of a header.  The options are provided by
L<HTML::FromMail::Head::fields()|HTML::FromMail::Head/"Other methods">.

» example: using HTML::FromMail::Format::Magic

  # simple
  <pre><!--{head}--></pre>

  # complex
  <table>
  <!--{head remove_spam_groups => 0}-->
    <tr><td><!--{name}--></td>
        <td><!--{body}--></td></tr>
  <!--{/head}-->
  </table>

=item $obj-E<gt>B<htmlInline>($message, \%options)

Z<>

 -Option--Default
  type    ''

=over 2

=item type => $mime_type

Selects the C<$mime_type> which is handled by this singlepart block.  Type
comparison uses MIME::Type, so is smart.

=back

» example: using HTML::FromMail::Format::Magic

  <!--{message}-->
     <!--{inline type => text/html}-->
        <!--{html}-->
     <!--{/inline}-->
  <!--{/message}-->

=item $obj-E<gt>B<htmlMessage>($message, \%options)

Encapsulated code which is producing the C<$message>, which may
be a multipart.  You have to defined the message block when
you use the part (see L<htmlPart()|HTML::FromMail::Message/"Other methods">) tag.  If you do not use
that, you do not need this.

» example: using HTML::FromMail::Format::Magic

  <!--{message}-->
    <!--{inline}-->This is an inlined singlepart<!--{/inline}-->
    <!--{attach}-->This is an attachment<!--{/attach}-->
    <!--{preview}-->An attachment with preview<!--{/preview}-->
    <!--{multipart}-->This is a multipart<!--{/multipart}-->
    <!--{nested}-->message/rfc822 encapsulated<!--{/nested}-->
  <!--{/message}-->

=item $obj-E<gt>B<htmlMultipart>($message, \%options)

Encapsulates text to be produced when the C<$message>(-part) is a
multipart.

=item $obj-E<gt>B<htmlName>($message, \%options)

Produce the name of a field.  This tag can only be used inside a field
container. See L<HTML::FromMail::Field::htmlName()|HTML::FromMail::Field/"Other methods"> for the use and
options.

=item $obj-E<gt>B<htmlNested>($message, \%options)

Contains text to be produced when the C<$message>(-part) is a
nested message; encapsulated in a message/rfc822.

=item $obj-E<gt>B<htmlPart>($message|$part, \%options)

Apply the C<$message> container of the current C<$part> on its data.  See example
in L<htmlForeachPart()|HTML::FromMail::Message/"Other methods">.

=item $obj-E<gt>B<htmlPreview>($message, \%options)

Z<>

 -Option--Default
  type    ''

=over 2

=item type => $mime_type

Selects the C<$mime_type> which are handled by this singlepart block.  You can
specify the types as defined by MIME::Type subroutine equals.

The C<preview> container defines C<url>, C<size> and C<type>
tags for the template, which describe the attachment file.  Besides,
it preview defines a tag which tells whether the preview is made as
C<html> or as C<image>.  Within an C<html> block, you will get an
extra C<text> which includes the actual html preview text.

The C<image> container provides more tags: C<smallurl>,
C<smallwidth>, C<smallheight>, C<width>, and C<height>.

=back

» example: using HTML::FromMail::Format::Magic

  <!--{message}-->
    <!--{preview}-->
       <!--{html}-->
          <!--{text}-->
       <!--{/html}-->
       <!--{image}-->
          <img src="<!--{smallurl}-->"
           width="<!--{smallwidth}-->"
           height="<!--{smallheight}-->"><br />
           (real is <!--{width}--> x <!--{height}-->)
       <!--{/image}-->
       <a href="<!--{url}-->">Attachment of
        <!--{type}--> (<!--{size}--> bytes)</a>
    <!--{/preview}-->
  <!--{/message}-->

=item $obj-E<gt>B<htmlRawText>($message, \%options)

Returns the plain text of the body.

=item $obj-E<gt>B<htmlSubject>($message, \%options)

Get the subject field from the C<$message>'s header, just a short-cut
for specifying L<htmlField(name)|HTML::FromMail::Message/"Other methods"> with C<subject>.

» example: using HTML::FromMail::Format::Magic

  <!--{subject}-->                # message subject
  <!--{field name => subject}-->  # part's subject
  <!--{field name => subject, from => MESSAGE}-->  # message subject

=item $obj-E<gt>B<htmlifier>($mime_type)

Returns the code reference for a routine which can create html
for the objects of the specified C<$mime_type>.  The type may be a (smartly
overloaded) MIME::Type object. The behaviour can be changed with
the C<htmlifiers> setting.

=item $obj-E<gt>B<lookup>($label, \%options)

Inherited, see L<HTML::FromMail::Page/"Other methods">

=item $obj-E<gt>B<plain2html>(STRING)

Inherited, see L<HTML::FromMail::Object/"Other methods">

=item $obj-E<gt>B<previewer>($mime_type)

Returns the code reference for a routine which can create a preview
for the objects of the specified C<$mime_type>.  The type may be a (smartly
overloaded) MIME::Type object.  The behaviour can be changed with
the C<previewers> setting.

=back

=head1 DETAILS

=head2 Settings

You can specify the following settings in L<HTML::FromMail::new(settings)|HTML::FromMail/"Constructors">
for topic C<message>:

=head3 disposition CODE

Message parts have to be displayed.  There are a few ways to do that: by
C<inline>, C<attach>, and C<preview>.  In the first case, the text of the
part is inserted in the main page, in the other two as link to an external
file.  The latter is creating a small preview of the attachement.

The message may provide an indication of the way the part should be
displayed in the C<Content-Disposition> field. For many reasons, an
exception will be made... for instance, binary messages will never be
inlined.  You can create your own code reference to change the behavior
of the default algorithm.

=head4 » Example: of own disposition rules

  my $f = HTML::FromMail->new(
     settings => {
        message => { disposition => \&my_disposer },
     },
  );

  sub my_disposer($$$$$)
  {   my ($obj, $message, $part, $suggestion, $args) = @_;
      $suggestion eq 'inline' && $part->size > 10_000 ? 'attach' : $suggestion;
  }

=head3 previewers \@pairs

For some kinds of message parts, previews can be produced.  This ordered
list of PAIRS contains mime type with code reference combinations, each
describing such a production.  The specified items are added before the
default list of preview generators.  An C<undef> as code reference will
cause the default preview producer to be disabled.

Method L<previewer()|HTML::FromMail::Message/"Other methods"> is called when a previewer for a certain content
type has to be looked-up.  The default previewers are defined (and
implemented) in HTML::FromMail::Default::Previewers.

=head3 htmlifiers \@pairs

Some kinds of information can be translated into HTML.  When a data
type defines such a translation, it may be inlined (see L<htmlInline()|HTML::FromMail::Message/"Other methods">),
where in other cases it will get attached.  The usage is the same as
for the C<previewers> option.

Method L<htmlifier()|HTML::FromMail::Message/"Other methods"> is called when a htmlifier for a certain content
type has to be looked-up.  The default htmlifiers are defined (and
implemented) in HTML::FromMail::Default::HTMLifiers.

=head4 » Example: use own converters

  my @prevs = (
     'text/postscript' => \&prepost,
     'image'           => \&imagemagick,
  );

  my @html  = (
     'text/html'       => \&strip_html,
     'text/plain'      => \&plain2html,
  );

  my $f = HTML::FromMail->new(
      settings => {
         message => {
            previewers  => \@prevs,
            htmlifiers  => \@html,
            disposition => \&my_disposer,
         },
      },
   );

  sub prepost($$$$$)
  {   my ($page, $message, $part, $attach, $args) = @_;
      # args contains extra info from template
      # returns a hash of info which is used in a
      # preview block (see htmlPreview())
  }

=head1 DIAGNOSTICS

=over 4

=item Warning: No field name specified in $template

Cast by C<htmlField()>

=item Error: foreachPart not used within part

Cast by C<htmlForeachPart()>

=item Error: foreachPart outside multipart

Cast by C<htmlForeachPart()>

=item Error: use of 'addresses' outside field container

Cast by C<htmlAddresses()>

=item Error: use of 'body' outside field container

Cast by C<htmlBody()>

=item Error: use of 'name' outside field container

Cast by C<htmlName()>

=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.

