vendor/rails/actionpack/lib/action_view/helpers/date_helper.rb

   1 require "date"
   2 require 'action_view/helpers/tag_helper'
   3
   4 module ActionView
   5   module Helpers
   6     # The Date Helper primarily creates select/option tags for different kinds of dates and date elements. All of the
   7     # select-type methods share a number of common options that are as follows:
   8     #
   9     # * <tt>:prefix</tt> - overwrites the default prefix of "date" used for the select names. So specifying "birthday"
  10     # would give birthday[month] instead of date[month] if passed to the select_month method.
  11     # * <tt>:include_blank</tt> - set to true if it should be possible to set an empty date.
  12     # * <tt>:discard_type</tt> - set to true if you want to discard the type part of the select name. If set to true,
  13     #   the select_month method would use simply "date" (which can be overwritten using <tt>:prefix</tt>) instead of
  14     #   "date[month]".
  15     module DateHelper
  16       # Reports the approximate distance in time between two Time or Date objects or integers as seconds.
  17       # Set <tt>include_seconds</tt> to true if you want more detailed approximations when distance < 1 min, 29 secs
  18       # Distances are reported based on the following table:
  19       #
  20       #   0 <-> 29 secs                                                             # => less than a minute
  21       #   30 secs <-> 1 min, 29 secs                                                # => 1 minute
  22       #   1 min, 30 secs <-> 44 mins, 29 secs                                       # => [2..44] minutes
  23       #   44 mins, 30 secs <-> 89 mins, 29 secs                                     # => about 1 hour
  24       #   89 mins, 29 secs <-> 23 hrs, 59 mins, 29 secs                             # => about [2..24] hours
  25       #   23 hrs, 59 mins, 29 secs <-> 47 hrs, 59 mins, 29 secs                     # => 1 day
  26       #   47 hrs, 59 mins, 29 secs <-> 29 days, 23 hrs, 59 mins, 29 secs            # => [2..29] days
  27       #   29 days, 23 hrs, 59 mins, 30 secs <-> 59 days, 23 hrs, 59 mins, 29 secs   # => about 1 month
  28       #   59 days, 23 hrs, 59 mins, 30 secs <-> 1 yr minus 1 sec                    # => [2..12] months
  29       #   1 yr <-> 2 yrs minus 1 secs                                               # => about 1 year
  30       #   2 yrs <-> max time or date                                                # => over [2..X] years
  31       #
  32       # With <tt>include_seconds</tt> = true and the difference < 1 minute 29 seconds:
  33       #   0-4   secs      # => less than 5 seconds
  34       #   5-9   secs      # => less than 10 seconds
  35       #   10-19 secs      # => less than 20 seconds
  36       #   20-39 secs      # => half a minute
  37       #   40-59 secs      # => less than a minute
  38       #   60-89 secs      # => 1 minute
  39       #
  40       # ==== Examples
  41       #   from_time = Time.now
  42       #   distance_of_time_in_words(from_time, from_time + 50.minutes)        # => about 1 hour
  43       #   distance_of_time_in_words(from_time, 50.minutes.from_now)           # => about 1 hour
  44       #   distance_of_time_in_words(from_time, from_time + 15.seconds)        # => less than a minute
  45       #   distance_of_time_in_words(from_time, from_time + 15.seconds, true)  # => less than 20 seconds
  46       #   distance_of_time_in_words(from_time, 3.years.from_now)              # => over 3 years
  47       #   distance_of_time_in_words(from_time, from_time + 60.hours)          # => about 3 days
  48       #   distance_of_time_in_words(from_time, from_time + 45.seconds, true)  # => less than a minute
  49       #   distance_of_time_in_words(from_time, from_time - 45.seconds, true)  # => less than a minute
  50       #   distance_of_time_in_words(from_time, 76.seconds.from_now)           # => 1 minute
  51       #   distance_of_time_in_words(from_time, from_time + 1.year + 3.days)   # => about 1 year
  52       #   distance_of_time_in_words(from_time, from_time + 4.years + 9.days + 30.minutes + 5.seconds) # => over 4 years
  53       #
  54       #   to_time = Time.now + 6.years + 19.days
  55       #   distance_of_time_in_words(from_time, to_time, true)     # => over 6 years
  56       #   distance_of_time_in_words(to_time, from_time, true)     # => over 6 years
  57       #   distance_of_time_in_words(Time.now, Time.now)           # => less than a minute
  58       #
  59       def distance_of_time_in_words(from_time, to_time = 0, include_seconds = false, options = {})
  60         from_time = from_time.to_time if from_time.respond_to?(:to_time)
  61         to_time = to_time.to_time if to_time.respond_to?(:to_time)
  62         distance_in_minutes = (((to_time - from_time).abs)/60).round
  63         distance_in_seconds = ((to_time - from_time).abs).round
  64
  65         I18n.with_options :locale => options[:locale], :scope => :'datetime.distance_in_words' do |locale|
  66           case distance_in_minutes
  67             when 0..1
  68               return distance_in_minutes == 0 ?
  69                      locale.t(:less_than_x_minutes, :count => 1) :
  70                      locale.t(:x_minutes, :count => distance_in_minutes) unless include_seconds
  71
  72               case distance_in_seconds
  73                 when 0..4   then locale.t :less_than_x_seconds, :count => 5
  74                 when 5..9   then locale.t :less_than_x_seconds, :count => 10
  75                 when 10..19 then locale.t :less_than_x_seconds, :count => 20
  76                 when 20..39 then locale.t :half_a_minute
  77                 when 40..59 then locale.t :less_than_x_minutes, :count => 1
  78                 else             locale.t :x_minutes,           :count => 1
  79               end
  80
  81             when 2..44           then locale.t :x_minutes,      :count => distance_in_minutes
  82             when 45..89          then locale.t :about_x_hours,  :count => 1
  83             when 90..1439        then locale.t :about_x_hours,  :count => (distance_in_minutes.to_f / 60.0).round
  84             when 1440..2879      then locale.t :x_days,         :count => 1
  85             when 2880..43199     then locale.t :x_days,         :count => (distance_in_minutes / 1440).round
  86             when 43200..86399    then locale.t :about_x_months, :count => 1
  87             when 86400..525599   then locale.t :x_months,       :count => (distance_in_minutes / 43200).round
  88             when 525600..1051199 then locale.t :about_x_years,  :count => 1
  89             else                      locale.t :over_x_years,   :count => (distance_in_minutes / 525600).round
  90           end
  91         end
  92       end
  93
  94       # Like distance_of_time_in_words, but where <tt>to_time</tt> is fixed to <tt>Time.now</tt>.
  95       #
  96       # ==== Examples
  97       #   time_ago_in_words(3.minutes.from_now)       # => 3 minutes
  98       #   time_ago_in_words(Time.now - 15.hours)      # => 15 hours
  99       #   time_ago_in_words(Time.now)                 # => less than a minute
 100       #
 101       #   from_time = Time.now - 3.days - 14.minutes - 25.seconds     # => 3 days
 102       def time_ago_in_words(from_time, include_seconds = false)
 103         distance_of_time_in_words(from_time, Time.now, include_seconds)
 104       end
 105
 106       alias_method :distance_of_time_in_words_to_now, :time_ago_in_words
 107
 108       # Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based
 109       # attribute (identified by +method+) on an object assigned to the template (identified by +object+). You can
 110       # the output in the +options+ hash.
 111       #
 112       # ==== Options
 113       # * <tt>:use_month_numbers</tt> - Set to true if you want to use month numbers rather than month names (e.g.
 114       #    "2" instead of "February").
 115       # * <tt>:use_short_month</tt>   - Set to true if you want to use the abbreviated month name instead of the full
 116       #   name (e.g. "Feb" instead of "February").
 117       # * <tt>:add_month_number</tt>  - Set to true if you want to show both, the month's number and name (e.g.
 118       #   "2 - February" instead of "February").
 119       # * <tt>:use_month_names</tt>   - Set to an array with 12 month names if you want to customize month names.
 120       #   Note: You can also use Rails' new i18n functionality for this.
 121       # * <tt>:date_separator</tt>    - Specifies a string to separate the date fields. Default is "" (i.e. nothing).
 122       # * <tt>:start_year</tt>        - Set the start year for the year select. Default is <tt>Time.now.year - 5</tt>.
 123       # * <tt>:end_year</tt>          - Set the end year for the year select. Default is <tt>Time.now.year + 5</tt>.
 124       # * <tt>:discard_day</tt>       - Set to true if you don't want to show a day select. This includes the day
 125       #   as a hidden field instead of showing a select field. Also note that this implicitly sets the day to be the
 126       #   first of the given month in order to not create invalid dates like 31 February.
 127       # * <tt>:discard_month</tt>     - Set to true if you don't want to show a month select. This includes the month
 128       #   as a hidden field instead of showing a select field. Also note that this implicitly sets :discard_day to true.
 129       # * <tt>:discard_year</tt>      - Set to true if you don't want to show a year select. This includes the year
 130       #   as a hidden field instead of showing a select field.
 131       # * <tt>:order</tt>             - Set to an array containing <tt>:day</tt>, <tt>:month</tt> and <tt>:year</tt> do
 132       #   customize the order in which the select fields are shown. If you leave out any of the symbols, the respective
 133       #   select will not be shown (like when you set <tt>:discard_xxx => true</tt>. Defaults to the order defined in
 134       #   the respective locale (e.g. [:year, :month, :day] in the en locale that ships with Rails).
 135       # * <tt>:include_blank</tt>     - Include a blank option in every select field so it's possible to set empty
 136       #   dates.
 137       # * <tt>:default</tt>           - Set a default date if the affected date isn't set or is nil.
 138       # * <tt>:disabled</tt>          - Set to true if you want show the select fields as disabled.
 139       #
 140       # If anything is passed in the +html_options+ hash it will be applied to every select tag in the set.
 141       #
 142       # NOTE: Discarded selects will default to 1. So if no month select is available, January will be assumed.
 143       #
 144       # ==== Examples
 145       #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
 146       #   date_select("post", "written_on")
 147       #
 148       #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute,
 149       #   # with the year in the year drop down box starting at 1995.
 150       #   date_select("post", "written_on", :start_year => 1995)
 151       #
 152       #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute,
 153       #   # with the year in the year drop down box starting at 1995, numbers used for months instead of words,
 154       #   # and without a day select box.
 155       #   date_select("post", "written_on", :start_year => 1995, :use_month_numbers => true,
 156       #                                     :discard_day => true, :include_blank => true)
 157       #
 158       #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
 159       #   # with the fields ordered as day, month, year rather than month, day, year.
 160       #   date_select("post", "written_on", :order => [:day, :month, :year])
 161       #
 162       #   # Generates a date select that when POSTed is stored in the user variable, in the birthday attribute
 163       #   # lacking a year field.
 164       #   date_select("user", "birthday", :order => [:month, :day])
 165       #
 166       #   # Generates a date select that when POSTed is stored in the user variable, in the birthday attribute
 167       #   # which is initially set to the date 3 days from the current date
 168       #   date_select("post", "written_on", :default => 3.days.from_now)
 169       #
 170       #   # Generates a date select that when POSTed is stored in the credit_card variable, in the bill_due attribute
 171       #   # that will have a default day of 20.
 172       #   date_select("credit_card", "bill_due", :default => { :day => 20 })
 173       #
 174       # The selects are prepared for multi-parameter assignment to an Active Record object.
 175       #
 176       # Note: If the day is not included as an option but the month is, the day will be set to the 1st to ensure that
 177       # all month choices are valid.
 178       def date_select(object_name, method, options = {}, html_options = {})
 179         InstanceTag.new(object_name, method, self, options.delete(:object)).to_date_select_tag(options, html_options)
 180       end
 181
 182       # Returns a set of select tags (one for hour, minute and optionally second) pre-selected for accessing a
 183       # specified time-based attribute (identified by +method+) on an object assigned to the template (identified by
 184       # +object+). You can include the seconds with <tt>:include_seconds</tt>.
 185       #
 186       # This method will also generate 3 input hidden tags, for the actual year, month and day unless the option
 187       # <tt>:ignore_date</tt> is set to +true+.
 188       #
 189       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
 190       #
 191       # ==== Examples
 192       #   # Creates a time select tag that, when POSTed, will be stored in the post variable in the sunrise attribute
 193       #   time_select("post", "sunrise")
 194       #
 195       #   # Creates a time select tag that, when POSTed, will be stored in the order variable in the submitted
 196       #   # attribute
 197       #   time_select("order", "submitted")
 198       #
 199       #   # Creates a time select tag that, when POSTed, will be stored in the mail variable in the sent_at attribute
 200       #   time_select("mail", "sent_at")
 201       #
 202       #   # Creates a time select tag with a seconds field that, when POSTed, will be stored in the post variables in
 203       #   # the sunrise attribute.
 204       #   time_select("post", "start_time", :include_seconds => true)
 205       #
 206       #   # Creates a time select tag with a seconds field that, when POSTed, will be stored in the entry variables in
 207       #   # the submission_time attribute.
 208       #   time_select("entry", "submission_time", :include_seconds => true)
 209       #
 210       #   # You can set the :minute_step to 15 which will give you: 00, 15, 30 and 45.
 211       #   time_select 'game', 'game_time', {:minute_step => 15}
 212       #
 213       # The selects are prepared for multi-parameter assignment to an Active Record object.
 214       #
 215       # Note: If the day is not included as an option but the month is, the day will be set to the 1st to ensure that
 216       # all month choices are valid.
 217       def time_select(object_name, method, options = {}, html_options = {})
 218         InstanceTag.new(object_name, method, self, options.delete(:object)).to_time_select_tag(options, html_options)
 219       end
 220
 221       # Returns a set of select tags (one for year, month, day, hour, and minute) pre-selected for accessing a
 222       # specified datetime-based attribute (identified by +method+) on an object assigned to the template (identified
 223       # by +object+). Examples:
 224       #
 225       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
 226       #
 227       # ==== Examples
 228       #   # Generates a datetime select that, when POSTed, will be stored in the post variable in the written_on
 229       #   # attribute
 230       #   datetime_select("post", "written_on")
 231       #
 232       #   # Generates a datetime select with a year select that starts at 1995 that, when POSTed, will be stored in the
 233       #   # post variable in the written_on attribute.
 234       #   datetime_select("post", "written_on", :start_year => 1995)
 235       #
 236       #   # Generates a datetime select with a default value of 3 days from the current time that, when POSTed, will
 237       #   # be stored in the trip variable in the departing attribute.
 238       #   datetime_select("trip", "departing", :default => 3.days.from_now)
 239       #
 240       #   # Generates a datetime select that discards the type that, when POSTed, will be stored in the post variable
 241       #   # as the written_on attribute.
 242       #   datetime_select("post", "written_on", :discard_type => true)
 243       #
 244       # The selects are prepared for multi-parameter assignment to an Active Record object.
 245       def datetime_select(object_name, method, options = {}, html_options = {})
 246         InstanceTag.new(object_name, method, self, options.delete(:object)).to_datetime_select_tag(options, html_options)
 247       end
 248
 249       # Returns a set of html select-tags (one for year, month, day, hour, and minute) pre-selected with the
 250       # +datetime+. It's also possible to explicitly set the order of the tags using the <tt>:order</tt> option with
 251       # an array of symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in the desired order. If you do not
 252       # supply a Symbol, it will be appended onto the <tt>:order</tt> passed in. You can also add
 253       # <tt>:date_separator</tt>, <tt>:datetime_separator</tt> and <tt>:time_separator</tt> keys to the +options+ to
 254       # control visual display of the elements.
 255       #
 256       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
 257       #
 258       # ==== Examples
 259       #   my_date_time = Time.now + 4.days
 260       #
 261       #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
 262       #   select_datetime(my_date_time)
 263       #
 264       #   # Generates a datetime select that defaults to today (no specified datetime)
 265       #   select_datetime()
 266       #
 267       #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
 268       #   # with the fields ordered year, month, day rather than month, day, year.
 269       #   select_datetime(my_date_time, :order => [:year, :month, :day])
 270       #
 271       #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
 272       #   # with a '/' between each date field.
 273       #   select_datetime(my_date_time, :date_separator => '/')
 274       #
 275       #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
 276       #   # with a date fields separated by '/', time fields separated by '' and the date and time fields
 277       #   # separated by a comma (',').
 278       #   select_datetime(my_date_time, :date_separator => '/', :time_separator => '', :datetime_separator => ',')
 279       #
 280       #   # Generates a datetime select that discards the type of the field and defaults to the datetime in
 281       #   # my_date_time (four days after today)
 282       #   select_datetime(my_date_time, :discard_type => true)
 283       #
 284       #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
 285       #   # prefixed with 'payday' rather than 'date'
 286       #   select_datetime(my_date_time, :prefix => 'payday')
 287       #
 288       def select_datetime(datetime = Time.current, options = {}, html_options = {})
 289         DateTimeSelector.new(datetime, options, html_options).select_datetime
 290       end
 291
 292       # Returns a set of html select-tags (one for year, month, and day) pre-selected with the +date+.
 293       # It's possible to explicitly set the order of the tags using the <tt>:order</tt> option with an array of
 294       # symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in the desired order. If you do not supply a Symbol,
 295       # it will be appended onto the <tt>:order</tt> passed in.
 296       #
 297       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
 298       #
 299       # ==== Examples
 300       #   my_date = Time.today + 6.days
 301       #
 302       #   # Generates a date select that defaults to the date in my_date (six days after today)
 303       #   select_date(my_date)
 304       #
 305       #   # Generates a date select that defaults to today (no specified date)
 306       #   select_date()
 307       #
 308       #   # Generates a date select that defaults to the date in my_date (six days after today)
 309       #   # with the fields ordered year, month, day rather than month, day, year.
 310       #   select_date(my_date, :order => [:year, :month, :day])
 311       #
 312       #   # Generates a date select that discards the type of the field and defaults to the date in
 313       #   # my_date (six days after today)
 314       #   select_date(my_date, :discard_type => true)
 315       #
 316       #   # Generates a date select that defaults to the date in my_date,
 317       #   # which has fields separated by '/'
 318       #   select_date(my_date, :date_separator => '/')
 319       #
 320       #   # Generates a date select that defaults to the datetime in my_date (six days after today)
 321       #   # prefixed with 'payday' rather than 'date'
 322       #   select_date(my_date, :prefix => 'payday')
 323       #
 324       def select_date(date = Date.current, options = {}, html_options = {})
 325         DateTimeSelector.new(date, options, html_options).select_date
 326       end
 327
 328       # Returns a set of html select-tags (one for hour and minute)
 329       # You can set <tt>:time_separator</tt> key to format the output, and
 330       # the <tt>:include_seconds</tt> option to include an input for seconds.
 331       #
 332       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
 333       #
 334       # ==== Examples
 335       #   my_time = Time.now + 5.days + 7.hours + 3.minutes + 14.seconds
 336       #
 337       #   # Generates a time select that defaults to the time in my_time
 338       #   select_time(my_time)
 339       #
 340       #   # Generates a time select that defaults to the current time (no specified time)
 341       #   select_time()
 342       #
 343       #   # Generates a time select that defaults to the time in my_time,
 344       #   # which has fields separated by ':'
 345       #   select_time(my_time, :time_separator => ':')
 346       #
 347       #   # Generates a time select that defaults to the time in my_time,
 348       #   # that also includes an input for seconds
 349       #   select_time(my_time, :include_seconds => true)
 350       #
 351       #   # Generates a time select that defaults to the time in my_time, that has fields
 352       #   # separated by ':' and includes an input for seconds
 353       #   select_time(my_time, :time_separator => ':', :include_seconds => true)
 354       #
 355       def select_time(datetime = Time.current, options = {}, html_options = {})
 356         DateTimeSelector.new(datetime, options, html_options).select_time
 357       end
 358
 359       # Returns a select tag with options for each of the seconds 0 through 59 with the current second selected.
 360       # The <tt>second</tt> can also be substituted for a second number.
 361       # Override the field name using the <tt>:field_name</tt> option, 'second' by default.
 362       #
 363       # ==== Examples
 364       #   my_time = Time.now + 16.minutes
 365       #
 366       #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
 367       #   select_second(my_time)
 368       #
 369       #   # Generates a select field for seconds that defaults to the number given
 370       #   select_second(33)
 371       #
 372       #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
 373       #   # that is named 'interval' rather than 'second'
 374       #   select_second(my_time, :field_name => 'interval')
 375       #
 376       def select_second(datetime, options = {}, html_options = {})
 377         DateTimeSelector.new(datetime, options, html_options).select_second
 378       end
 379
 380       # Returns a select tag with options for each of the minutes 0 through 59 with the current minute selected.
 381       # Also can return a select tag with options by <tt>minute_step</tt> from 0 through 59 with the 00 minute
 382       # selected. The <tt>minute</tt> can also be substituted for a minute number.
 383       # Override the field name using the <tt>:field_name</tt> option, 'minute' by default.
 384       #
 385       # ==== Examples
 386       #   my_time = Time.now + 6.hours
 387       #
 388       #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
 389       #   select_minute(my_time)
 390       #
 391       #   # Generates a select field for minutes that defaults to the number given
 392       #   select_minute(14)
 393       #
 394       #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
 395       #   # that is named 'stride' rather than 'second'
 396       #   select_minute(my_time, :field_name => 'stride')
 397       #
 398       def select_minute(datetime, options = {}, html_options = {})
 399         DateTimeSelector.new(datetime, options, html_options).select_minute
 400       end
 401
 402       # Returns a select tag with options for each of the hours 0 through 23 with the current hour selected.
 403       # The <tt>hour</tt> can also be substituted for a hour number.
 404       # Override the field name using the <tt>:field_name</tt> option, 'hour' by default.
 405       #
 406       # ==== Examples
 407       #   my_time = Time.now + 6.hours
 408       #
 409       #   # Generates a select field for hours that defaults to the hour for the time in my_time
 410       #   select_hour(my_time)
 411       #
 412       #   # Generates a select field for hours that defaults to the number given
 413       #   select_hour(13)
 414       #
 415       #   # Generates a select field for hours that defaults to the minutes for the time in my_time
 416       #   # that is named 'stride' rather than 'second'
 417       #   select_hour(my_time, :field_name => 'stride')
 418       #
 419       def select_hour(datetime, options = {}, html_options = {})
 420         DateTimeSelector.new(datetime, options, html_options).select_hour
 421       end
 422
 423       # Returns a select tag with options for each of the days 1 through 31 with the current day selected.
 424       # The <tt>date</tt> can also be substituted for a hour number.
 425       # Override the field name using the <tt>:field_name</tt> option, 'day' by default.
 426       #
 427       # ==== Examples
 428       #   my_date = Time.today + 2.days
 429       #
 430       #   # Generates a select field for days that defaults to the day for the date in my_date
 431       #   select_day(my_time)
 432       #
 433       #   # Generates a select field for days that defaults to the number given
 434       #   select_day(5)
 435       #
 436       #   # Generates a select field for days that defaults to the day for the date in my_date
 437       #   # that is named 'due' rather than 'day'
 438       #   select_day(my_time, :field_name => 'due')
 439       #
 440       def select_day(date, options = {}, html_options = {})
 441         DateTimeSelector.new(date, options, html_options).select_day
 442       end
 443
 444       # Returns a select tag with options for each of the months January through December with the current month
 445       # selected. The month names are presented as keys (what's shown to the user) and the month numbers (1-12) are
 446       # used as values (what's submitted to the server). It's also possible to use month numbers for the presentation
 447       # instead of names -- set the <tt>:use_month_numbers</tt> key in +options+ to true for this to happen. If you
 448       # want both numbers and names, set the <tt>:add_month_numbers</tt> key in +options+ to true. If you would prefer
 449       # to show month names as abbreviations, set the <tt>:use_short_month</tt> key in +options+ to true. If you want
 450       # to use your own month names, set the <tt>:use_month_names</tt> key in +options+ to an array of 12 month names.
 451       # Override the field name using the <tt>:field_name</tt> option, 'month' by default.
 452       #
 453       # ==== Examples
 454       #   # Generates a select field for months that defaults to the current month that
 455       #   # will use keys like "January", "March".
 456       #   select_month(Date.today)
 457       #
 458       #   # Generates a select field for months that defaults to the current month that
 459       #   # is named "start" rather than "month"
 460       #   select_month(Date.today, :field_name => 'start')
 461       #
 462       #   # Generates a select field for months that defaults to the current month that
 463       #   # will use keys like "1", "3".
 464       #   select_month(Date.today, :use_month_numbers => true)
 465       #
 466       #   # Generates a select field for months that defaults to the current month that
 467       #   # will use keys like "1 - January", "3 - March".
 468       #   select_month(Date.today, :add_month_numbers => true)
 469       #
 470       #   # Generates a select field for months that defaults to the current month that
 471       #   # will use keys like "Jan", "Mar".
 472       #   select_month(Date.today, :use_short_month => true)
 473       #
 474       #   # Generates a select field for months that defaults to the current month that
 475       #   # will use keys like "Januar", "Marts."
 476       #   select_month(Date.today, :use_month_names => %w(Januar Februar Marts ...))
 477       #
 478       def select_month(date, options = {}, html_options = {})
 479         DateTimeSelector.new(date, options, html_options).select_month
 480       end
 481
 482       # Returns a select tag with options for each of the five years on each side of the current, which is selected.
 483       # The five year radius can be changed using the <tt>:start_year</tt> and <tt>:end_year</tt> keys in the
 484       # +options+. Both ascending and descending year lists are supported by making <tt>:start_year</tt> less than or
 485       # greater than <tt>:end_year</tt>. The <tt>date</tt> can also be substituted for a year given as a number.
 486       # Override the field name using the <tt>:field_name</tt> option, 'year' by default.
 487       #
 488       # ==== Examples
 489       #   # Generates a select field for years that defaults to the current year that
 490       #   # has ascending year values
 491       #   select_year(Date.today, :start_year => 1992, :end_year => 2007)
 492       #
 493       #   # Generates a select field for years that defaults to the current year that
 494       #   # is named 'birth' rather than 'year'
 495       #   select_year(Date.today, :field_name => 'birth')
 496       #
 497       #   # Generates a select field for years that defaults to the current year that
 498       #   # has descending year values
 499       #   select_year(Date.today, :start_year => 2005, :end_year => 1900)
 500       #
 501       #   # Generates a select field for years that defaults to the year 2006 that
 502       #   # has ascending year values
 503       #   select_year(2006, :start_year => 2000, :end_year => 2010)
 504       #
 505       def select_year(date, options = {}, html_options = {})
 506         DateTimeSelector.new(date, options, html_options).select_year
 507       end
 508     end
 509
 510     class DateTimeSelector #:nodoc:
 511       extend ActiveSupport::Memoizable
 512       include ActionView::Helpers::TagHelper
 513
 514       DEFAULT_PREFIX = 'date'.freeze unless const_defined?('DEFAULT_PREFIX')
 515       POSITION = {
 516         :year => 1, :month => 2, :day => 3, :hour => 4, :minute => 5, :second => 6
 517       }.freeze unless const_defined?('POSITION')
 518
 519       def initialize(datetime, options = {}, html_options = {})
 520         @options      = options.dup
 521         @html_options = html_options.dup
 522         @datetime     = datetime
 523       end
 524
 525       def select_datetime
 526         # TODO: Remove tag conditional
 527         # Ideally we could just join select_date and select_date for the tag case
 528         if @options[:tag] && @options[:ignore_date]
 529           select_time
 530         elsif @options[:tag]
 531           order = date_order.dup
 532           order -= [:hour, :minute, :second]
 533
 534           @options[:discard_year]   ||= true unless order.include?(:year)
 535           @options[:discard_month]  ||= true unless order.include?(:month)
 536           @options[:discard_day]    ||= true if @options[:discard_month] || !order.include?(:day)
 537           @options[:discard_minute] ||= true if @options[:discard_hour]
 538           @options[:discard_second] ||= true unless @options[:include_seconds] && !@options[:discard_minute]
 539
 540           # If the day is hidden and the month is visible, the day should be set to the 1st so all month choices are
 541           # valid (otherwise it could be 31 and february wouldn't be a valid date)
 542           if @datetime && @options[:discard_day] && !@options[:discard_month]
 543             @datetime = @datetime.change(:day => 1)
 544           end
 545
 546           [:day, :month, :year].each { |o| order.unshift(o) unless order.include?(o) }
 547           order += [:hour, :minute, :second] unless @options[:discard_hour]
 548
 549           build_selects_from_types(order)
 550         else
 551           "#{select_date}#{@options[:datetime_separator]}#{select_time}"
 552         end
 553       end
 554
 555       def select_date
 556         order = date_order.dup
 557
 558         # TODO: Remove tag conditional
 559         if @options[:tag]
 560           @options[:discard_hour]     = true
 561           @options[:discard_minute]   = true
 562           @options[:discard_second]   = true
 563
 564           @options[:discard_year]   ||= true unless order.include?(:year)
 565           @options[:discard_month]  ||= true unless order.include?(:month)
 566           @options[:discard_day]    ||= true if @options[:discard_month] || !order.include?(:day)
 567
 568           # If the day is hidden and the month is visible, the day should be set to the 1st so all month choices are
 569           # valid (otherwise it could be 31 and february wouldn't be a valid date)
 570           if @datetime && @options[:discard_day] && !@options[:discard_month]
 571             @datetime = @datetime.change(:day => 1)
 572           end
 573         end
 574
 575         [:day, :month, :year].each { |o| order.unshift(o) unless order.include?(o) }
 576
 577         build_selects_from_types(order)
 578       end
 579
 580       def select_time
 581         order = []
 582
 583         # TODO: Remove tag conditional
 584         if @options[:tag]
 585           @options[:discard_month]    = true
 586           @options[:discard_year]     = true
 587           @options[:discard_day]      = true
 588           @options[:discard_second] ||= true unless @options[:include_seconds]
 589
 590           order += [:year, :month, :day] unless @options[:ignore_date]
 591         end
 592
 593         order += [:hour, :minute]
 594         order << :second if @options[:include_seconds]
 595
 596         build_selects_from_types(order)
 597       end
 598
 599       def select_second
 600         if @options[:use_hidden] || @options[:discard_second]
 601           build_hidden(:second, sec) if @options[:include_seconds]
 602         else
 603           build_options_and_select(:second, sec)
 604         end
 605       end
 606
 607       def select_minute
 608         if @options[:use_hidden] || @options[:discard_minute]
 609           build_hidden(:minute, min)
 610         else
 611           build_options_and_select(:minute, min, :step => @options[:minute_step])
 612         end
 613       end
 614
 615       def select_hour
 616         if @options[:use_hidden] || @options[:discard_hour]
 617           build_hidden(:hour, hour)
 618         else
 619           build_options_and_select(:hour, hour, :end => 23)
 620         end
 621       end
 622
 623       def select_day
 624         if @options[:use_hidden] || @options[:discard_day]
 625           build_hidden(:day, day)
 626         else
 627           build_options_and_select(:day, day, :start => 1, :end => 31, :leading_zeros => false)
 628         end
 629       end
 630
 631       def select_month
 632         if @options[:use_hidden] || @options[:discard_month]
 633           build_hidden(:month, month)
 634         else
 635           month_options = []
 636           1.upto(12) do |month_number|
 637             options = { :value => month_number }
 638             options[:selected] = "selected" if month == month_number
 639             month_options << content_tag(:option, month_name(month_number), options) + "\n"
 640           end
 641           build_select(:month, month_options.join)
 642         end
 643       end
 644
 645       def select_year
 646         if !@datetime || @datetime == 0
 647           val = ''
 648           middle_year = Date.today.year
 649         else
 650           val = middle_year = year
 651         end
 652
 653         if @options[:use_hidden] || @options[:discard_year]
 654           build_hidden(:year, val)
 655         else
 656           options                 = {}
 657           options[:start]         = @options[:start_year] || middle_year - 5
 658           options[:end]           = @options[:end_year] || middle_year + 5
 659           options[:step]          = options[:start] < options[:end] ? 1 : -1
 660           options[:leading_zeros] = false
 661
 662           build_options_and_select(:year, val, options)
 663         end
 664       end
 665
 666       private
 667         %w( sec min hour day month year ).each do |method|
 668           define_method(method) do
 669             @datetime.kind_of?(Fixnum) ? @datetime : @datetime.send(method) if @datetime
 670           end
 671         end
 672
 673         # Returns translated month names, but also ensures that a custom month
 674         # name array has a leading nil element
 675         def month_names
 676           month_names = @options[:use_month_names] || translated_month_names
 677           month_names.unshift(nil) if month_names.size < 13
 678           month_names
 679         end
 680         memoize :month_names
 681
 682         # Returns translated month names
 683         #  => [nil, "January", "February", "March",
 684         #           "April", "May", "June", "July",
 685         #           "August", "September", "October",
 686         #           "November", "December"]
 687         #
 688         # If :use_short_month option is set
 689         #  => [nil, "Jan", "Feb", "Mar", "Apr", "May", "Jun",
 690         #           "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
 691         def translated_month_names
 692           begin
 693             key = @options[:use_short_month] ? :'date.abbr_month_names' : :'date.month_names'
 694             I18n.translate(key, :locale => @options[:locale])
 695           end
 696         end
 697
 698         # Lookup month name for number
 699         #  month_name(1) => "January"
 700         #
 701         # If :use_month_numbers option is passed
 702         #  month_name(1) => 1
 703         #
 704         # If :add_month_numbers option is passed
 705         #  month_name(1) => "1 - January"
 706         def month_name(number)
 707           if @options[:use_month_numbers]
 708             number
 709           elsif @options[:add_month_numbers]
 710             "#{number} - #{month_names[number]}"
 711           else
 712             month_names[number]
 713           end
 714         end
 715
 716         def date_order
 717           @options[:order] || translated_date_order
 718         end
 719         memoize :date_order
 720
 721         def translated_date_order
 722           begin
 723             I18n.translate(:'date.order', :locale => @options[:locale]) || []
 724           end
 725         end
 726
 727         # Build full select tag from date type and options
 728         def build_options_and_select(type, selected, options = {})
 729           build_select(type, build_options(selected, options))
 730         end
 731
 732         # Build select option html from date value and options
 733         #  build_options(15, :start => 1, :end => 31)
 734         #  => "<option value="1">1</option>
 735         #      <option value=\"2\">2</option>
 736         #      <option value=\"3\">3</option>..."
 737         def build_options(selected, options = {})
 738           start         = options.delete(:start) || 0
 739           stop          = options.delete(:end) || 59
 740           step          = options.delete(:step) || 1
 741           leading_zeros = options.delete(:leading_zeros).nil? ? true : false
 742
 743           select_options = []
 744           start.step(stop, step) do |i|
 745             value = leading_zeros ? sprintf("%02d", i) : i
 746             tag_options = { :value => value }
 747             tag_options[:selected] = "selected" if selected == i
 748             select_options << content_tag(:option, value, tag_options)
 749           end
 750           select_options.join("\n") + "\n"
 751         end
 752
 753         # Builds select tag from date type and html select options
 754         #  build_select(:month, "<option value="1">January</option>...")
 755         #  => "<select id="post_written_on_2i" name="post[written_on(2i)]">
 756         #        <option value="1">January</option>...
 757         #      </select>"
 758         def build_select(type, select_options_as_html)
 759           select_options = {
 760             :id => input_id_from_type(type),
 761             :name => input_name_from_type(type)
 762           }.merge(@html_options)
 763           select_options.merge!(:disabled => 'disabled') if @options[:disabled]
 764
 765           select_html = "\n"
 766           select_html << content_tag(:option, '', :value => '') + "\n" if @options[:include_blank]
 767           select_html << select_options_as_html.to_s
 768
 769           content_tag(:select, select_html, select_options) + "\n"
 770         end
 771
 772         # Builds hidden input tag for date part and value
 773         #  build_hidden(:year, 2008)
 774         #  => "<input id="post_written_on_1i" name="post[written_on(1i)]" type="hidden" value="2008" />"
 775         def build_hidden(type, value)
 776           tag(:input, {
 777             :type => "hidden",
 778             :id => input_id_from_type(type),
 779             :name => input_name_from_type(type),
 780             :value => value
 781           }) + "\n"
 782         end
 783
 784         # Returns the name attribute for the input tag
 785         #  => post[written_on(1i)]
 786         def input_name_from_type(type)
 787           prefix = @options[:prefix] || ActionView::Helpers::DateTimeSelector::DEFAULT_PREFIX
 788           prefix += "[#{@options[:index]}]" if @options[:index]
 789
 790           field_name = @options[:field_name] || type
 791           if @options[:include_position]
 792             field_name += "(#{ActionView::Helpers::DateTimeSelector::POSITION[type]}i)"
 793           end
 794
 795           @options[:discard_type] ? prefix : "#{prefix}[#{field_name}]"
 796         end
 797
 798         # Returns the id attribute for the input tag
 799         #  => "post_written_on_1i"
 800         def input_id_from_type(type)
 801           input_name_from_type(type).gsub(/([\[\(])|(\]\[)/, '_').gsub(/[\]\)]/, '')
 802         end
 803
 804         # Given an ordering of datetime components, create the selection html
 805         # and join them with their appropriate seperators
 806         def build_selects_from_types(order)
 807           select = ''
 808           order.reverse.each do |type|
 809             separator = separator(type) unless type == order.first # don't add on last field
 810             select.insert(0, separator.to_s + send("select_#{type}").to_s)
 811           end
 812           select
 813         end
 814
 815         # Returns the separator for a given datetime component
 816         def separator(type)
 817           case type
 818             when :month, :day
 819               @options[:date_separator]
 820             when :hour
 821               (@options[:discard_year] && @options[:discard_day]) ? "" : @options[:datetime_separator]
 822             when :minute
 823               @options[:time_separator]
 824             when :second
 825               @options[:include_seconds] ? @options[:time_separator] : ""
 826           end
 827         end
 828     end
 829
 830     class InstanceTag #:nodoc:
 831       def to_date_select_tag(options = {}, html_options = {})
 832         datetime_selector(options, html_options).select_date
 833       end
 834
 835       def to_time_select_tag(options = {}, html_options = {})
 836         datetime_selector(options, html_options).select_time
 837       end
 838
 839       def to_datetime_select_tag(options = {}, html_options = {})
 840         datetime_selector(options, html_options).select_datetime
 841       end
 842
 843       private
 844         def datetime_selector(options, html_options)
 845           datetime = value(object) || default_datetime(options)
 846
 847           options = options.dup
 848           options[:field_name]           = @method_name
 849           options[:include_position]     = true
 850           options[:prefix]             ||= @object_name
 851           options[:index]              ||= @auto_index
 852           options[:datetime_separator] ||= ' &mdash; '
 853           options[:time_separator]     ||= ' : '
 854
 855           DateTimeSelector.new(datetime, options.merge(:tag => true), html_options)
 856         end
 857
 858         def default_datetime(options)
 859           return if options[:include_blank]
 860
 861           case options[:default]
 862             when nil
 863               Time.current
 864             when Date, Time
 865               options[:default]
 866             else
 867               default = options[:default].dup
 868
 869               # Rename :minute and :second to :min and :sec
 870               default[:min] ||= default[:minute]
 871               default[:sec] ||= default[:second]
 872
 873               time = Time.current
 874
 875               [:year, :month, :day, :hour, :min, :sec].each do |key|
 876                 default[key] ||= time.send(key)
 877               end
 878
 879               Time.utc_time(
 880                 default[:year], default[:month], default[:day],
 881                 default[:hour], default[:min], default[:sec]
 882               )
 883           end
 884         end
 885     end
 886
 887     class FormBuilder
 888       def date_select(method, options = {}, html_options = {})
 889         @template.date_select(@object_name, method, options.merge(:object => @object), html_options)
 890       end
 891
 892       def time_select(method, options = {}, html_options = {})
 893         @template.time_select(@object_name, method, options.merge(:object => @object), html_options)
 894       end
 895
 896       def datetime_select(method, options = {}, html_options = {})
 897         @template.datetime_select(@object_name, method, options.merge(:object => @object), html_options)
 898       end
 899     end
 900   end
 901 end