Greenwich...

...has been helping Rails developers work with custom time zones since 2011.

Greenwich

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

chirrpy

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.