The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
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.