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.