Greenwich...
...has been helping Rails developers work with custom time zones since 2011.
Rails 2.1 brought much-needed improvements to working with time zones in Rails. But even now, with Rails 3 out and kicking ass, allowing users to specify the time zone they would like to use for a given date is still a PITA.
Enter Greenwich
You too can now give your users the POWER of choosing a time zone via a standard web form. Maybe you have a system that allows people to enter appointments for Widgets, Inc. Since they make the best widgets in the world, they're very popular internationally. You would like a system which allows your users to enter not just the time of an appointment but also the time zone in which the appointment is located.
Still interested? Read on intrepid traveler.
Installation
gem install greenwich
Initialization
You add Greenwich to your models like so:
time_with_time_zone :your_column_name_utc
By default, Greenwich removes the _utc
from the column name and uses
the resulting string as the composed field.
For example, the above call would result in a composed field called
your_column_name
.
Time Zones
Greenwich will try to use convention to choose a time zone column name based on the time field you choose.
time_with_time_zone :started_at_utc
Will look for a column called started_at_time_zone
which contains the
time zone for the time field.
Custom Time Zone
If you want to use the same time zone for multiple time fields or just
don't like the custom one we choose for you, you can pass a :time_zone
option which will override our default.
time_with_time_zone :started_at_utc, :time_zone => :started_at_zone
Will tell Greenwich that when the user accesses the started_at
method,
it will use the information from the started_at_zone
column for its
time zone.
Convention... but missing a little configuration
We're on v1.0.0
and have more features planned in the future, however
for now, all columns passed to time_with_time_zone
must end in _utc
.
Usage
Note: These examples assume the application's default time zone is set to UTC. If you have modified the default time zone, directly accessing your DateTime field will render it in that time zone and not UTC.
When working with your instances, Greenwich will convert to the proper time zone when you access it. So if you've defined a Greenwich time field like this:
time_with_time_zone :started_at_utc
And if you've previously saved a DateTime like this:
my_model.started_at_utc = Time.utc(2011, 7, 4, 13, 0, 0)
my_model.started_at_time_zone = 'Alaska'
Then that will result in your model returning the following values (assuming these particular columns exist in the database):
my_model.started_at_utc # => ActiveSupport::TimeWithZone 2011-07-04 13:00:00 UTC
my_model.started_at_time_zone # => ActiveSupport::TimeZone 'Alaska'
Whereas asking Greenwich for the value of started_at
will result in:
my_model.started_at # => ActiveSupport::TimeWithZone 2011-07-04 04:00:00 AKDT
If you then change your time zone:
my_model.started_at_time_zone = 'Hawaii'
Then calling the attributes on your model will result in the following:
my_model.started_at_utc # => ActiveSupport::TimeWithZone 2011-07-04 13:00:00 UTC
my_model.started_at_time_zone # => ActiveSupport::TimeZone 'Hawaii'
And again, asking Greenwich for the value of started_at
will result in:
my_model.started_at # => ActiveSupport::TimeWithZone 2011-07-04 03:00:00 HADT
Issues
If you have problems, please create a Github issue.
Credits
greenwich is maintained by Chrrpy, LLC
The names and logos for Chirrpy are trademarks of Chrrpy, LLC
License
greenwich is Copyright © 2011 Chirrpy. It is free software, and may be redistributed under the terms specified in the LICENSE file.