view release on metacpan or  search on metacpan

lib/App/ZofCMS/Plugin/FeatureSuggestionBox.pm  view on Meta::CPAN

        if not $conf->{no_identification}
            and length( $q->{plugfsb_email} ) > 300;

    return $self->_set_error('You must fill in your suggestion')
        if not _has_value( $q->{plugfsb_suggestion} );

    return $self->_set_error('"Your suggestion" cannot be longer than 300,000 characters')
        if length( $q->{plugfsb_suggestion} ) > 300000;

    return 1;
}

sub _make_form {
    my $self = shift;
    my $conf = $self->{CONF};
    my $q    = $self->{Q};

    my $template = HTML::Template->new_scalar_ref(
        \ $self->_get_form_html_template,
        die_on_bad_params => 0,
    );

    $template->param(
        page            => $self->{Q_PAGE},
        error           => $self->{ERROR},
        send_success    => $self->{SEND_SUCCESS},
        (
            map +( $_ => $q->{"plugfsb_$_"} ),
                qw/name  email  suggestion/,
        ),
        (
            map +( $_ => $conf->{$_} ),
                qw/submit_button  no_identification/,
        ),
    );

    return $template->output;
}

sub _set_error {
    my $self = shift;
    $self->{ERROR} = shift;
    return;
}

sub _has_value {
    my $v = shift;
    return 1
        if defined $v and length $v;

    return 0;
}

sub _email_template {
    return <<'END_HTML';
<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>
END_HTML
}

sub _get_form_html_template {
    return <<'END_HTML';
<tmpl_if name="send_success">
    <p class="success-message">Successfully sent.</p>
<tmpl_else>
    <form action="" method="POST" id="plugfsb_form">
    <div>
        <input type="hidden" name="page" value="<tmpl_var escape='html' name='page'>">
        <input type="hidden" name="plugfsb_send" value="1">

        <tmpl_if name="error">
            <p class="error"><tmpl_var escape='html' name='error'></p>
        </tmpl_if>

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

        <tmpl_var name='submit_button'>
    </div>
    </form>
</tmpl_if>
END_HTML
}

1;
__END__

=encoding utf8

=head1 NAME

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

=head1 SYNOPSIS

In your L<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">|,
    },

=head1 DESCRIPTION

The module is a plugin for L<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 L<App::ZofCMS>, L<App::ZofCMS::Config> and L<App::ZofCMS::Template>.

=head1 FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

=head2 C<plugins>

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

lib/App/ZofCMS/Plugin/FeatureSuggestionBox.pm  view on Meta::CPAN

            Auth   => [ 'foos/bars', 'p4ss' ],
        ],
    ...

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

=head3 C<submit_button>

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

B<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.
B<Defaults to:>
C<< <input type="submit" class="submit_button" value="Send"> >>

=head1 C<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>

=head2 C<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.

=head2 C<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.

=head1 EMAIL TEMPLATE

If C<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 L<HTML::Template> template variables available here as as follows:

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

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

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

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

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

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

=head2 C<< <tmpl_var name='suggestion'> >>

    Suggestion: <tmpl_var name='suggestion'>

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

=head2 C<< <tmpl_if name='has_name'> >>

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

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

=head2 C<< <tmpl_if name='has_email'> >>

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

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

=head1 GENERATED FORM

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

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

=head2 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>

=head2 An error occured

    <form action="" method="POST" id="plugfsb_form">