mirror of
https://github.com/ditkrg/validates_timeliness.git
synced 2026-01-22 22:06:45 +00:00
261 lines
9.1 KiB
Plaintext
261 lines
9.1 KiB
Plaintext
= 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 (in beta)
|
|
|
|
# in Gemfile
|
|
gem 'validates_timeliness', '3.0.0.beta'
|
|
|
|
# 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
|