= ValidatesTimeliness

* Source:  http://github.com/adzap/validates_timeliness
* Bugs:    http://github.com/adzap/validates_timeliness/issues

== Description

Validate dates, times and datetimes for Rails 3.x and ActiveModel.

If you a looking for the old version for Rails 2.x go here[http://github.com/adzap/validates_timeliness/tree/v2.3].


== Features

* Adds ActiveModel validation for dates, times and datetimes

* Should work with any ORM using ActiveModel

* Supports timezone handling

* Supports I18n for the error messages

* Adds before_type_cast method on validated attributes, if ORM supports it.


== Installation

As plugin (from master)

  rails plugin install git://github.com/adzap/validates_timeliness.git

As gem (not working as yet)

  # in Gemfile
  gem 'validates_timeliness'

  # Run bundler
  $ bundle install

Then run
  
  $ rails generate validates_timeliness:install

This creates configuration initializer and locale files. In the initializer, you there are a number of config options to customize the plugin.

  ValidatesTimeliness.setup do |config|

    # Add plugin to supported ORMs (only :active_record for now)
    # config.extend_orms = [ :active_record ]

  end

By default the plugin extends ActiveRecord if present. Currently ActiveRecord is the only ORM included for extension. If you wish to extend
another ORM then look at the {wiki page}[http://github.com/adzap/validates_timeliness/wiki/ORM-Support] for more information.

To extend other ORMs is pretty straight forward. It's matter of hooking into a couple of methods, being the attribute method generation and 
timezone handling of validated attributes. However, the plugin must support the ActiveModel validations system. If you extend an ORM 
successfully, please send me a pull request to add the shim to the plugin or let me know where to find it.


== Usage:

To validate a model with a date, time or datetime attribute you just use the
validation method

  class Person < ActiveRecord::Base
    validates_date :date_of_birth, :on_or_before => lambda { Date.today }
    # or
    validates :date_of_birth, :timeliness => {:on_or_before => lambda { Date.today }, :type => date}
  end

  # or even on a specific record, per ActiveModel API.

  @person.validates_date :date_of_birth, :on_or_before => lambda { Date.today }


The list of validation methods available are as follows:
  validates_date     - validate value as date
  validates_time     - validate value as time only i.e. '12:20pm'
  validates_datetime - validate value as a full date and time
  validates          - use the :timeliness key and set the type in the hash.

The validation methods take the usual options plus some specific ones to restrict
the valid range of dates or times allowed

Temporal options (or restrictions):
  :is_at        - Attribute must be equal to value to be valid
  :before       - Attribute must be before this value to be valid
  :on_or_before - Attribute must be equal to or before this value to be valid
  :after        - Attribute must be after this value to be valid
  :on_or_after  - Attribute must be equal to or after this value to be valid
  :between      - Attribute must be between the values to be valid. Range or Array of 2 values. 
                  Uses :on_or_after and :on_of_before for error messages on lower and upper bounds respectively.

Regular validation options:
  :allow_nil    - Allow a nil value to be valid
  :allow_blank  - Allows a nil or empty string value to be valid
  :if           - Execute validation when :if evaluates true
  :unless       - Execute validation when :unless evaluates false

Special options:
  :ignore_usec  - Ignores microsecond value on datetime restrictions
  :format       - Limit validation to a single format for special cases. Requires plugin parser.

The temporal restrictions can take 4 different value types:

* Date, Time, or DateTime object value
* Proc or lambda object which may take an optional parameter, being the record object
* A symbol matching a method name in the model
* String value

When an attribute value is compared to temporal restrictions, they are compared as
the same type as the validation method type. So using validates_date means all
values are compared as dates.


== Configuration

=== Error Messages

Using the I18n system to define new defaults:

  en:
    errors:
      messages:
        invalid_date: "is not a valid date"
        invalid_time: "is not a valid time"
        invalid_datetime: "is not a valid datetime"
        is_at: "must be at %{restriction}"
        before: "must be before %{restriction}"
        on_or_before: "must be on or before %{restriction}"
        after: "must be after %{restriction}"
        on_or_after: "must be on or after %{restriction}"

The %{restriction} signifies where the interpolation value for the restriction will be inserted.

You can also use validation options for custom error messages. The following option keys are available:

    :invalid_date_message
    :invalid_time_message
    :invalid_datetime_message
    :is_at_message
    :before_message
    :on_or_before_message
    :after_message
    :on_or_after_message

Note: There is no :between_message option. The between error message should be defined using the :on_or_before and :on_or_after messages.

It is highly recommended you use the I18n system for error messages.


=== Plugin Parser

The plugin comes with a customisable date and time parser. You can add or remove valid formats
for dates, times, and datetimes. It is also more strict than the Ruby parser, which means it 
won't accept day of the month if it's not a valid number for that month.

By default the parser is switched off. To switch it on:

  # in the setup block
  config.use_plugin_parser = true

See the wiki[http://github.com/adzap/validates_timeliness/wiki/Plugin-Parser] for all the details about the parser.


=== Restriction Option Shorthand

It is common to restrict an attribute to being on or before the current time or current day. 
To specify this you need to use a lambda as an option value e.g. <tt>lambda { Time.now }</tt>.
This can be tedious noise amongst your validations for something so common. To combat this the
plugin allows you to use shorthand symbols for often used relative times or dates.

Just provide the symbol as the option value like so:

  validates_date :birth_date, :on_or_before => :today

The :today symbol is evaluated as <tt>lambda { Date.today }</tt>. The :now and :today
symbols are pre-configured. Configure your own like so:

  # in the setup block
  config.restriction_shorthand_symbols.update(
    :yesterday => lambda { 1.day.ago }
  )


=== Default Timezone

The plugin needs to know the default timezone you are using when parsing or type casting values. If you are using
ActiveRecord then the default is automatically set to the same default zone as ActiveRecord. If you are using 
another ORM you may need to change this setting.

  # in the setup block
  config.default_timezone = :utc

By default it will be UTC if ActiveRecord is not loaded.


=== Dummy Date For Time Types

Given that Ruby has no support for a time-only type, all time type columns are evaluated
as a regular Time class objects with a dummy date value set. Rails defines the dummy date as
2000-01-01. So a time of '12:30' is evaluated as a Time value of '2000-01-01 12:30'. If you
need to customize this for some reason you can do so as follows

  # in the setup block
  config.dummy_date_for_time_type = [2009, 1, 1]

The value should be an array of 3 values being year, month and day in that order.


=== Temporal Restriction Errors

When using the validation temporal restrictions there are times when the restriction
option value itself may be invalid. This will add an error to the model such as
'Error occurred validating birth_date for :before restriction'. These can be annoying
in development or production as you most likely just want to skip the option if no
valid value was returned. By default these errors are displayed in Rails test mode.

To turn them on/off:

  # in the setup block
  config.ignore_restriction_errors = true


=== Display Invalid Values in Select Helpers

The plugin offers an extension for ActionView to allowing invalid
date and time values to be redisplayed to the user as feedback, instead of
a blank field which happens by default in Rails. Though the date helpers make this a
pretty rare occurrence, given the select dropdowns for each date/time component, but
it may be something of interest.

To activate it, put this in an initializer:

  # in the setup block
  config.enable_date_time_select_extension!


=== Strict Parsing for Select Helpers

When using date/time select helpers, the component values are handled by ActiveRecord using
the Time class to instantiate them into a time value. But this mean that some invalid dates,
such as 31st June, are shifted forward and treated as valid. To handle these cases in a strict
way you can enable the plugin handler to treat them as invalid dates.

To activate it, put this in an initializer:

  # in the setup block
  config.enable_multiparameter_extension!


== Credits

* Adam Meehan (adam.meehan@gmail.com, http://github.com/adzap)


== License

Copyright (c) 2008-2010 Adam Meehan, released under the MIT license