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
pluginsplugins => [ 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',
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
},
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 as a value. 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.
triggertrigger => [ 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).
subjectsubject => '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
mailermailer => '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_keyok_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_redirectok_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:
http://rt.cpan.org/NoAuth/Bugs.html?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.
