NAME

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

INHERITANCE

 HTML::FromMail
   is a Mail::Reporter

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

DESCRIPTION

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

Status

• 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, examples/msg2html.pl

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

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

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

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

Plans

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

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

• Generation of pages showing folders with or without threads.

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

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

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

METHODS

Constructors

HTML::FromMail->new(OPTIONS)

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

formatter => CLASS|OBJECT|HASH

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 HTML::FromMail::Format::OODoc object which will be created for you.

producers => HASH

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 Mail::Box) to sub-classes of this object. You may modify the default list using producer(). Read more in "Producers".

settings => HASH

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 "Settings".

templates => DIRECTORY

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

Attributes

$obj->formatter()

Returns the selected formatter object.

$obj->producer( (CLASS|OBJECT) [, HTML_PRODUCER] )

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

example:

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

 print $converter->producer($msg);

$obj->settings( (PRODUCER|TOPIC) [,HASH|LIST] )

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 new(settings) or add the information to the content of your templates.

$obj->templates( [PRODUCER|TOPIC] )

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.

Export

$obj->export(OBJECT, OPTIONS)

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

 -Option--Default
  output  <required>
  use     undef

output => DIRECTORY|FILENAME

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.

use => ARRAY-OF-FILENAMES

Directoy 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 topic.

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

Other methods

$obj->expandFiles(DIRECTORY|FILENAME|ARRAY-OF-FILENAMES)

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.

DETAILS

Producers

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

On the moment, the following producers are defined. When marked with a (*), 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    *

Settings

Each producer has one single topic, but there may be multiple alternatives for one topic. The topic is configurable with HTML::FromMail::Object::new(topic).

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 "Settings" in HTML::FromMail::Message.

DIAGNOSTICS

Warning: Cannot find $dir/file

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

The templates directory (see new(templates)) does not contain a template for the specified topic (see HTML::FromMail::Object::new(topic)).

Error: Cannot read from directory $thing: $!

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

The specified producer (see new(producers)) does not exist or produces compilation errors. The problem is displayed.

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

Error: Formatter $class could not be instantiated

Error: No output directory or file specified.

Error: No producer for $class objects.

Warning: No templates for $topic objects.

Warning: No templates found in $templates directory

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

SEE ALSO

This module is part of HTML-FromMail distribution version 0.12, built on January 29, 2018. Website: http://perl.overmeer.net/CPAN/

LICENSE

Copyrights 2003-2018 by [Mark Overmeer <markov@cpan.org>]. 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 http://dev.perl.org/licenses/

cpanm HTML::FromMail

perl -MCPAN -e shell
install HTML::FromMail