NAME

HTML::FromMail::Message - output a message as HTML

INHERITANCE

HTML::FromMail::Message
  is a HTML::FromMail::Page
  is a HTML::FromMail::Object
  is a Mail::Reporter

SYNOPSIS

DESCRIPTION

THIS MODULE IS UNDER CONSTRUCTION. However, a lot of things already work. Best take a look at the examples directory.

Extends "DESCRIPTION" in HTML::FromMail::Page.

METHODS

Extends "METHODS" in HTML::FromMail::Page.

Constructors

Extends "Constructors" in HTML::FromMail::Page.

$class->new(%options)

-Option  --Defined in            --Default
 settings  HTML::FromMail::Object  {}
 topic     HTML::FromMail::Object  'message'

settings => \%map
topic => STRING

Attributes

Extends "Attributes" in HTML::FromMail::Page.

$obj->fields(): Returns the field text producing object.
$obj->header(): Returns the header text producting object.
$obj->settings( [TOPIC] ): Inherited, see "Attributes" in HTML::FromMail::Object
$obj->topic(): Inherited, see "Attributes" in HTML::FromMail::Object

Other methods

Extends "Other methods" in HTML::FromMail::Page.

$obj->createAttachment($message, $part, \%options)

Create an attachment file, and return a HASH with information about that file. Returns undef if creation fails.

This method is used by htmlAttach() and htmlPreview() to create an actual attachment file. It defines url, size and type tags for the template.

-Option--Default
 outdir  <required>

outdir => $directory: The name of the $directory where the external file will be produced.

$obj->disposition($message, $part, \%options)

Returns a string, which is either inline, attach, or preview, which indicates how the $part of the $message should be formatted. This can be changed with setting disposition.

$obj->htmlAddresses($message, \%options)

Produce data about addresses which are in the field. This method uses HTML::FromMail::Field::htmlAddresses() for that.

$obj->htmlAttach($message, \%options)

The attach container defines url, size and type tags for the template.

» example: using HTML::FromMail::Format::Magic

<!--{message}-->
  <!--{attach}-->
  <!--{/attach}-->
<!--{/message}-->

$obj->htmlBody($message, \%options)

Produce the body of a field. This tag can only be used inside a field container. See HTML::FromMail::Field::htmlBody() for the use and options.

$obj->htmlField($message, \%options)

Returns the field definition for the currently active message part. When the formatter sees this is a final token, then only the body of the field is returned (and the options of HTML::FromMail::Field::htmlBody() are accepted as well). Otherwise, the information about the field is captured to be used later.

-Option--Default
 decode  true if possible
 from    'PART'
 name    <required>

decode => BOOLEAN
from => 'PART'|'PARENT'|'MESSAGE': The source of this field: the currently active 'PART' (which may be the main message), the 'PARENT' of the active part (defaults to the message), or the main $message itself.
name => STRING

» example: using HTML::FromMail::Format::Magic

<!--{field name => To, content => REFOLD, wrap => 20}-->

<!--{field name => To}-->
   <!--{name capitals => WELLFORMED}-->
   <!--{body wrap => 30}-->
<!--{/field}-->

$obj->htmlForeachPart($message|$part, \%options)

Produces html for the parts of a multipart body. Each $part may be a multipart too. For each part, the message container code is applied recursively.

This container defines a part_number, and enables the use of the part tag.

» example: using HTML::FromMail::Format::Magic

<!--{message}-->
  <!--{multipart}-->
    <ul>
    <!--{foreachPart}-->
    <li>This is part <!--{part_number}-->
        <!--{part}-->
    </li>
    <!--{/foreachPart}-->
    </ul>
  <!--{/multipart}-->
<!--{message}-->

$obj->htmlHead($message, \%options)

Defines the fields of a header. The options are provided by HTML::FromMail::Head::fields().

» example: using HTML::FromMail::Format::Magic

# simple
<pre><!--{head}--></pre>

# complex
<table>
<!--{head remove_spam_groups => 0}-->
  <tr><td><!--{name}--></td>
      <td><!--{body}--></td></tr>
<!--{/head}-->
</table>

$obj->htmlInline($message, \%options)

-Option--Default
 type    ''

type => $mime_type: Selects the $mime_type which is handled by this singlepart block. Type comparison uses MIME::Type, so is smart.

» example: using HTML::FromMail::Format::Magic

<!--{message}-->
   <!--{inline type => text/html}-->
      <!--{html}-->
   <!--{/inline}-->
<!--{/message}-->

$obj->htmlMessage($message, \%options)

Encapsulated code which is producing the $message, which may be a multipart. You have to defined the message block when you use the part (see htmlPart()) tag. If you do not use that, you do not need this.

» example: using HTML::FromMail::Format::Magic

<!--{message}-->
  <!--{inline}-->This is an inlined singlepart<!--{/inline}-->
  <!--{attach}-->This is an attachment<!--{/attach}-->
  <!--{preview}-->An attachment with preview<!--{/preview}-->
  <!--{multipart}-->This is a multipart<!--{/multipart}-->
  <!--{nested}-->message/rfc822 encapsulated<!--{/nested}-->
<!--{/message}-->

$obj->htmlMultipart($message, \%options)

Encapsulates text to be produced when the $message(-part) is a multipart.

$obj->htmlName($message, \%options)

Produce the name of a field. This tag can only be used inside a field container. See HTML::FromMail::Field::htmlName() for the use and options.

$obj->htmlNested($message, \%options)

Contains text to be produced when the $message(-part) is a nested message; encapsulated in a message/rfc822.

$obj->htmlPart($message|$part, \%options)

Apply the $message container of the current $part on its data. See example in htmlForeachPart().

$obj->htmlPreview($message, \%options)

-Option--Default
 type    ''

type => $mime_type

Selects the $mime_type which are handled by this singlepart block. You can specify the types as defined by MIME::Type subroutine equals.

The preview container defines url, size and type tags for the template, which describe the attachment file. Besides, it preview defines a tag which tells whether the preview is made as html or as image. Within an html block, you will get an extra text which includes the actual html preview text.

The image container provides more tags: smallurl, smallwidth, smallheight, width, and height.

» example: using HTML::FromMail::Format::Magic

<!--{message}-->
  <!--{preview}-->
     <!--{html}-->
        <!--{text}-->
     <!--{/html}-->
     <!--{image}-->
        <img src="<!--{smallurl}-->"
         width="<!--{smallwidth}-->"
         height="<!--{smallheight}-->"><br />
         (real is <!--{width}--> x <!--{height}-->)
     <!--{/image}-->
     <a href="<!--{url}-->">Attachment of
      <!--{type}--> (<!--{size}--> bytes)</a>
  <!--{/preview}-->
<!--{/message}-->

$obj->htmlRawText($message, \%options)

Returns the plain text of the body.

$obj->htmlSubject($message, \%options)

Get the subject field from the $message's header, just a short-cut for specifying htmlField(name) with subject.

» example: using HTML::FromMail::Format::Magic

<!--{subject}-->                # message subject
<!--{field name => subject}-->  # part's subject
<!--{field name => subject, from => MESSAGE}-->  # message subject

$obj->htmlifier($mime_type)

Returns the code reference for a routine which can create html for the objects of the specified $mime_type. The type may be a (smartly overloaded) MIME::Type object. The behaviour can be changed with the htmlifiers setting.

$obj->lookup($label, \%options)

Inherited, see "Other methods" in HTML::FromMail::Page

$obj->plain2html(STRING)

Inherited, see "Other methods" in HTML::FromMail::Object

$obj->previewer($mime_type)

Returns the code reference for a routine which can create a preview for the objects of the specified $mime_type. The type may be a (smartly overloaded) MIME::Type object. The behaviour can be changed with the previewers setting.

DETAILS

Settings

You can specify the following settings in HTML::FromMail::new(settings) for topic message:

disposition CODE

Message parts have to be displayed. There are a few ways to do that: by inline, attach, and preview. In the first case, the text of the part is inserted in the main page, in the other two as link to an external file. The latter is creating a small preview of the attachement.

The message may provide an indication of the way the part should be displayed in the Content-Disposition field. For many reasons, an exception will be made... for instance, binary messages will never be inlined. You can create your own code reference to change the behavior of the default algorithm.

» Example: of own disposition rules

my $f = HTML::FromMail->new(
   settings => {
      message => { disposition => \&my_disposer },
   },
);

sub my_disposer($$$$$)
{   my ($obj, $message, $part, $suggestion, $args) = @_;
    $suggestion eq 'inline' && $part->size > 10_000 ? 'attach' : $suggestion;
}

previewers \@pairs

For some kinds of message parts, previews can be produced. This ordered list of PAIRS contains mime type with code reference combinations, each describing such a production. The specified items are added before the default list of preview generators. An undef as code reference will cause the default preview producer to be disabled.

Method previewer() is called when a previewer for a certain content type has to be looked-up. The default previewers are defined (and implemented) in HTML::FromMail::Default::Previewers.

htmlifiers \@pairs

Some kinds of information can be translated into HTML. When a data type defines such a translation, it may be inlined (see htmlInline()), where in other cases it will get attached. The usage is the same as for the previewers option.

Method htmlifier() is called when a htmlifier for a certain content type has to be looked-up. The default htmlifiers are defined (and implemented) in HTML::FromMail::Default::HTMLifiers.

» Example: use own converters

my @prevs = (
   'text/postscript' => \&prepost,
   'image'           => \&imagemagick,
);

my @html  = (
   'text/html'       => \&strip_html,
   'text/plain'      => \&plain2html,
);

my $f = HTML::FromMail->new(
    settings => {
       message => {
          previewers  => \@prevs,
          htmlifiers  => \@html,
          disposition => \&my_disposer,
       },
    },
 );

sub prepost($$$$$)
{   my ($page, $message, $part, $attach, $args) = @_;
    # args contains extra info from template
    # returns a hash of info which is used in a
    # preview block (see htmlPreview())
}

DIAGNOSTICS

Warning: No field name specified in $template: Cast by htmlField()
Error: foreachPart not used within part: Cast by htmlForeachPart()
Error: foreachPart outside multipart: Cast by htmlForeachPart()
Error: use of 'addresses' outside field container: Cast by htmlAddresses()
Error: use of 'body' outside field container: Cast by htmlBody()
Error: use of 'name' outside field container: Cast by htmlName()

LICENSE

For contributors see file ChangeLog.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install HTML::FromMail, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::FromMail

CPAN shell

perl -MCPAN -e shell
install HTML::FromMail

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Constructors

Attributes

Other methods

DETAILS

Settings

disposition CODE

» Example: of own disposition rules

previewers \@pairs

htmlifiers \@pairs

» Example: use own converters

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions