Unobtrusive Date-Picker Widget Plugin
This is a helper for creating a date or date-time picker that uses the Unobtrusive Date-Picker Widget(sic) (www.frequency-decoder.com/2006/10/02/unobtrusive-date-picker-widgit-update) to add a clickable calendar image that will bring up a calendar picker if javascript is available. It replicates as much of the API of the Rails ‘date_select`, and `datetime_select` form helpers.
It also uses the 12 Hour Time plugin (code.google.com/p/rails-twelve-hour-time-plugin/) so that 12 Hour times can be processed by Active Record.
You may want to consider compressing the javascript files with Dean Edward’s Packer (dean.edwards.name/packer/) or Douglas Crockford’s JSMin (www.crockford.com/javascript/jsmin.html) before deploying your application.
Install
`script/plugin install git://github.com/brianjlandau/unobtrusive_date_picker.git`
Usage
To be able to use the date-picker methods below you need to include the javascript library file and CSS stylesheet in the <head> of your layout template. You can do this either by manually including the files via a ‘javascript_include_tag` and a `stylesheet_link_tag` (the files are both named “datepicker”), OR by using the included `unobtrusive_datepicker_includes` helper method, which will do this for you.
There are 4 main methods:
- unobtrusive_date_picker
- unobtrusive_datetime_picker
-
-
- unobtrusive_date_text_picker
- unobtrusive_date_text_picker_tag
Options (* indicates same functionality as is in Rails Date helpers):
- *:order => the order the selects should be positioned in
- *:include_blank => include a blank option at the top of every select
- *:start_year => year that the year select should start on (defaults to 5
below either the year of the date value or current year)
- *:end_year => year that the year select should end on (defaults to 5 above
either the year of the date value or current year)
- *:minute_step => how many minutes apart each minute option should be
- example: (:minute_step => 5) would result in [0, 15, 30, 45] as options
- *:use_short_month => use short month names (Jan, Feb, etc.) instead of long
names (January) for option text
- *:use_month_numbers => use month numbers instead of names for option text
- *:add_month_numbers => add month numbers to names for option text ("1 - January")
- :highlight_days => which days of the week should be highlighted in the datepicker (by default Saturday and Sunday)
- Excepts either a string of number representing days of the week (0 = Monday, 1 = Tuesday ... 6 = Sunday)
- Or a singular symbol for one day of the week
- Or an array of symbols representing days of the week, i.e. [:Monday, :Sunday]
- :range_low => the low range of acceptable dates (not times) for this input
- managed by the Javascript, thus should be enforced with your own validations
- Excepts:
- One of the following symbols: :today, :tomorrow, :yesterday
- A string representation of a date
- A Date, DateTime, or Time object
- :range_high => the high range of acceptable dates (not times) for this input
- Excepts same options as :range_low; also managed by javascript
- :disable_days => days of the week that may not be selected
- Excepts the same format as :highlight_days
- Also managed by javascript
- :no_transparency => if set to true it disables the fade in/out
visual effect of the datepicker
The ‘unobtrusive_date_text_picker` and `unobtrusive_date_text_picker_tag` methods don’t except the “:order”, “:include_blank”, “:start_year”, “:end_year”, “:minute_step”, “:use_short_month”, “:use_month_numbers”, and “:add_month_numbers” options. It does use these options though:
- :format => the format the date should be in
- m-d-y
- d-m-y
- y-m-d
- :divider => the divider used between the dates
- "slash" or "/"
- "dash" or "-"
- "dot" or "."
- "space" or " "
RJS Method
There is an additional RJS method to re initialize the Date Pickers when an AJAX response is supplied to the client:
- unobtrusive_date_picker_create
- This method can accept the DOM ID of a year select element to turn into
a date picker widget or if none is provided it will create all based on
the appropriate class name.
Rake task
There is also a rake task that can be executed by running ‘rake datepicker:update` in your Rails apps root directory. This task will update your datepicker javascripts, stylesheets, and images. This is useful if you are using an old version of the plugin that had an older version of the Unobtrusive Date-Picker Widget Javascript library, or in the future when new version are release and I update the plugin with them.
Example:
<% form_for :article, :url => { :action => @form_action, :id => @article } do |f| %>
<fieldset>
...
<label>Date: <%= f.unobtrusive_datetime_picker :date %></label><br />
...
</fieldset>
<% end %>
Produces (Current date when output: 12/6/07):
<form action="/form/create" method="post">
<fieldset>
<label>Date:
<select id="article_date-dd" name="article[date(3i)]">
<option value="1">1</option>
...
<option value="31">31</option>
</select>
<select id="article_date-mm" name="article[date(2i)]">
<option value="1">January</option>
...
<option value="12" selected="selected">December</option>
</select>
<select id="article_date" name="article[date(1i)]" class="split-date">
<option value="2002">2002</option>
...
<option value="2012">2012</option>
</select>
<select id="article_date_4i" name="article[date(4i)][hour]">
<option value="1">1</option>
...
<option value="12">12</option>
</select>
:
<select id="article_date_5i" name="article[date(5i)][minute]">
<option value="00">00</option>
...
<option value="59">59</option>
</select>
<select id="article_date_6i" name="article[date(6i)][ampm]">
<option value="AMPM>AMPM</option>
<option value="AMPM>AMPM</option>
</select>
</label><br />
</fieldset>
</form>
LICENSE
See MIT-LICENSE file for copyright and licensing information for this plugin.
Unobtrusive Date-Picker Widget is provided under the Creative Commons Attribution-ShareAlike 2.5 license (creativecommons.org/licenses/by-sa/2.5/) by frequency-decoder.com