NAME

App::ZofCMS::Plugin::FormMailer - plugin for e-mailing forms

SYNOPSIS

In your Main Config File or ZofCMS Template file:

    plug_form_mailer => {
        trigger => [ qw/ d   plug_form_checker_ok / ],
        subject => 'Zen of Design Account Request',
        to      => 'foo@bar.com',
        mailer  => 'testfile',
        format  => <<'END',
The following account request has been submitted:
First name: {:{first_name}:}
Time:       {:[time]:}
Host:       {:[host]:}
END
    },

In your HTML::Template file:

    <tmpl_if name="plug_form_mailer_ok">
        <p>Your request has been successfully submitted.</p>
    <tmpl_else>
        <form action="" method="POST" id="form_account_request">
            <input type="text" name="first_name">
            <input type="submit" value="Request account">
        </form>
    </tmpl_if>

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to easily e-mail query parameters.

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

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

    plugins => [ qw/FormMailer/ ],

You need to add the plugin in the list of plugins to execute. Generally you'd want to check query parameters first with, e.g. App::ZofCMS::Plugin::FormChecker. If that's what you're doing then make sure to set the correct priority:

    plugins => [ { FormChecker => 1000 }, { FormMailer => 2000 }, ],

plug_form_mailer

        plug_form_mailer => {
            trigger     => [ qw/ d   plug_form_checker_ok / ],
            subject     => 'Zen of Design Account Request',
            to          => 'foo@bar.com',
            from        => 'Me <me@mymail.com>',
            ok_redirect => 'http://google.com/',
            mailer      => 'testfile',
            format      => <<'END',
    The following account request has been submitted:
    First name: {:{first_name}:}
    Time:       {:[time]:}
    Host:       {:[host]:}
    END
        },


    plug_form_mailer => sub {
        my ( $t, $q, $config ) = @_;
        return {
            # set plugin config here
        };
    },

The plugin will not run unless plug_form_mailer first-level key is set in either Main Config File or ZofCMS Template file. The plug_form_mailer first-level key takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_form_mailer 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. Keys that are set in both Main Config File and ZofCMS Template file will take on their values from ZofCMS Template. Possible keys/values are as follows:

format

        format  => \'file_name_relative_to_templates',

        # or

        format  => <<'END',
    The following account request has been submitted:
    First name: {:{first_name}:}
    Time:       {:[time]:}
    Host:       {:[host]:}
    END
        },

Mandatory. The format key takes a scalar or a scalarref as a value. When the value is a scalarref then it is interpreted as a file name relative to the "templates" dir; this file will be read and its contents will serve as a value for format argument (i.e. same as specifying contents of the file to format as scalar value). If an error occured when opening the file, the plugin will set the plug_form_mailer_error in the {t} special key to the error message and will set the format to an empty string.

When value is a scalar, it represents the body of the e-mail that plugin will send. In this scalar you can use special "tags" that will be replaced with data. The tag format is {:{TAG_NAME}:}. Tag name cannot contain a closing curly bracket (}) in it. Two special tags are {:[time]:} and {:[host]:} (note a slightly different tag format) that will be replaced with current time and user's host respectively.

to

    to => 'foo@bar.com',
    to => [ qw/foo@bar.com  foo2@bar.com/ ],

Mandatory. Specifies the e-mail address(es) to which to send the e-mails. Takes either an arrayref or a scalar as a value. Specifying a scalar is the same as specifying an arrayref with just that scalar in it. Each element of that arrayref must be a valid e-mail address.

from

    from => 'Me <me@mymail.com>',

Optional. Specifies the "From" header to use. Note: in my experience, setting the "From" to some funky address would sometimes make the server refuse to send mail; if your mail is not being sent, try to leave the from header at the default.By default: not specified, thus the "From" will be whatever your server has in stock.

trigger

    trigger => [ qw/ d   plug_form_checker_ok / ],

Optional. The plugin will not do anything until its "trigger" is set to a true value. The trigger argument takes an arrayref as a value. Each element of this arrayref represent a hashref key in which to find the trigger. In other words, if trigger is set to [ qw/ d plug_form_checker_ok / ] then the plugin will check if the plug_form_checker_ok key inside {d} ZofCMS Template special key is set to a true value. You can nest as deep as you want, however only hashref keys are supported. Defaults to: [ qw/d plug_form_mailer/ ] (plug_form_mailer key inside d first-level key).

subject

    subject => 'Zen of Design Account Request',

Optional. The subject key takes a scalar as a value. This value will be the "Subject" line in the e-mails sent by the plugin. Defaults to: FormMailer

mailer

    mailer  => 'testfile',

Optional. Specfies the "mailer" to use for e-mailing. See DESCRIPTION of Mail::Mailer for possible values and their meanings. If this value is set to a false value (or not specified at all) then plugin will try all available mailers until one succeeds. Specifying testfile as a mailer will cause the plugin to "e-mail" data into mailer.testfile file in the same directory as your index.pl file.

ok_key

    ok_key  => 't',

Optional. After sending an e-mail the plugin will set key plug_form_mailer_ok in one of the first-level keys of ZofCMS Template hashref. The ok_key specifies the name of that first-level key. Note that that key's must value must be a hashref. Defaults to: t (thus you can readily use the <tmpl_if name="plug_form_mailer_ok"> to check for success (or rather display some messages).

ok_redirect

    ok_redirect => 'http://google.com/',

Optional. Takes a string with a URL in it. When specified the plugin will redirect the user to the page specified in ok_redirect after sending the mail. By default is not specified.

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.

cpanm App::ZofCMS

perl -MCPAN -e shell
install App::ZofCMS