/ 
Template-Plugin-MIME-0.12
River stage zero No dependents
/ Template::Plugin::MIME

NAME

Template::Plugin::MIME - TemplateToolkit plugin providing a interface to MIME::Entity

VERSION

Version 0.12

SYNOPSIS

Use this plugin inside a template:

[% USE MIME %]

[% cid_of_image = MIME.attach('image.png') %]

<img src="cid:[% cid_of_image %]" />

METHODS FOR USE OUTSIDE TEMPLATE

attachments()

Returns all attached files.

use Template;
use Template::Plugin::MIME;

$template = Template->new;
$template->process(...);

$attachments = Template::Plugin::MIME->attachments($template);

merge($template, $mail)

This method merges a MIME::Entity documents together with all attached files in the template.

use Template;
use Template::Plugin::MIME;
use MIME::Entity;

$template = Template->new;
$template->process($infile, $stash, $outfile);

$entity = MIME::Entity->build(
    From => ...,
    To => ...,
    Subject => ...,
    Type => 'text/html',
    Path => $outfile,
);

Template::Plugin::MIME->merge($template, $entity);
    # $entity is now multipart/related

This methods invokes make_multipart('related') on $entity an then attaches all party to this entity with add_part() .

A more complex example is shown below. This can be used when you want seperate attachement dispositions together:

use Template;
use Template::Plugin::MIME;
use MIME::Entity;

$template = Template->new;
$template->process($ttfile, $stash, $outfile);

$inner_text = MIME::Entity->build(
    Top => 0, # this is very important!
    Type => 'text/plain',
    Path => $plainfile,
);

$inner_html = MIME::Entity->build(
    Top => 0, # this is very important!
    Type => 'text/html',
    Path => $outfile,
);

$outer = MIME::Entity->build(
    From => ...,
    To => ...,
    Subject => ...,
    Type => 'multipart/alternative',
);

# first, merges the attachments into the html entity:
Template::Plugin::MIME->merge($template, $inner_html);
    # $inner_html is now multipart/related

# seconds merges the alternative into the root entity:
$outer->add_part($inner_text);
$outer->add_part($inner_html);

The advantage is, the root entity considers of two alternative: a plain text and a html variant. the html variant is a multipart too, with related content (images, ...) attached.

And a total complex example shows how to use mixed content:

use Template;
use Template::Plugin::MIME;
use MIME::Entity;

$template = Template->new;
$template->process($ttfile, $stash, $outfile);

$inner_text = MIME::Entity->build(
    Top => 0, # this is very important!
    Type => 'text/plain',
    Path => $plainfile,
);

$inner_html = MIME::Entity->build(
    Top => 0, # this is very important!
    Type => 'text/html',
    Path => $outfile,
);

$outer = MIME::Entity->build(
    Top => 0, # this is very important!
    Type => 'multipart/alternative',
);

$entity = MIME::Entity->build(
    From => ...,
    To => ...,
    Subject => ...,
    Type => 'multipart/mixed',
);

# first, merge the attachments into the html entity:
Template::Plugin::MIME->merge($template, $inner_html);
    # $inner_html is now multipart/related

# second, merge the alternative into the outer entity:
$outer->add_part($inner_text);
$outer->add_part($inner_html);

# third, merge all parts together the root entity
$entity->add_part($outer);
$entity->add_part(Path => 'invoice.pdf', Type => 'application/pdf', Filename => 'Your Invoice.pdf');

The mime structue is now

(root) multipart/mixed
|-> multipart/alternative
|   |-> multipart/related
|   |   |-> text/html
|   |   `-> image/png
|   `-> text/plain
`-> application/pdf

FUNCTIONS FOR USE INSIDE TEMPLATE

attach($path [, %options] )

This method attaches a file and returns a Content-Id for use within html content, for example.

[% USE MIME %]

[% signature_cid = MIME.attach("signature.png") %]

<img src="cid:[% signature_cid %]" />

The paramhash %options is equivalent to the build class/instance method in MIME::Entity. The following options are overridden in order to work with related content:

  • Path is equivalent to $path

  • Id is the content-id, automatically generated.

  • Encoding is forced to Base64.

  • Type is the content type (but see below for more information)

  • Top is 0, since an attachment is not a top-level entity.

All other options are passed through.

Obtaining Content-Type

If the Options Type is set, this will be used regardless what the file is really is.

If File::LibMagic is installed on your system, checktype_filename will be invoked to obtain the mime-type. This method may fail and error messages are discarded for now.

If all fails, the mime-type "application/octet-stream" is used.

AUTHOR

David Zurborg, <david at fakenet.eu>

BUGS

Please report any bugs or feature requests to bug-template-plugin-mime at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-MIME. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Template::Plugin::MIME

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2013 David Zurborg, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the ISC license.