The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
=head1 NAME

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

=head1 INHERITANCE

 HTML::FromMail
   is a Mail::Reporter

=head1 SYNOPSIS

 use Mail::Message;   # part of Mail::Box
 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, L<HTML::FromMail|HTML::FromMail>, is designed to put e-mail related data
on web-pages.  This could be used to create web-mail clients.

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

=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

HTML::FromMail-E<gt>B<new>(OPTIONS)

=over 4

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

. formatter => CLASS|OBJECT|HASH

=over 4

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

You can specify a CLASS, a 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.

=back

. producers => HASH

=over 4

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

=back

. settings => HASH

=over 4

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 influence the formatters behavior as well.
Read more in L</Settings>.

=back

. templates => DIRECTORY

=over 4

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

=back

=back

=head2 Attributes

$obj-E<gt>B<formatter>

=over 4

Returns the selected formatter object.

=back

$obj-E<gt>B<producer>((CLASS|OBJECT) [, HTML_PRODUCER])

=over 4

The CLASS object, for instance a Mail::Message, is handled by the
HTML_PRODUCER class.  When an OBJECT is specified, the 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 CLASS is
returned.  In this case, the producer class will be compiled for you,
if that hasn't be done before.

I<Example:> 

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

 print $converter->producer($msg);

=back

$obj-E<gt>B<settings>((PRODUCER|TOPIC) [,HASH|LIST])

=over 4

Returns a hash which contains the differences from the default for
producers of a certain TOPIC, or the topic of the specified PRODUCER.
With 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.

=back

$obj-E<gt>B<templates>([PRODUCER|TOPIC])

=over 4

Returns the location of the templates.  When a TOPIC is specified,
that is added to the templates path.  With a PRODUCER, that is object is used
to get the topic.

=back

=head2 Export

$obj-E<gt>B<export>(OBJECT, OPTIONS)

=over 4

Produce the HTML output of the OBJECT, using the specified OPTIONS.

 Option--Default
 output  <required>
 use     undef

. output => DIRECTORY|FILENAME

=over 4

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

=back

. use => ARRAY-OF-FILENAMES

=over 4

Directoy C<new(templates)> defines the location of all template files.  In
that directort, 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

=back

=head2 Other methods

$obj-E<gt>B<expandFiles>(DIRECTORY|FILENAME|ARRAY-OF-FILENAMES)

=over 4

Returns a list with all filenames which are included in the DIRECTORY
specified or the ARRAY.  If only one FILENAME is specified, then that
will be returned.

=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/"Attributes">.

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/"METHODS">.

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

I<Warning:> Cannot find $dir/file

I<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/"METHODS">).

I<Error:> Cannot read from directory $thing: $!

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

I<Error:> Formatter $class can not be used: $@

I<Error:> Formatter $class could not be instantiated

I<Error:> No output directory or file specified.

I<Error:> No producer for $class objects.

I<Warning:> No templates for $topic objects.

I<Warning:> No templates found in $templates directory

I<Warning:> Skipping $full, which is neither file or directory.

=head1 SEE ALSO

This module is part of HTML-FromMail distribution version 0.11,
built on June 08, 2007. Website: F<http://perl.overmeer.net/html-from-mail/>

=head1 LICENSE

Copyrights 2003,2004,2007 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>