The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-1.001008
River stage one • 1 direct dependent • 1 total dependent
++
/ 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'.

on_success

    on_success => 'quicknote_success'

Optional. Takes a string as a value that representes a key in {t} special key. When specified, the plugin will set the on_success key in {t} special key to a true value when the quicknote has been sent; this can be used to display some special messages when quick note succeeds. Defaults to: quicknote_success.

on_error

    on_error => 'quicknote_error'

Optional. Takes a string as a value that representes a key in {t} special key. When specified, the plugin will set the on_error key in {t} special key to a true value when the quicknote has not been sent due to some error, e.g. user did not specify mandatory parameters; this can be used to display some special messages when quick note fails. By default is not specified.

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" id="quicknote_submit" value="Send">
    </div>
    </form>

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.