/ 
HTML-FromMail-3.01
River stage zero No dependents
/ HTML::FromMail

NAME

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

INHERITANCE

HTML::FromMail
  is a Mail::Reporter

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

DESCRIPTION

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

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

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

$class->new(%options)

-Option   --Default
 formatter  HTML::FromMail::Format::OODoc
 producers  <some basic items>
 settings   +{}
 templates  '.'
formatter => CLASS|$formatter|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 => \%map

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

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

Other methods

$obj->expandFiles($directory|$file|\@files)

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

$obj->export($object, %options)

Produce the HTML output of the $object.

-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 => \@files

Directory new(templates) defines the location of all template @files. In that directory, 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.

$obj->producer( (CLASS|$object), [$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.

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

Cast by expandFiles()

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)). Cast by templates()

Error: Cannot read from directory $thing: $!

Cast by expandFiles()

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

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

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

Cast by new()

Error: Formatter $class could not be instantiated

Cast by new()

Error: No output directory or file specified.

Cast by export()

Error: No producer for $class objects.

Cast by export()

Warning: No templates for $topic objects.

Cast by export()

Warning: No templates found in $templates directory

Cast by export()

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

Cast by expandFiles()

SEE ALSO

This module is part of HTML-FromMail version 3.01, built on November 21, 2025. Website: http://perl.overmeer.net/CPAN/

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.