/ 
App-ZofCMS-1.001003
River stage one • 1 direct dependent • 1 total dependent
/ App::ZofCMS::Plugin::HTMLMailer

NAME

App::ZofCMS::Plugin::HTMLMailer - ZofCMS plugin for sending HTML email

SYNOPSIS

plugins => [
    { HTMLMailer => 2000, },
],

plug_htmlmailer => {
    to          => 'cpan@zoffix.com',
    template    => 'email-template.tmpl',

    # everything below is optional
    template_params => [
        foo => 'bar',
        baz => 'ber',
    ],
    subject         => 'Test Subject',
    from            => 'Zoffix Znet <any.mail@fake.com>',
    cc              => 'foo@bar.com',
    bcc             => [ 'agent42@fbi.com', 'foo@bar2.com' ],
    template_dir    => 'mail-templates',
    precode         => sub {
        my ( $t, $q, $config, $plug_conf ) = @_;
        # run some code
    },
    mime_lite_params => [
        'smtp',
        'srvmail',
        Auth   => [ 'FOOBAR/foos', 'p4ss' ],
    ],
    html_template_object => HTML::Template->new(
        filename            => 'mail-templates/email-template.tmpl',
        die_on_bad_params   => 0,
    ),
    attach => [
        Type     => 'image/gif',
        Path     => 'aaa000123.gif',
        Filename => 'logo.gif',
        Disposition => 'attachment'
    ],
},

DESCRIPTION

The module is a ZofCMS plugin that provides means to easily create an email from an HTML::Template template, fill it, and email it as an HTML email.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

FIRST-LEVEL ZofCMS TEMPLATE KEYS

plugins

plugins => [ qw/HTMLMailer/ ],

First and obvious, you need to stick HTMLMailer in the list of your plugins.

plug_htmlmailer

plug_htmlmailer => {
    to          => 'cpan@zoffix.com',
    template    => 'email-template.tmpl',

    # everything below is optional
    template_params => [
        foo => 'bar',
        baz => 'ber',
    ],
    subject         => 'Test Subject',
    from            => 'Zoffix Znet <any.mail@fake.com>',
    cc              => 'foo@bar.com',
    bcc             => [ 'agent42@fbi.com', 'foo@bar2.com' ],
    template_dir    => 'mail-templates',
    precode         => sub {
        my ( $t, $q, $config, $plug_conf ) = @_;
        # run some code
    },
    mime_lite_params => [
        'smtp',
        'srvmail',
        Auth   => [ 'FOOBAR/foos', 'p4ss' ],
    ],
    html_template_object => HTML::Template->new(
        filename            => 'mail-templates/email-template.tmpl',
        die_on_bad_params   => 0,
    ),
},

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_htmlmailer as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:

to

plug_htmlmailer => {
    to => 'foo@bar.com',
...

plug_htmlmailer => {
    to => [ 'foo@bar.com', 'ber@bar.com', ],
...

plug_htmlmailer => {
    to => sub {
        my ( $t, $q, $config ) = @_;
        return [ 'foo@bar.com', 'ber@bar.com', ];
    }
...

Mandatory. Specifies the email address(es) to which to send the email. Takes a scalar, an arrayref or a subref as a value. If a scalar is specified, plugin will create a single-item arrayref with it; if an arrayref is specified, each of its items will be interpreted as an email address to which to send email. If a subref is specified, its return value will be assigned to the to key and its @_ array will contain: $t, $q, $config (in that order) where $t is ZofCMS Template hashref, $q is the query parameter hashref and $config is the App::ZofCMS::Config object. Default: if the to key is not defined (or the subref to which it's set returns undef) then the plugin will stop further processing.

cc

plug_htmlmailer => {
    cc => 'foo@bar.com',
...

plug_htmlmailer => {
    cc => [ 'foo@bar.com', 'ber@bar.com', ],
...

plug_htmlmailer => {
    cc => sub {
        my ( $t, $q, $config ) = @_;
        return [ 'foo@bar.com', 'ber@bar.com', ];
    }
...

Optional. Specifies "Cc" (carbon copy) email address(es) to which to send the email. Takes a scalar, an arrayref or a subref as a value. If a scalar is specified, plugin will create a single-item arrayref with it; if an arrayref is specified, each of its items will be interpreted as an email address to which to send email. If a subref is specified, its return value will be assigned to the cc key and its @_ array will contain: $t, $q, $config (in that order) where $t is ZofCMS Template hashref, $q is the query parameter hashref and $config is the App::ZofCMS::Config object. Default: not specified

bcc

plug_htmlmailer => {
    bcc => 'foo@bar.com',
...

plug_htmlmailer => {
    bcc => [ 'foo@bar.com', 'ber@bar.com', ],
...

plug_htmlmailer => {
    bcc => sub {
        my ( $t, $q, $config ) = @_;
        return [ 'foo@bar.com', 'ber@bar.com', ];
    }
...

Optional. Specifies "Bcc" (blind carbon copy) email address(es) to which to send the email. Takes a scalar, an arrayref or a subref as a value. If a scalar is specified, plugin will create a single-item arrayref with it; if an arrayref is specified, each of its items will be interpreted as an email address to which to send email. If a subref is specified, its return value will be assigned to the bcc key and its @_ array will contain: $t, $q, $config (in that order) where $t is ZofCMS Template hashref, $q is the query parameter hashref and $config is the App::ZofCMS::Config object. Default: not specified

template

plug_htmlmailer => {
    template => 'email-template.tmpl',
...

Mandatory, unless html_template_object (see below) is specified. Takes a scalar as a value that represents the location of the HTML::Template template to use as the body of your email. If relative path is specified, it will be relative to the location of index.pl file. Note: if template_dir is specified, it will be prepended to whatever you specify here.

template_params

plug_htmlmailer => {
    template_params => [
        foo => 'bar',
        baz => 'ber',
    ],
...

plug_htmlmailer => {
    template_params => sub {
        my ( $t, $q, $config ) = @_:
        return [ foo => 'bar', ];
    }
...

Optional. Specifies key/value parameters for HTML::Template's param() method; this will be called on the HTML::Template template of your email body (specified by template argument). Takes an arrayref or a subref as a value. If subref is specified, its @_ will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is App::ZofCMS::Config object. The subref must return either an arrayref or an undef (or empty list), and that will be assigned to template_params as a true value. By default is not specified.

subject

plug_htmlmailer => {
    subject => 'Test Subject',
...

Optional. Takes a scalar as a value that specifies the subject line of your email. Default: empty string.

from

plug_htmlmailer => {
    from => 'Zoffix Znet <any.mail@fake.com>',
...

Optional. Takes a scalar as a value that specifies the From field for your email. If not specified, the plugin will simply not set the From argument in MIME::Lite's new() method (which is what this plugin uses under the hood). See MIME::Lite's docs for more description. By default is not specified.

template_dir

plug_htmlmailer => {
    template_dir => 'mail-templates',
...

Optional. Takes a scalar as a value. If specified, takes either an absolute or relative path to the directory that contains all your HTML::Template email templates (see template above for more info). If relative path is specified, it will be relative to the index.pl file. The purpose of this argument is to simply have a shortcut to save you the trouble of specifying the directory every time you use template. By default is not specified.

precode

plug_htmlmailer => {
    precode => sub {
        my ( $t, $q, $config, $plug_conf ) = @_;
        # run some code
    },
...

Optional. Takes a subref as a value. This is just an "insertion point", a place to run a piece of code if you really have to. The @_ of the subref will contain $t, $q, $config, and $plug_conf (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, $config is App::ZofCMS::Config object, and $plug_conf is the configuration hashref of this plugin (that is the plug_htmlmailer hashref). You can use $plug_conf to stick modified configuration arguments to the current run of this plugin (modifications will not be saved past current run stage). The subref will be executed after the to argument is processed, but before anything else is done. Note: if to is not set (or set to subref that returns undef) then the precode subref will NOT be executed at all. By default is not specified.

mime_lite_params

plug_htmlmailer => {
    mime_lite_params => [
        'smtp',
        'srvmail',
        Auth   => [ 'FOOBAR/foos', 'p4ss' ],
    ],
...

Optional. Takes an arrayref as a value. If specified, the arrayref will be directly dereferenced into MIME::Lite->send(). Here you can set any special send arguments you need; see MIME::Lite docs for more info. By default is not specified.

html_template_object

plug_htmlmailer => {
    html_template_object => HTML::Template->new(
        filename            => 'mail-templates/email-template.tmpl',
        die_on_bad_params   => 0,
    ),
...

Optional. Takes an HTML::Template object (or something that behaves like one). If specified, the template and template_dir arguments will be ignored and the object you specify will be used instead. Note: the default HTML::Template object (used when html_template_object is not specified) has die_on_bad_params argument set to a false value; using html_template_object you can change that. By default is not specified.

attach

plug_htmlmailer => {
    attach => [
        Type     => 'image/gif',
        Path     => 'aaa000123.gif',
        Filename => 'logo.gif',
        Disposition => 'attachment'
    ],
...

plug_htmlmailer => {
    attach => [
        [
            Type     => 'image/gif',
            Path     => 'aaa000123.gif',
            Filename => 'logo1.gif',
            Disposition => 'attachment'
        ],
        [
            Type     => 'TEXT',
            Data     => "Here's the GIF file you wanted"
        ],
    ],
...

plug_htmlmailer => {
    attach => sub {
        my ( $t, $q, $config ) = @_;
        return [
            Type     => 'TEXT',
            Data     => "Here's the GIF file you wanted"
        ];
    }
...

Optional. Provides access to the attach method of MIME::Lite, e.g. gives you an ability to attach files to your emails. Takes an arrayref, an arrayref of arrayrefs, or a subref as a value. If an arrayref is specified, plugin will create a single-item arrayref with it (so it'll be nested); if an arrayref of arrayrefs is specified, each of its arrayrefs will be interpreted as a list of arguments to pass to attach method. If a subref is specified, its return value will be assigned to the attach key and its @_ array will contain: $t, $q, $config (in that order) where $t is ZofCMS Template hashref, $q is the query parameter hashref and $config is the App::ZofCMS::Config object. Default: not specified

OUTPUT

This plugin doesn't produce any output and doesn't set any keys.

A WARNING ABOUT ERRORS

This plugin doesn't have any error handling. The behaviour is completely undefined in cases of: invalid email addresses, improper or insufficient mime_lite_params values, no from set, etc. For example, on my system, not specifying any mime_lite_params makes it look like plugin is not running at all. If things go awry: copy the plugin's code into your projects dir (zofcms_helper --nocore --site YOUR_PROJECT --plugins HTMLMailer) and mess around with code to see what's wrong (the code would be located in YOUR_PROJECT_site/App/ZofCMS/Plugin/HTMLMailer.pm)

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.