Zoffix Znet > App-ZofCMS > App::ZofCMS::Plugin::BoolSettingsManager

Download:
App-ZofCMS-1.001004.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.001004   Source  

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

syntax highlighting: