/ 
App-ZofCMS-Plugin-QuickNote-0.0103
/ App::ZofCMS::Plugin::QuickNote

NAME

App::ZofCMS::Plugin::QuickNote - drop-in "quicknote" form to email messages from your site

SYNOPSIS

In your ZofCMS template:

# basic:
quicknote => {
    to  => 'me@example.com',
},

# juicy
quicknote => {
    mailer      => 'testfile',
    to          => [ 'foo@example.com', 'bar@example.com'],
    subject     => 'Quicknote from example.com',
    must_name   => 1,
    must_email  => 1,
    must_message => 1,
    name_max    => 20,
    email_max   => 20,
    message_max => 1000,
    success     => 'Your message has been successfuly sent',
    format      => <<'END_FORMAT',
Quicknote from host {::{host}::} sent on {::{time}::}
Name: {::{name}::}
E-mail: {::{email}::}
Message:
{::{message}::}
END_FORMAT
},

In your HTML::Template template:

<tmpl_var name="quicknote">

DESCRIPTION

The module is a plugin for App::ZofCMS which provides means to easily drop-in a "quicknote" form which asks the user for his/her name, e-mail address and a message he or she wants to send. After checking all of the provided values plugin will e-mail the data which the visitor entered to the address which you specified.

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

HTML TEMPLATE

The only thing you'd want to add in your HTML::Template is a <tmpl_var name="quicknote"> the data for this variable will be put into special key {t}, thus you can stick it in secondary templates.

USED FIRST-LEVEL ZofCMS TEMPLATE KEYS

plugins

{
    plugins => [ qw/QuickNote/ ],
}

First and obvious is that you'd want to include the plugin in the list of plugins to run.

quicknote

# basic:
quicknote => {
    to  => 'me@example.com',
},

# juicy
quicknote => {
    mailer      => 'testfile',
    to          => [ 'foo@example.com', 'bar@example.com'],
    subject     => 'Quicknote from example.com',
    must_name   => 1,
    must_email  => 1,
    must_message => 1,
    name_max    => 20,
    email_max   => 20,
    message_max => 1000,
    success     => 'Your message has been successfuly sent',
    format      => <<'END_FORMAT',
Quicknote from host {::{host}::} sent on {::{time}::}
Name: {::{name}::}
E-mail: {::{email}::}
Message:
{::{message}::}
END_FORMAT
},

The quicknote first-level ZofCMS template key is the only thing you'll need to use to tell the plugin what to do. The key takes a hashref as a value. The only mandatory key in that hashref is the to key, the rest have default values. Possible keys in quicknote hashref are as follows:

to

to => 'me@example.com'

to => [ 'foo@example.com', 'bar@example.com'],

Mandatory. Takes either a string or an arrayref as a value. Passing the string is equivalent to passing an arrayref with just one element. Each element of that arrayref must contain a valid e-mail address, upon successful completion of the quicknote form by the visitor the data on that form will be emailed to all of the addresses which you specify here.

mailer

mailer => 'testfile',

Optional. Specifies which mailer to use for sending mail. See documentation for Mail::Mailer for possible mailers. When using the testfile mailer the file will be located in the same directory your in which your index.pl file is located. By default plugin will do the same thing Mail::Mailer will (search for the first available mailer).

subject

subject => 'Quicknote from example.com',

Optional. Specifies the subject line of the quicknote e-mail. Defaults to: Quicknote

must_name, must_email and must_message

must_name   => 1,
must_email  => 1,
must_message => 1,

Optional. The must_name, must_email and must_message arguments specify whether or not the "name", "e-mail" and "message" form fields are mandatory. When set to a true value indicate that the field is mandatory. When set to a false value the form field will be filled with N/A unless specified by the visitor. Visitor will be shown an error message if he or she did not specify some mandatory field. By default only the must_message argument is set to a true value (thus the vistior does not have to fill in neither the name nor the e-mail).

name_max, email_max and message_max

name_max    => 20,
email_max   => 20,
message_max => 1000,

Optional. Alike must_* arguments, the name_max, email_max and message_max specify max lengths of form fields. Visitor will be shown an error message if any of the parameters exceed the specified maximum lengths. By default the value for name_max is 100, value for email_max is 200 and value for message_max 10000

success

success => 'Your message has been successfuly sent',

Optional. Specifies the text to display to your visitor when the quicknote is successfuly sent. Defaults to: 'Your message has been successfuly sent'.

format

    format      => <<'END_FORMAT',
Quicknote from host {::{host}::} sent on {::{time}::}
Name: {::{name}::}
E-mail: {::{email}::}
Message:
{::{message}::}
END_FORMAT

Optional. Here you can specify the format of the quicknote e-mail which plugin will send. The following special sequences will be replaced by corresponding values:

{::{host}::}        - the host of the person sending the quicknote
{::{time}::}        - the time the message was sent ( localtime() )
{::{name}::}        - the "Name" form field
{::{email::}        - the "E-mail" form field
{::{message}::}     - the "Message" form field

Default format is shown above and in SYNOPSIS.

GENERATED HTML

Below is the HTML code generated by the plugin. Use CSS to style it.

# on successful send
<p class="quicknote_success"><tmpl_var name="success"></p>

# on error
<p class="quicknote_error"><tmpl_var name="error"></p>


# the form itself
<form class="quicknote" action="" method="POST">
<div>
    <input type="hidden" name="quicknote_username" value="your full name">
    <input type="hidden" name="page" value="index">
    <ul>
        <li>
            <label for="quicknote_name">Name:</label
            ><input type="text" name="quicknote_name" id="quicknote_name"
            value="">
        </li>
        <li>
            <label for="quicknote_email">E-mail: </label
            ><input type="text" name="quicknote_email" id="quicknote_email"
            value="">
        </li>
        <li>
            <label for="quicknote_message">Message: </label
            ><textarea name="quicknote_message" id="quicknote_message"
            cols="40" rows="10"></textarea>
        </li>
    </ul>
    <input type="submit" value="Send">
</div>
</form>

AUTHOR

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

BUGS

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

SUPPORT

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

perldoc App::ZofCMS::Plugin::QuickNote

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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