[[TOC]]
= Handling of Timezones =

== Original Timezone Implementation ==

  - time zones are handled as fixed UTC offsets
  - the server UTC offset is an admin setting
  - users can set their own offset in their profile, which defaults to the server UTC offset

  - datetime values are stored in the database as UTC
  - datetime values are displayed in the user's (fallback: server's) time zone using their respective UTC offset
  - DST doesn't get adjusted

  - we use a custom validator IS_UTC_DATETIME() which accepts datetimes in:
    - ISO format without trailing UTC offset (=interpreted as being in user's local time)
    - extended ISO format with trailing UTC offset (=interpreted according to the trailing offset)
  - the validator converts datetime values on input into UTC
  - datetime values retrieved from the DB are converted into local time using the current user's UTC offset:
    - shn_user_utc_offset() retrieves the current user's UTC offset as "+/-HHmm" (fallback: server UTC offset)
    - shn_as_local_time() formats UTC datetimes according to the current user's UTC offset
    - shn_as_local_time() is used for .represent of datetime values

== New Timezones Implementation ==

 - time zones are handled by their abbrevated names (e.g. UTC, CET, CEST and so forth)
 - the server timezone is an admin setting
 - users can set their own timezone in their profile, which defaults to the server timezone
  * [/attachment/wiki/BluePrintTimezones/TimeZones.png Potential UI]

 - datetime values are stored in the database as UTC
 - datetimes are displayed/accepted with timezone correction and automatic DST adjustment:
  - at input according to a fallback cascade of:
   * the timezone specified at the input value (if any)
   * the timezone specified by .requires of the respective field (if any)
   * the current user's timezone
  - at output according to a fallback cascade of:
   * the timezone specified by the controller at the request (use-case see below)
   * the timezone specified by .represent of the respective field (if any)
   * the current user's timezone

 - we use a custom validator IS_UTC_DATETIME() which accepts datetimes in:
  - ISO format without trailing timezone or UTC offset (=interpreted as being in user's local time, automatic DST adjustment)
  - extended ISO format with trailing UTC offset (=interpreted according to the trailing offset, no DST adjustment)
  - extended ISO format with trailing timezone (=interpreted according to the trailing timezone, automatic DST adjustment)

 - Should use [http://pypi.python.org/pypi/pytz/ PyTZ] library to ensure that we don't need to maintain our own database
  - may use higher-level [http://blog.twinapex.fi/2008/06/30/relativity-of-time-shortcomings-in-python-datetime-and-workaround/ fixed_datetime.py] to interface with this

=== Special use-cases ===
  - where information is to be saved about the timezone of the entering user, this should happen in an extra field
  - when information is stored about the timezone of the entering user, the datetimes should be displayed in that timezone instead of the reading user's local time, clearly indicating to the reading user which timezone the datetime is expressed in

=== Automatic DST adjustment ===

  ''dst_adjustment = function(datetime, timezone)''

Meaning: DST adjustment depends on the respective timezone '''''and''''' the datetime value (!)

e.g., with the user's timezone being CET:
   - 2009-07-03 14:33 is interpreted as 2009-07-03 12:33 UTC (offset +02:00), while
   - 2009-11-08 18:15 is interpreted as 2009-11-08 17:15 UTC (offset +01:00)

== Possibly Useful ==
 * http://www.ama3.com/anytime/AnyTime/anytimetz.js

----
BluePrints