mirror of
https://github.com/ditkrg/validates_timeliness.git
synced 2026-01-22 22:06:45 +00:00
252 lines
8.3 KiB
Plaintext
252 lines
8.3 KiB
Plaintext
= validates_timeliness
|
|
|
|
* Source: http://github.com/adzap/validates_timeliness
|
|
* Tickets: http://adzap.lighthouseapp.com/projects/14111-validates_timeliness
|
|
|
|
== DESCRIPTION:
|
|
|
|
Validate dates, times and datetimes for Rails 2.x. Plays nicely with new
|
|
features such as automatic timezone handling and dirty attributes. Allows
|
|
date/time atttributes to behave like other attribute types by allowing you to
|
|
review the raw entered value before it is converted.
|
|
|
|
Allows you add custom formats or remove defaults easily. You can also just use
|
|
another date parser altogther in conjuction with the plugin.
|
|
|
|
|
|
== FEATURES:
|
|
|
|
* Adds ActiveRecord validation for dates, times and datetimes
|
|
|
|
* Add or remove date/time formats to customize validation
|
|
|
|
* Create new formats using very simple date/time format patterns
|
|
|
|
* Adds better transparency of date/time attributes restoring ability to view
|
|
raw value before type casting, which was lost in Rails 2.1.
|
|
|
|
* Allows pluggable date and time parsing with other parsers of your choosing (eg Chronic)
|
|
|
|
* Respects new timezone features of Rails 2.1.
|
|
|
|
|
|
== INSTALLATION:
|
|
|
|
Rails 2.1
|
|
./script/plugin git://github.com/adzap/validates_timeliness
|
|
|
|
Rails 2.0
|
|
# TODO: best practice for git with Rails 2.0?
|
|
|
|
|
|
== 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
|
|
|
|
end
|
|
|
|
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
|
|
|
|
The validation methods take the usual options plus some specific ones to restrict
|
|
the valid range of dates or times allowed
|
|
|
|
Temporal options:
|
|
|
|
: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
|
|
|
|
Regular validation options:
|
|
|
|
:allow_nil - Allow a nil value to be valid
|
|
:allow_blank - Allows a nil or empty string value to be valid
|
|
|
|
The temporal options can take 4 different value types:
|
|
|
|
* String date or time value
|
|
* Date, Time, or DateTime object value
|
|
* Proc or lambda object
|
|
* A symbol matching the method name in the model
|
|
|
|
When values are compared for temporal options, they are compared as the same type
|
|
as the validation method type. So validates_date means all values are compared
|
|
as dates.
|
|
|
|
== EXAMPLES:
|
|
|
|
validates_date :date_of_birth, :on_or_after => '1900-01-01',
|
|
:before => Date.new(1980, 1, 1)
|
|
|
|
validates_time :breakfast_time, :on_or_after => '6:00am',
|
|
:before => :second_breakfast_time
|
|
|
|
validates_datetime :appointment_date, :before => Proc.new { 1.week.from_now }
|
|
|
|
|
|
=== DATE/TIME FORMATS:
|
|
|
|
So what formats does the plugin allow. Well there are default formats which can
|
|
be added to easily using the plugins format rules. Also formats can be easily
|
|
removed without hacking the plugin at all.
|
|
|
|
Below are the default formats. If you think they are easy to read then you will
|
|
be happy to know that is exactly the format you can use to define your own if
|
|
you want. No regular expressions or duck punching (monkey patching) the plugin.
|
|
|
|
Time formats:
|
|
hh:nn:ss => 01:23:59
|
|
hh-nn-ss => 01:23:59
|
|
h:nn => 1:23 or 01:23
|
|
h.nn => 1.23 or 01.23
|
|
h nn => 1 23 or 01 23
|
|
h-nn => 1-23 or 01-23
|
|
h:nn_ampm => 1:23am or 1:23 am or 01:23am
|
|
h.nn_ampm
|
|
h nn_ampm
|
|
h-nn_ampm
|
|
h_ampm
|
|
|
|
NOTE: Any time format without a ampm token or meridian is considered in 24 hour time.
|
|
|
|
Date formats:
|
|
yyyy/mm/dd
|
|
yyyy-mm-dd
|
|
yyyy.mm.dd
|
|
m/d/yy OR d/m/yy
|
|
m\d\yy OR d\m\yy
|
|
d-m-yy
|
|
d.m.yy
|
|
d mmm yy
|
|
|
|
NOTE: to switch to using non-US date formats see US/EURO FORMATS section
|
|
|
|
Datetime formats:
|
|
m/d/yy h:nn:ss OR d/m/yy hh:nn:ss
|
|
m/d/yy h:nn OR d/m/yy h:nn
|
|
m/d/yy h:nn_ampm OR d/m/yy h:nn_ampm
|
|
yyyy-mm-dd hh:nn:ss
|
|
yyyy-mm-dd h:nn
|
|
ddd mmm d hh:nn:ss zo yyyy # Ruby time string
|
|
yyyy-mm-ddThh:nn:ss(?:Z|zo) # ISO 8601
|
|
|
|
NOTE: to switch to using non-US date formats see US/EURO FORMATS section
|
|
|
|
Here is what each format token means:
|
|
|
|
Format tokens:
|
|
y = year
|
|
m = month
|
|
d = day
|
|
h = hour
|
|
n = minute
|
|
s = second
|
|
u = micro-seconds
|
|
ampm = meridian (am or pm) with or without dots (e.g. am, a.m, or a.m.)
|
|
_ = optional space
|
|
tz = Timezone abbreviation (e.g. UTC, GMT, PST, EST)
|
|
zo = Timezone offset (e.g. +10:00, -08:00, +1000)
|
|
|
|
All other characters are considered literal. You can embed regular expressions
|
|
in the format but no gurantees that it will remain intact. If you avoid the use
|
|
of any token characters and regexp dots or backslashes as special characters
|
|
in the regexp, it may well work as expected. For special characters use
|
|
POSIX character clsses for safety. See the ISO 8601 datetime for en example of
|
|
of an embedded regular expression.
|
|
|
|
Repeating tokens:
|
|
x = 1 or 2 digits for unit (e.g. 'h' means an hour can be '9' or '09')
|
|
xx = 2 digits exactly for unit (e.g. 'hh' means an hour can only be '09')
|
|
|
|
Special Cases:
|
|
yy = 2 or 4 digit year
|
|
yyyyy = exactly 4 digit year
|
|
mmm = month long name (e.g. 'Jul' or 'July')
|
|
ddd = Day name of 3 to 9 letters (e.g. Wed or Wednesday)
|
|
u = microseconds matches 1 to 3 digits
|
|
|
|
For the technically minded (well you are developers), these formats are compiled
|
|
into regular expressions at runtime so don't add any extra overhead than using
|
|
regular expressions directly. So, no, it won't make your app slow!
|
|
|
|
To see all defined formats look in the lib/validates_timeliness/formats.rb.
|
|
|
|
=== US/EURO FORMATS
|
|
|
|
The perenial problem for non-US develops or applications not primarily for the
|
|
US, is the US date format of m/d/yy. This is ambiguous with the European format
|
|
of d/my/yy. By default the plugin uses the US formats as this is the Ruby default
|
|
when it does date interpretation, and is in keeping PoLS (principle of least
|
|
surprise).
|
|
|
|
To switch to using the European (or Rest of The World) formats put this in an
|
|
initializer or environment.rb
|
|
|
|
ValidatesTimeliness::Formats.remove_us_formats
|
|
|
|
Now '01/02/2000' will be parsed as 1st February 2000, instead of 2nd January 2000.
|
|
|
|
=== CUSTOMISING FORMATS:
|
|
|
|
I hear you say "Thats greats but I don't want X format to be valid". Well to
|
|
remove a format stick this in an initializer file or environment.rb
|
|
|
|
ValidatesTimeliness::Formats.remove_formats(:date, 'm\d\yy')
|
|
|
|
Done! That format is no longer considered valid. Easy!
|
|
|
|
Ok, now I hear you say "Well I have format that I want to use but you don't have it".
|
|
Ahh, then add it yourself. Again stick this in an initializer file or environment.rb.
|
|
|
|
ValidatesTimeliness::Formats.add_formats(:time, "d o'clock")
|
|
|
|
Now '10 o'clock' will be a valid value. So easy, no more whingeing!
|
|
|
|
Because formats are evaluated in order, adding a format which may be ambiguous
|
|
with an existing format, will mean your format is ignored. If you need to make
|
|
your new format higher precedence than an existing format, you can include the
|
|
before option like so
|
|
|
|
ValidatesTimeliness::Formats.add_formats(:time, 'ss:nn:hh', :before => 'hh:nn:ss')
|
|
|
|
Now a time of '59:30:23' will be interpreted as 11:30:59 pm. This option saves
|
|
you adding a new one and deleting an old one to get it to work.
|
|
|
|
=== EXTERNAL PARSER:
|
|
|
|
I mentioned earlier that you could use a pluggable or alternative parser such
|
|
as Chronic instead of the in built one. So if you need some super fancy stuff that
|
|
the plugin custom formats can't handle, then be my guest and override it. This is
|
|
an example of using Chronis instead. Put this into a file in the lib directory.
|
|
|
|
class ActiveRecord::Base
|
|
|
|
def self.parse_date_time(raw_value, type)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
== CREDITS:
|
|
|
|
* Adam Meehan (adam.meehan@gmail.com, http://duckpunching.com/)
|
|
|
|
* Jonathan Viney (http://workingwithrails.com/person/4985-jonathan-viney)
|
|
For his validates_date_time plugin which I have used before this plugin and
|
|
which influenced some of the design and I borrowed a little of code from it.
|
|
|
|
|
|
== LICENSE:
|
|
|
|
Copyright (c) 2008 Adam Meehan, released under the MIT license
|