NAME

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

SYNOPSIS

    <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 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 => [ 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 elements 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 documentation 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 argument. 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 argument:

    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> elements (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.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plug_bool_settings_manager

settings

dsn

user

pass

opt

table

login_col

login

submit_button