rd_unobtrusive_date_picker

= 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) (http://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 (http://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 (http://dean.edwards.name/packer/) or Douglas Crockford's JSMin (http://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 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_picker_tags
• unobtrusive_datetime_picker_tags
• 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| %>

... Date: <%= f.unobtrusive_datetime_picker :date %>
... <% end %>

=== Produces (Current date when output: 12/6/07):

     <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>
         &nbsp; 
        <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>

== 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 (http://creativecommons.org/licenses/by-sa/2.5/) by frequency-decoder.com