Permalink
Browse files

some documentation for Timeish inputs, fixes #589

  • Loading branch information...
1 parent 82fa002 commit e34f01b72c6c373c4b97aa626d629cb6d1e8ed7e @justinfrench committed Jun 11, 2011
@@ -1,6 +1,90 @@
module Formtastic
module Inputs
module Base
+ # Timeish inputs (`:date`, `:datetime`, `:time`) are similar to the Rails date and time
+ # helpers (`date_select`, `datetime_select`, `time_select`), rendering a series of `<select>`
+ # tags for each fragment (year, month, day, hour, minute, seconds). The fragments are then
+ # re-combined to a date by ActiveRecord through multi-parameter assignment.
+ #
+ # The mark-up produced by Rails is simple but far from ideal, with no way to label the
+ # individual fragments for accessibility, no fieldset to group the related fields, and no
+ # legend describing the group. Formtastic addresses this within the standard `<li>` wrapper
+ # with a `<fieldset>` with a `<legend>` as a label, followed by an ordered list (`<ol>`) of
+ # list items (`<li>`), one for each fragment (year, month, ...). Each `<li>` fragment contains
+ # a `<label>` (eg "Year") for the fragment, and a `<select>` containing `<option>`s (eg a
+ # range of years).
+ #
+ # In the supplied formtastic.css file, the resulting mark-up is styled to appear a lot like a
+ # standard Rails date time select by:
+ #
+ # * styling the legend to look like the other labels (to the left hand side of the selects)
+ # * floating the `<li>` fragments against each other as a single line
+ # * hiding the `<label>` of each fragment with `display:none`
+ #
+ # @example `:date` input with full form context and sample HTMl output
+ #
+ # <%= semantic_form_for(@post) do |f| %>
+ # <%= f.inputs do %>
+ # ...
+ # <%= f.input :publish_at, :as => :date %>
+ # <% end %>
+ # <% end %>
+ #
+ # <form...>
+ # <fieldset class="inputs">
+ # <ol>
+ # <li class="date">
+ # <fieldset class="fragments">
+ # <ol class="fragments-group">
+ # <li class="fragment">
+ # <label for="post_publish_at_1i">Year</label>
+ # <select id="post_publish_at_1i" name="post[publish_at_1i]">...</select>
+ # </li>
+ # <li class="fragment">
+ # <label for="post_publish_at_2i">Month</label>
+ # <select id="post_publish_at_2i" name="post[publish_at_2i]">...</select>
+ # </li>
+ # <li class="fragment">
+ # <label for="post_publish_at_3i">Day</label>
+ # <select id="post_publish_at_3i" name="post[publish_at_3i]">...</select>
+ # </li>
+ # </ol>
+ # </fieldset>
+ # </li>
+ # </ol>
+ # </fieldset>
+ # </form>
+ #
+ #
+ # @example `:time` input
+ # <%= f.input :publish_at, :as => :time %>
+ #
+ # @example `:datetime` input
+ # <%= f.input :publish_at, :as => :datetime %>
+ #
+ # @example Change the labels for each fragment
+ # <%= f.input :publish_at, :as => :date, :labels => { :year => "Y", :month => "M", :day => "D" } %>
+ #
+ # @example Skip a fragment (defaults to 1, skips all following fragments)
+ # <%= f.input :publish_at, :as => :datetime, :discard_minute => true %>
+ # <%= f.input :publish_at, :as => :datetime, :discard_hour => true %>
+ # <%= f.input :publish_at, :as => :datetime, :discard_day => true %>
+ # <%= f.input :publish_at, :as => :datetime, :discard_month => true %>
+ # <%= f.input :publish_at, :as => :datetime, :discard_year => true %>
+ #
+ # @example Change the order
+ # <%= f.input :publish_at, :as => :date, :order => [:month, :day, :year] %>
+ #
+ # @example Include seconds with times (excluded by default)
+ # <%= f.input :publish_at, :as => :time, :include_seconds => true %>
+ #
+ # @example Specify if there should be a blank option at the start of each select or not
+ # <%= f.input :publish_at, :as => :time, :include_blank=> true %>
+ # <%= f.input :publish_at, :as => :time, :include_blank=> false %>
+ #
+ # @todo Document i18n
+ # @todo Check what other Rails options are supported (`start_year`, `end_year`, `use_month_numbers`, `use_short_month`, `add_month_numbers`, `prompt`), write tests for them, and otherwise support them
+ # @todo Could we take the rendering from Rails' helpers and inject better HTML in and around it rather than re-inventing the whee?
module Timeish
def to_html
@@ -1,5 +1,7 @@
module Formtastic
module Inputs
+ # Outputs a series of select boxes for the fragments that make up a date (year, month, day).
+ #
# @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
class DateInput
include Base
@@ -1,5 +1,8 @@
module Formtastic
module Inputs
+
+ # Outputs a series of select boxes for the fragments that make up a date and time (year, month, day, hour, minute, second).
+ #
# @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
class DatetimeInput
include Base
@@ -1,5 +1,7 @@
module Formtastic
module Inputs
+ # Outputs a series of select boxes for the fragments that make up a time (hour, minute, second).
+ #
# @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
class TimeInput
include Base

0 comments on commit e34f01b

Please sign in to comment.