/ 
App-ZofCMS-1.001002
River stage one • 1 direct dependent • 1 total dependent
/ App::ZofCMS::Plugin::BoolSettingsManager

NAME

App::ZofCMS::Plugin::BoolSettingsManager - Plugin to let individual users manage boolean settings

SYNOPSIS

In HTML::Template template:

<tmpl_var name='plug_bool_settings_manager_form'>

In ZofCMS Template:

plugins => [
    qw/BoolSettingsManager/,
],

plug_bool_settings_manager => {
    settings => [
        notice_forum         => q|new forum posts|,
        notice_flyers        => q|new flyer uploads|,
        notice_photo_library => q|new images added to Photo Library|,
    ],

    # everything below is optional; default values are shown
    dsn           => "DBI:mysql:database=test;host=localhost",
    user          => '',
    pass          => undef,
    opt           => { RaiseError => 1, AutoCommit => 1 },
    table         => 'users',
    login_col     => 'login',
    login         => sub { $_[0]->{d}{user}{login} },
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
},

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to present a user a form with a number of checkboxes that control boolean settings, which are stored in a SQL database.

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

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plugins => [ qw/BoolSettingsManager/ ],

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

plug_bool_settings_manager

plug_bool_settings_manager => {
    settings => [
        notice_forum         => q|new forum posts|,
        notice_flyers        => q|new flyer uploads|,
        notice_photo_library => q|new images added to Photo Library|,
    ],

    # everything below is optional; default values are shown
    dsn           => "DBI:mysql:database=test;host=localhost",
    user          => '',
    pass          => undef,
    opt           => { RaiseError => 1, AutoCommit => 1 },
    table         => 'users',
    login_col     => 'login',
    login         => sub { $_[0]->{d}{user}{login} },
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
},

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_bool_settings_manager key 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 Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:

settings

plug_bool_settings_manager => {
    settings => [
        notice_forum         => q|new forum posts|,
        notice_flyers        => q|new flyer uploads|,
        notice_photo_library => q|new images added to Photo Library|,
    ],
...

plug_bool_settings_manager => {
    settings => sub {
        my ( $t, $q, $config ) = @_;
        return $arrayref_to_assing_to_settings;
    },
...

Mandatory. Takes an arrayref or a subref as a value. If subref is specified, its return value must be either an arrayref or undef (or empty list). The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object.

If settings is not specified, or its arrayref is empty, or if the subref returns undef, empty arrayref or empty list, plugin will stop further execution.

The arrayref must have an even number of elemeants that are to be thought of as keys and values (the arrayref is used to preserve order). The "keys" of the arrayref represent boolean column names in table (see below) SQL table in which users' settings are stored (one setting per column). The keys will also be used as parts of id="" attributes in the form, thus they need to also conform to HTML spec (http://xrl.us/bicips) (or whatever your markup language of choice is).

The "values" must be strings that represent the human readable description of their corresponding "keys". These will be shown as text in the <label>s for corresponding checkboxes.

dsn

plug_bool_settings_manager => {
    dsn => "DBI:mysql:database=test;host=localhost",
...

Optional, but the default is pretty useless. The dsn key will be passed to DBI's connect_cached() method, see documeantation for DBI and DBD::your_database for the correct syntax for this one. The example above uses MySQL database called test which is located on localhost. Defaults to: "DBI:mysql:database=test;host=localhost"

user

plug_bool_settings_manager => {
    user => '',
...

Optional. Specifies the user name (login) for the database. This can be an empty string if, for example, you are connecting using SQLite driver. Defaults to: '' (empty string)

pass

plug_bool_settings_manager => {
    pass => undef,
...

Optional. Same as user except specifies the password for the database. Defaults to: undef (no password)

opt

plug_bool_settings_manager => {
    opt => { RaiseError => 1, AutoCommit => 1 },
...

Optional. Will be passed directly to DBI's connect_cached() method as "options". Defaults to: { RaiseError => 1, AutoCommit => 1 }

table

plug_bool_settings_manager => {
    table => 'users',
...

Optional. Takes a string as a value that specifies the name of the table in which users' logins and their settings are stored. Defaults to: users

login_col

plug_bool_settings_manager => {
    login_col => 'login',
...

Optional. Takes a string as a value that specifies the name of the column in table table that contains users' logins. Defaults to: login

login

plug_bool_settings_manager => {
    login => sub {
        my ( $t, $q, $config ) = @_;
        return $t->{d}{user}{login};
    },
...

plug_bool_settings_manager => {
    login => 'zoffix',
...

Optional. Takes an undef, a subref or a scalar as a value. Specifies the login of a current user. This is the value located in the login_col (see above) column. This will be used to look up/store the settings. If a subref is specified, its return value must be either an undef or a scalar, which will be assigned to login as if it was already there. If login is set to undef (or the sub returns an undef/empty list), then plugin will stop further execution. The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object. Defaults to: sub { $_[0]->{d}{user}{login} }

submit_button

plug_bool_settings_manager => {
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
...

Optional. Takes HTML code as a value, which represents the submit button to be used on the settings-changing form. Feel free to throw in any extra code into this argumeant. Defaults to: <input type="submit" class="input_submit" value="Save">

HTML::Template TEMPLATE VARIABLE

All of plugin's output is spit out into a single variable in your HTML::Template template:

<tmpl_var name='plug_bool_settings_manager_form'>

HTML CODE GENERATED BY THE PLUGIN

The HTML code below was generated after saving settings in the form generated using this plugin's settings argumeant:

settings => [
    notice_forum         => q|new forum posts|,
    notice_flyers        => q|new flyer uploads|,
    notice_photo_library => q|new images added to Photo Library|,
],

Notice the "keys" in the settings arrayref are used to generate id="" attributes on the <li> and <input> elemeants (and for="" attribute on <label>s). The value for page hidden <input> is derived by the plugin automagically.

<p class="success-message">Successfully saved</p>

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

    <ul>
        <li id="pbsm_container_notice_forum">
            <input type="checkbox"
                id="pbsm_notice_forum"
                name="notice_forum"
            ><label for="pbsm_notice_forum"
                class="checkbox_label"> new forum posts</label>
        </li>
        <li id="pbsm_container_notice_flyers">
            <input type="checkbox"
                id="pbsm_notice_flyers"
                name="notice_flyers"
            ><label for="pbsm_notice_flyers"
                class="checkbox_label"> new flyer uploads</label>
        </li>
        <li id="pbsm_container_notice_photo_library">
            <input type="checkbox"
                id="pbsm_notice_photo_library"
                name="notice_photo_library"
                checked
            ><label for="pbsm_notice_photo_library"
                class="checkbox_label"> new images added to Photo Library</label>
        </li>
    </ul>
    <input type="submit" class="input_submit" value="Save">
</div>
</form>

The <p class="success-message">Successfully saved</p> paragraph is only shown when user saves their settings.

REQUIRED MODULES

Plugin requires the following modules to survive:

App::ZofCMS::Plugin::Base => 0.0106,
HTML::Template            => 2.9,
DBI                       => 1.607,

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.