App::ZofCMS::Plugin::FeatureSuggestionBox - ZofCMS plugin that provides a feature suggestion box for your site
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">|, },
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.
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:
undef
@_
$t
$q
$config
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.
index.pl
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)
name
email
suggestion
1
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)
From
new()
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.
Your name
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} }
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.
Your email
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} }
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
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)
MIME::Lite->send()
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">
<input type="submit" class="submit_button" value="Send">
HTML::Template
<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
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.
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.
Suggestion
<br>
escape="html"
<tmpl_var>
<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.
Your emails
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.
no_identitification
<li>
The page hidden <input> element's value is obtained by the plugin automatically.
page
<input>
<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>
<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>
<p class="success-message">Successfully sent.</p>
Plugin requires these modules/versions:
App::ZofCMS::Plugin::Base => 0.0106, HTML::Template => 2.9, HTML::Entities => 1.35, MIME::Lite => 3.027,
Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS
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
bug-App-ZofCMS at rt.cpan.org
Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)
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.
LICENSE
To install App::ZofCMS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::ZofCMS
CPAN shell
perl -MCPAN -e shell install App::ZofCMS
For more information on module installation, please visit the detailed CPAN module installation guide.