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

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>

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

    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 => {
            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  => \'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 => '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 => '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 => [ 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 => '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  => '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  => '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 => '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.

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

Patches from Jon Smith aka jonsmith1982

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

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

    perldoc App::ZofCMS::Plugin::FormMailer

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS-Plugin-FormMailer

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS-Plugin-FormMailer

* CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS-Plugin-FormMailer

* Search CPAN

http://search.cpan.org/dist/App-ZofCMS-Plugin-FormMailer

Copyright 2008 'Zoffix, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.