=encoding utf8

=head1 NAME

HTML::FromMail - base-class for the HTML producers

=head1 INHERITANCE

 HTML::FromMail
   is a Mail::Reporter

=head1 SYNOPSIS

  use Mail::Message  ();
  use HTML::FromMail ();

  my $msg    = Mail::Message->read(\*STDIN);
  my $fmt    = HTML::FromMail->new(templates => 'templ');
  my $output = $fmt->export($msg, output => $tempdir);

  # See full example in examples/msg2html.pl

=head1 DESCRIPTION

This module is designed to put e-mail related data on web-pages.
This could be used to create web-mail clients.

B<This is a maintenance release for the old interface>.  Read
F<https://https://github.com/markov2/perl5-Mail-Box/wiki/> how
to move to towards version 4.

=head2 Status

=over 4

=item *

You can already produce pages for messages in a powerfull and
configurable way. Supported are: selection of header fields to be
included, inline display of the message's data, attachments, previews
for attachments, multiparts and rfc822 encapsulated messages. See
the example script, F<examples/msg2html.pl>

=item *

Pluggable data inliners, for instance a converter for plain text to html
to be inlined in the display of a page.  The same for HTML.

=item *

Pluggable preview generator: the first view lines (or a small version
of the image) can be included on the main display of the message.

=item *

The documentation is not sufficient in amount and organization.  But
there is some.

=item *

Email addresses in the header are not yet formatted as links.

=back

=head2 Plans

There are many extensions planned; but I have no time to implement
them.

=over 4

=item *

Fields should be treated smartly: links for addresses found in the header,
character encodings, etc.

=item *

Generation of pages showing folders with or without threads.

=item *

More documentation and examples, intergrated with the Mail::Box
documentation.

=item *

Production of previews must be made "lazy".  More default previewers, like
MSWord and PDF.

=item *

Support for other template systems.  The producer of message display data
is disconnected from the template system used, so this may not be too
hard.

=back

=head1 METHODS

=head2 Constructors

=over 4

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

Z<>

 -Option   --Default
  formatter  HTML::FromMail::Format::OODoc
  producers  <some basic items>
  settings   +{}
  templates  '.'

=over 2

=item formatter => CLASS|$formatter|HASH

The formatter which is used to process the template files which produce
the output.

You can specify a CLASS, a C<$formatter> object, or a HASH with options for
a L<HTML::FromMail::Format::OODoc|HTML::FromMail::Format::OODoc> object which will be created for you.

=item producers => \%map

The producer list describes which set of formatting commands are
applicable to certain objects when producing HTML.  The C<%map>
links external class names (usually implemented in Mail::Box) to
sub-classes of this object.  You may modify the default list
using L<producer()|HTML::FromMail/"Other methods">.  Read more in L</Producers>.

=item settings => \%map

Each producer has defaults for formatting flexability.  For instance,
sometimes alternatives are available for creating certain pieces
of HTML.  This option adds/modifies the settings for a certain group
of producers, but influences the formatters their behavior as well.
Read more in L</Settings>.

=item templates => $directory

The location where the template files can be found.  It is used as
base for relative names.

=back

=back

=head2 Attributes

=over 4

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

Returns the selected formatter object.

=back

=head2 Other methods

=over 4

=item $obj-E<gt>B<expandFiles>($directory|$file|\@files)

Returns a LIST with all filenames which are included in the C<$directory>
specified or the ARRAY.  If only one C<$file> is specified, then that
will be returned.

=item $obj-E<gt>B<export>($object, %options)

Produce the HTML output of the C<$object>.

 -Option--Default
  output  <required>
  use     undef

=over 2

=item output => $directory|$filename

The C<$directory> where the processed templates for the object are written
to.  It is only permitted to supply a single C<$filename> when the template
specifies a single filename as well.

=item use => \@files

Directory C<new(templates)> defines the location of all template C<@files>.  In
that directory, you have sub-directories for each kind of object which
can be formatted sorted on C<topic>.

for instance, C<templates> contains C</home/me/templates> and the object
is a L<Mail::Message> which is handled by L<HTML::FromMail::Message|HTML::FromMail::Message>
which has topic C<message>.  This directory plus the topic result in
the directory path C</home/me/templates/message/>.  By default, all
the files found in there get formatted.  However, when the C<use>
option is provided, only the specified files are taken.  If that filename
is related, it is relative to the C<templates> direcory.  If the filename
is absolute (starts with a slash), that name is used.

=back

=item $obj-E<gt>B<producer>( (CLASS|$object), [$producer] )

The C<CLASS> object, for instance a Mail::Message, is handled by the HTML
C<$producer> class.  When an C<$object> is specified, the C<CLASS> of that object
will be used.  The producer returned is the best fit with respect of
the inheritance relations.  C<undef> is returned when no producer was found.

Without producer as parameter, the actual producer for the C<CLASS> is
returned.  In this case, the producer class will be compiled for you,
if that hasn't be done before.

» example: 

  use HTML::FromMail;
  my $converter = HTML::FromMail->new;
  print $converter->producer("Mail::Message");

  print $converter->producer($msg);

=item $obj-E<gt>B<settings>( ($producer|$topic), [HASH|LIST] )

Returns a C<HASH> which contains the differences from the default for
producers of a certain C<$topic>, or the topic of the specified C<$producer>.
With C<HASH>, all settings will be replaced by that value as new set.

It may be easier to use L<new(settings)|HTML::FromMail/"Constructors"> or add the information to
the content of your templates.

=item $obj-E<gt>B<templates>( [$producer|$topic] )

Returns the location of the templates.  When a C<$topic> is specified,
that is added to the templates path.  With a C<$producer>, that is object is used
to get the topic.

=back

=head1 DETAILS

=head2 Producers

Producers are sets of methods which can be used to produce HTML for
a specific object.  For instance, the L<HTML::FromMail::Message|HTML::FromMail::Message> produces
output for Mail::Message objects.  You can add and overrule producers via
L<new(producers)|HTML::FromMail/"Constructors"> and L<producer()|HTML::FromMail/"Other methods">.

On the moment, the following producers are defined.  When marked with
a C<(*)>, the implementation is not yet finished.

  Mail::Message            HTML::FromMail::Message
  Mail::Message::Head      HTML::FromMail::Head
  Mail::Message::Field     HTML::FromMail::Field
  Mail::Message::Body      HTML::FromMail::Body      *
  Mail::Box                HTML::FromMail::Box       *
  Mail::Box::Thread::Node  HTML::FromMail::Thread    *

=head2 Settings

Each producer has one single topic, but there may be multiple alternatives
for one topic.  The topic is configurable with
L<HTML::FromMail::Object::new(topic)|HTML::FromMail::Object/"Constructors">.

For each item which is converted to HTML, one of the producers for that
item is created.  The topic of the producer is used to select a group of
settings to be used as changes on the defaults.  These values are used
for the formatter as well as the producer when formatting that topic.

An example should clarify things a little:

  my $fmt = HTML::FromMail->new(
     settings => {
        message => {
           previewers  => \@my_prevs,
           disposition => sub { 'attach' },
        },
        field   => { },
     },
  );
  print $fmt->export($msg, output => '/tmp/x');

For settings available for messages, see L<HTML::FromMail::Message/Settings>.

=head1 DIAGNOSTICS

=over 4

=item Warning: Cannot find $dir/file

Cast by C<expandFiles()>

=item Error: Cannot find template file or directory $topic in $directory.

The templates directory (see L<new(templates)|HTML::FromMail/"Constructors">) does not contain a template
for the specified topic (see L<HTML::FromMail::Object::new(topic)|HTML::FromMail::Object/"Constructors">).
Cast by C<templates()>

=item Error: Cannot read from directory $thing: $!

Cast by C<expandFiles()>

=item Error: Cannot use $producer for $class: $@

The specified producer (see L<new(producers)|HTML::FromMail/"Constructors">) does not exist or produces
compilation errors.  The problem is displayed.
Cast by C<producer()>

=item Error: Formatter $class can not be used: $@

Cast by C<new()>

=item Error: Formatter $class could not be instantiated

Cast by C<new()>

=item Error: No output directory or file specified.

Cast by C<export()>

=item Error: No producer for $class objects.

Cast by C<export()>

=item Warning: No templates for $topic objects.

Cast by C<export()>

=item Warning: No templates found in $templates directory

Cast by C<export()>

=item Warning: Skipping $full, which is neither file or directory.

Cast by C<expandFiles()>

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

