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.

To install App::ZofCMS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::ZofCMS

CPAN shell

perl -MCPAN -e shell
install App::ZofCMS

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

SYNOPSIS

DESCRIPTION

FIRST-LEVEL ZofCMS TEMPLATE KEYS

plugins

plug_htmlmailer

to

cc

bcc

template

template_params

subject

from

template_dir

precode

mime_lite_params

html_template_object

attach