Mark Overmeer > HTML-FromMail-0.11 > HTML::FromMail

Download:
HTML-FromMail-0.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.11   Source  

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

Plans

There are many extensions planned.

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.11, built on June 08, 2007. Website: http://perl.overmeer.net/html-from-mail/

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 http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: