/ 
App-ZofCMS-1.001008
River stage one • 1 direct dependent • 1 total dependent
/ App::ZofCMS::Plugin::FeatureSuggestionBox

NAME

App::ZofCMS::Plugin::FeatureSuggestionBox - ZofCMS plugin that provides a feature suggestion box for your site

SYNOPSIS

In your HTML::Template template:

<tmpl_var name='plug_feature_suggestion_box_form'>

In your ZofCMS Template:

plugins => [ qw/FeatureSuggestionBox/, ],

plug_feature_suggestion_box => {
    to => 'foo@bar.com',

    # this one has a default; see EMAIL TEMPLATE
    email_template    => 'blah blah',

    # everything below is optional; defaults are shown
    no_identification => 1,
    from              => undef,
    user_name         => sub { $_[0]->{d}{user}{name} },
    user_email        => sub { $_[0]->{d}{user}{email} },
    subject           => 'Feature Suggestion',
    mime_lite_params  => undef,
    submit_button => q|<input type="submit" class="submit_button"|
                        . q| value="Send">|,
},

DESCRIPTION

The module is a plugin for App::ZofCMS that gives you a "feature suggestion box". It is a form where a user can type up a suggestion and, once submitted, that suggestion will arrive in your email inbox.

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

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plugins => [
    { FeatureSuggestionBox => 2000 },
],

Mandatory. You need to include the plugin in the list of plugins to execute.

plug_feature_suggestion_box

plug_feature_suggestion_box => {
    to => 'foo@bar.com',

    # this one has a default; see EMAIL TEMPLATE
    email_template    => 'blah blah',

    # everything below is optional; defaults are shown
    no_identification => 1,
    from              => undef,
    user_name         => sub { $_[0]->{d}{user}{name} },
    user_email        => sub { $_[0]->{d}{user}{email} },
    subject           => 'Feature Suggestion',
    mime_lite_params  => undef,
    submit_button => q|<input type="submit" class="submit_button"|
                        . q| value="Send">|,
},

# or
plug_feature_suggestion_box => sub {
    my ( $t, $q, $config ) = @_;

    return $t->{hashref_to_assign_instead_of_this_sub};
},

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_feature_suggestion_box as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain $t, $q, and $config (in that order): where $t is ZofCMS Tempalate hashref, $q is query parameters hashref, and $config is App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:

to

plug_feature_suggestion_box => {
    to => 'foo@bar.com',
...

plug_feature_suggestion_box => {
    to => sub {
        my ( $t, $q, $config ) = @_;
        return 'foo@meow.com';
    }
...

Mandatory. Takes a scalar or a subref as a value. Specifies one or more email addresses to which to send feature suggestion. Separate multiple addresses with a comma(,). If subref is specified, its return value will be assigned to to, as if it were already there. Plugin will stop executing if to is not specified, or if the subref returns an undef or an empty list. In its @_ the subref will have $t, $q, and $config (in that order): where $t is ZofCMS Tempalate hashref, $q is query parameters hashref, and $config is App::ZofCMS::Config object.

email_template

plug_feature_suggestion_box => {
    email_template => 'blah blah',
...

plug_feature_suggestion_box => {
    email_template => \'template.tmpl',
...

Optional. Takes a scalar or a scalarref as a value. If a scalar is specified it will be interpreted as an HTML::Template template for use for the email (containing feature suggestion) body. If a scalarref is specified, it will be taken as a filename pointing to the file containing HTML::Template for the email. If relative path is specified, it will be relative to index.pl file. For template variables as well as the default email template see "EMAIL TEMPLATE" section below.

no_identification

plug_feature_suggestion_box => {
    no_identification => 1,
...

Optional. Takes either true or false values. If a false value is set, plugin's form will have three fields for the user to fill out: name, email, and suggestion. If set to a true value, the name and email fields will be suppressed, and the user will be presented only with a single box to fill out, the suggestion. Defaults to: 1 (name/email are disabled)

from

plug_feature_suggestion_box => {
    from => undef,
...

plug_feature_suggestion_box => {
    from => 'Zoffix Znet <cpan@zoffix.com>',
...

Optional. Takes a scalar as a value that specifies the From field for the email. If not specified, the plugin will simply not set the From argument in MIME::Lite's new() method (which is what this plugin uses under the hood). See MIME::Lite's docs for more description. Defaults to: undef (not specified)

user_name

plug_feature_suggestion_box => {
    user_name => sub { $_[0]->{d}{user}{name} },
...

plug_feature_suggestion_box => {
    user_name => 'Zoffix Znet',
...

Optional. Takes a subref or a scalar as a value. The value of this argument will be present in the email indicating submitter's name. Applies regardless of no_identification argument's value. If specified, the value will override whatever the user enters in the Your name field.

If subref is specified, its return value will be assigned to user_name, as if it were already there. In its @_ the subref will have $t, $q, and $config (in that order): where $t is ZofCMS Tempalate hashref, $q is query parameters hashref, and $config is App::ZofCMS::Config object. Defaults to: sub { $_[0]->{d}{user}{name} }

user_email

plug_feature_suggestion_box => {
    user_email => sub { $_[0]->{d}{user}{email} },
...

plug_feature_suggestion_box => {
    user_email => 'cpan@zoffix.com,
...

Optional. Takes a subref or a scalar as a value. The value of this argument will be present in the email indicating submitter's email address. Applies regardless of no_identification argument's value. If specified, the value will override whatever the user enters in the Your email field.

If subref is specified, its return value will be assigned to user_email, as if it were already there. In its @_ the subref will have $t, $q, and $config (in that order): where $t is ZofCMS Tempalate hashref, $q is query parameters hashref, and $config is App::ZofCMS::Config object. Defaults to: sub { $_[0]->{d}{user}{email} }

subject

plug_feature_suggestion_box => {
    subject => 'Feature Suggestion',
...

Optional. Takes a scalar as a value. The value will become the subject of the email. Defaults to: Feature Suggestion

mime_lite_params

plug_feature_suggestion_box => {
    mime_lite_params => undef,
...

plug_feature_suggestion_box => {
    mime_lite_params => [
        'smtp',
        'foosmail',
        Auth   => [ 'foos/bars', 'p4ss' ],
    ],
...

Optional. Takes an arrayref as a value. If specified, the arrayref will be directly dereferenced into MIME::Lite->send(). Here you can set any special send arguments you need; see MIME::Lite docs for more info. Note: if the plugin refuses to send email, it could well be that you need to set some mime_lite_params; on my box, without anything set, the plugin behaves as if everything went through fine, but no email arrives. Defaults to: undef (not specified)

submit_button

plug_feature_suggestion_box => {
    submit_button => q|<input type="submit" class="submit_button"|
                        . q| value="Send">|,
...

Optional. Takes HTML code as a value. This code represents the submit button in the feature suggestion form. This, for example, allows you to use image buttons instead of regular ones. Also, feel free to use this as the insertion point for any extra HTML form you need in this form. Defaults to: <input type="submit" class="submit_button" value="Send">

HTML::Template TEMPLATE VARIABLES

<tmpl_var name='plug_feature_suggestion_box_form'>

<tmpl_if name='plug_feature_suggestion_box_sent'>
    <p>Yey! :)</p>
</tmpl_if>

plug_feature_suggestion_box_for

<tmpl_var name='plug_feature_suggestion_box_form'>

This variable will contain either the feature suggestion form or a success message if that form was successfully submitted.

plug_feature_suggestion_box_sent

<tmpl_if name='plug_feature_suggestion_box_sent'>
    <p>Yey! :)</p>
</tmpl_if>

This will be set to true if the form has been successfully submitted.

EMAIL TEMPLATE

If email_template argument is not specified, the plugin will use its default email template shown here:

<h1>Feature Suggestion</h1>

<dl>
    <tmpl_if name='has_name'>
        <dt>From:</dt>
            <dd><tmpl_var escape='html' name='name'></dd>
    </tmpl_if>

    <tmpl_if name='has_email'>
        <dt>Email:</dt>
            <dd><a href="mailto:<tmpl_var escape='html'
                name='email'>"
                ><tmpl_var escape='html' name='email'></a></dd>
    </tmpl_if>

    <dt>Suggestion:</dt>
        <dd><tmpl_var name='suggestion'></dd>
</dl>

The HTML::Template template variables available here as as follows:

<tmpl_var escape='html' name='name'>

From: <tmpl_var escape='html' name='name'>

If user_name argument is specified, this variable will contain its value. Otherwise, it will either contain what the user specifies in the Your name field in the form, or won't be set at all.

<tmpl_var escape='html' name='email'>

Email: <tmpl_var escape='html' name='email'>

If user_email argument is specified, this variable will contain its value. Otherwise, it will either contain what the user specifies in the Your email field in the form, or won't be set at all.

<tmpl_var name='suggestion'>

Suggestion: <tmpl_var name='suggestion'>

This variable will contain what the user types in the Suggestion box in the form. Note: HTML entities will be escaped here and new lines replaced with <br> elements; thus, do not use escape="html" <tmpl_var> attribute here.

<tmpl_if name='has_name'>

<tmpl_if name='has_name'>
    I HAS NAME!!!
</tmpl_if>

Set to a true value if either user_name argument is set to something, or the user fills the Your name field in the form.

<tmpl_if name='has_email'>

<tmpl_if name='has_email'>
    I HAS EMAIL!!!
</tmpl_if>

Set to a true value if either user_email argument is set to something, or the user fills the Your emails field in the form.

GENERATED FORM

Examples below show the form with three fields. If no_identitification argument is set to a true value, the Your name and Your email fields (altogether with <li> elements that contain them) won't be present.

The page hidden <input> element's value is obtained by the plugin automatically.

Default view

<form action="" method="POST" id="plugfsb_form">
<div>
    <input type="hidden" name="page" value="/index">
    <input type="hidden" name="plugfsb_send" value="1">

    <ul>
        <li><label for="plugfsb_name">Your name:</label
            ><input type="text" class="input_text"
                name="plugfsb_name" id="plugfsb_name"
                value=""></li>
        <li><label for="plugfsb_email">Your email:</label
            ><input type="text" class="input_text"
                name="plugfsb_email" id="plugfsb_email"
                value=""></li>
        <li><label for="plugfsb_suggestion"
            class="textarea_label">Your suggestion:</label
            ><textarea id="plugfsb_suggestion" cols="60" rows="5"
                name="plugfsb_suggestion"
            ></textarea></li>
    </ul>

    <input type="submit" class="submit_button" value="Send">
</div>
</form>

An error occured

<form action="" method="POST" id="plugfsb_form">
<div>
    <input type="hidden" name="page" value="/index">
    <input type="hidden" name="plugfsb_send" value="1">

    <p class="error">You must fill in your name</p>

    <ul>
        <li><label for="plugfsb_name">Your name:</label
            ><input type="text" class="input_text"
                name="plugfsb_name" id="plugfsb_name"
                value=""></li>
        <li><label for="plugfsb_email">Your email:</label
            ><input type="text" class="input_text"
                name="plugfsb_email" id="plugfsb_email"
                value=""></li>
        <li><label for="plugfsb_suggestion"
            class="textarea_label">Your suggestion:</label
            ><textarea id="plugfsb_suggestion" cols="60" rows="5"
                name="plugfsb_suggestion"
            ></textarea></li>
    </ul>

    <input type="submit" class="submit_button" value="Send">
</div>
</form>

Feature successfully submitted

<p class="success-message">Successfully sent.</p>

REQUIRED MODULES

Plugin requires these modules/versions:

App::ZofCMS::Plugin::Base => 0.0106,
HTML::Template            => 2.9,
HTML::Entities            => 1.35,
MIME::Lite                => 3.027,

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.