The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-1.001004
River stage one • 1 direct dependent • 1 total dependent
++
/ App::ZofCMS::Plugin::DateSelector

NAME

App::ZofCMS::Plugin::DateSelector - plugin to generate and "parse" <select>s for date/time input

SYNOPSIS

In ZofCMS Template or Main Config File

    # the Sub plugin is used only for demonstration here

    plugins => [ { DateSelector => 2000 }, { Sub => 3000 } ],

    plug_date_selector => {
        class           => 'date_selector',
        id              => 'date_selector',
        q_name          => 'date',
        t_name          => 'date_selector',
        start           => time() - 30000000,
        end             => time() + 30000000,
        interval_step   => 'minute',
        interval_max    => 'year',
    },

    plug_sub => sub {
        my $t = shift;
        $t->{t}{DATE} = "[$t->{d}{date_selector}{localtime}]";
    },

In HTML::Template template:

    <form...

        <label for="date_selector">When: </label><tmpl_var name="date_selector">

    .../form>

    <tmpl_if name="DATE">
        <p>You selected: <tmpl_var name="DATE"></p>
    <tmpl_else>
        <p>You did not select anything yet</p>
    </tmpl_if>

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to generate several <select> elements for date and time selection by the user. Plugin also provides means to "parse" those <select>s from the query to generate either epoch time, same string as localtime() or access each selection individually from a hashref.

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/DateSelector/ ],

You obviously need to add the plugin to the list of plugins to execute. The plugin does not provide any input checking and sticks the "parse" of query into the {d} special key in ZofCMS Template, thus you'd very likely to use this plugin in combination with some other plugin.

plug_date_selector

    plug_date_selector => {
        class           => 'date_selector',
        id              => 'date_selector',
        q_name          => 'date',
        t_name          => 'date_selector',
        d_name          => 'date_selector',
        start           => time() - 30000000,
        end             => time() + 30000000,
        interval_step   => 'minute',
        interval_max    => 'year',
    }

    plug_date_selector => [
        {
            class           => 'date_selector1',
            id              => 'date_selector1',
            q_name          => 'date1',
            t_name          => 'date_selector1',
            d_name          => 'date_selector1',
        },
        {
            class           => 'date_selector2',
            id              => 'date_selector2',
            q_name          => 'date2',
            t_name          => 'date_selector2',
            d_name          => 'date_selector2',
        }
    ]

Plugin will not run unless plug_date_selector first-level key is specified in either ZofCMS Template or Main Config File. When specified in both, ZofCMS Template and Main Config File, then the value set in ZofCMS Template takes precedence. To use the plugin with all of its defaults use plug_date_selector => {}

The plug_date_selector key takes either hashref or an arrayref as a value. If the value is a hashref, it is the same as specifying an arrayref with just that hashref in it. Each hashref represents a separate "date selector", i.e. a set of <select> elements for date selection. The possible keys/values of each of those hashrefs are as follows:

class

    class => 'date_selector',

Optional. Specifies the class="" attribute to stick on every generated <select> element in the date selector. Defaults to: date_selector

id

    id => 'date_selector',

Optional. Specifies the id="" attribute to stick on the first generated <select> element in the date selector. By default is not specified, i.e. no id="" will be added.

q_name

    q_name => 'date',

Optional. Specifies the "base" query parameter name for generated <select> elements. Each of those elements will have its name="" attribute made from $q_name . '_' . $type, where $q_name is the value of q_name key and $type is the type of the <select>, the types are as follows: year, month, day, hour, minute and second. Defaults to: date

t_name

    t_name => 'date_selector',

Optional. Specifies the name of the key in {t} ZofCMS Template special key where to stick HTML code for generated <select>s. Defaults to: date_selector, thus you'd use <tmpl_var name='date_selector'> to insert HTML code.

d_name

    d_name => 'date_selector',

Optional. If plugin sees that the query contains all of the parameters from a given "date selector", then it will set the d_name key in {d} ZofCMS Template special key with a hashref that contains three keys:

    $VAR1 = {
        'time' => 1181513455,
        'localtime' => 'Sun Jun 10 18:10:55 2007',
        'bits' => {
            'hour' => '18',
            'minute' => '10',
            'second' => 55,
            'month' => '5',
            'day' => '10',
            'year' => 107
        }
    };

time

    'time' => 1181513455,

The time key will contain the epoch time of the date that user selected (i.e. as time() would output).

localtime

    'localtime' => 'Sun Jun 10 18:10:55 2007',

The localtime key will contain the "date string" of the selected date (i.e. output of localtime()).

bits

    'bits' => {
        'hour' => '18',
        'minute' => '10',
        'second' => 55,
        'month' => '5',
        'day' => '10',
        'year' => 107
    }

The bits key will contain a hashref, with individual "bits" of the selected date. The "bits" are keys in the hashref and are as follows: year, month, day, hour, minute and second. If your date selector's range does not cover all the values (e.g. has only month and day) (see interval_step and interval_max options below) then the missing values will be taken from the output of localtime(). The values of each of these "bits" are in the same format as localtime() would give them to you, i.e. to get the full year you'd do bits->{year} + 1900.

start

    start => time() - 30000000,

Optional. The plugin will generate values for <select> elements to cover a certain period of time. The start and end (see below) parameters take the number of seconds from epoch (i.e. same as return of time()) as values and start indicates the start of the period to cover and end indicates the end of the time period to cover. Defaults to: time() - 30000000

end

    end => time() + 30000000,

Optional. See description of start right above. Defaults to: time() + 30000000

interval_step

    interval_step   => 'minute',

Optional. Specifies the "step", or the minimum unit of time the user would be able to select. Valid values (all lowercase) are as follows: year, month, day, hour, minute and second. Defaults to: minute

interval_max

    interval_max => 'year',

Optional. Specifies the maximum unit of time the user would be able to select. Valid values (all lowercase) are as follows: year, month, day, hour, minute and second. Defaults to: year

minute_step

    minute_step => 5,

Optional. Specifies the "step" of minutes to display, in other words, when minute_step is set to 10, then in the "minutes" <select> the plugin will generate only <option>s 0, 10, 20, 30, 40 and 50. Defaults to: 5 (increments of 5 minutes).

second_step

    second_step => 10,

Optional. Specifies the "step" of seconds to display, in other words, when second_step is set to 10, then in the "minutes" <select> the plugin will generate only <option>s 0, 10, 20, 30, 40 and 50. Defaults to: 5 (increments of 5 minutes).

HTML::Template VARIABLES

See description of t_name argument above. The value of t_name specifies the name of the <tmpl_var name=""> plugin will generate. Note that there could be several of these of you are generating several date selectors.

GENERATED HTML CODE

The following is a sample of the generated code with all the defaults left intact:

    <select name="date_year" class="date_selector">
        <option value="107" selected>2007</option>
        <option value="108">2008</option>
        <option value="109">2009</option>
    </select>

    <select name="date_month" class="date_selector">
        <option value="0" selected>January</option>
        <option value="1">February</option>
        <option value="2">March</option>
        <option value="3">April</option>
        <option value="4">May</option>
        <option value="5">June</option>
        <option value="6">July</option>
        <option value="7">August</option>
        <option value="8">September</option>
        <option value="9">October</option>
        <option value="10">November</option>
        <option value="11">December</option>
    </select>

    <select name="date_day" class="date_selector">
        <option value="1" selected>Day: 1</option>
        <option value="2">Day: 2</option>
        <option value="3">Day: 3</option>
        <option value="4">Day: 4</option>
        <option value="5">Day: 5</option>
        <option value="6">Day: 6</option>
        <option value="7">Day: 7</option>
        <option value="8">Day: 8</option>
        <option value="9">Day: 9</option>
        <option value="10">Day: 10</option>
        <option value="11">Day: 11</option>
        <option value="12">Day: 12</option>
        <option value="13">Day: 13</option>
        <option value="14">Day: 14</option>
        <option value="15">Day: 15</option>
        <option value="16">Day: 16</option>
        <option value="17">Day: 17</option>
        <option value="18">Day: 18</option>
        <option value="19">Day: 19</option>
        <option value="20">Day: 20</option>
        <option value="21">Day: 21</option>
        <option value="22">Day: 22</option>
        <option value="23">Day: 23</option>
        <option value="24">Day: 24</option>
        <option value="25">Day: 25</option>
        <option value="26">Day: 26</option>
        <option value="27">Day: 27</option>
        <option value="28">Day: 28</option>
        <option value="29">Day: 29</option>
        <option value="30">Day: 30</option>
        <option value="31">Day: 31</option>
    </select>

    <select name="date_hour" class="date_selector">
        <option value="0" selected>Hour: 0</option>
        <option value="1">Hour: 1</option>
        <option value="2">Hour: 2</option>
        <option value="3">Hour: 3</option>
        <option value="4">Hour: 4</option>
        <option value="5">Hour: 5</option>
        <option value="6">Hour: 6</option>
        <option value="7">Hour: 7</option>
        <option value="8">Hour: 8</option>
        <option value="9">Hour: 9</option>
        <option value="10">Hour: 10</option>
        <option value="11">Hour: 11</option>
        <option value="12">Hour: 12</option>
        <option value="13">Hour: 13</option>
        <option value="14">Hour: 14</option>
        <option value="15">Hour: 15</option>
        <option value="16">Hour: 16</option>
        <option value="17">Hour: 17</option>
        <option value="18">Hour: 18</option>
        <option value="19">Hour: 19</option>
        <option value="20">Hour: 20</option>
        <option value="21">Hour: 21</option>
        <option value="22">Hour: 22</option>
        <option value="23">Hour: 23</option>
    </select>

    <select name="date_minute" class="date_selector">
        <option value="0" selected>Minute: 00</option>
        <option value="5">Minute: 05</option>
        <option value="10">Minute: 10</option>
        <option value="15">Minute: 15</option>
        <option value="20">Minute: 20</option>
        <option value="25">Minute: 25</option>
        <option value="30">Minute: 30</option>
        <option value="35">Minute: 35</option>
        <option value="40">Minute: 40</option>
        <option value="45">Minute: 45</option>
        <option value="50">Minute: 50</option>
        <option value="55">Minute: 55</option>
    </select>

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.