This module provides support for displaying a date or time in the user's own time zone in both formatted date fields and (via token text) within the body of any formatted text field.
A typical usage would be to give the time(s) of an event in the body of a page that will be seen by people in multiple time zones.
Logged-in users will see the date/time in their own time zone. Anonymous users will see it in the default time zone (typically the server time zone), but there is an option to detect their time zone as well.
Installation
Install this module using the official Backdrop CMS instructions.
- Visit the configuration page under Administration > Configuration > Regional and lanugage >
User time zone tokens (admin/config/category/utz-tokens) and select the desired method for detecting the user's time zone.
To use the tokens in formatted text,
- Install and enable the Token Filter module.
- Enable the "Replace tokens" filter for the text formats that you will be using these tokens in.
To automatically detect the time zone for anonymous or all users,
- Install and enable the Luxon module.
- Go to /admin/config/regional/utz-tokens and check the desired option.
Usage
Date Fields
User Time Zone Tokens provides a field formatter for the three Date type fields. Using the "UTZ Date and Time" formatter, you can render user-timezone-aware fields in (for example) node display pages and within Views.
You can use any of the built-in date formats or create your own custom formats. Note, though, that for date ranges (with starting and ending dates), you will define three date formats:
- Start date
- End date
- End date for intervals less than 24 hours.
The reason for the third format is to allow formats that include the year, month, and/or day to drop those values for intervals less than 24 hours. The core Date module does this dropping automatically; this module doesn't (due to how the rendered date ranges are sometimes constructed by Javascript).
Tokens
Tokens are of the form
[utz-datetime:datetime|format]
where
-
datetime is a string specifying the time in any format suitable for initializing a DateTime object.
- To initialize from a Unix timestamp, prepend '@' to the timestamp, e.g.,
@1611363600. - To initialize from a time string, be sure to include the time zone explicitly, e.g.,
2021-01-01 12:00 PST; otherwise the user's local time zone is assumed (which would defeat the purpose of using this token).
- To initialize from a Unix timestamp, prepend '@' to the timestamp, e.g.,
-
format is a string giving the desired output formatting, which can be either
- The machine name of a Backdrop date/time format found at /admin/config/regional/date-time (e.g.,
'short','medium','long'), or - Any valid PHP formatting string. Formatting options are documented in the PHP Manual.
- The machine name of a Backdrop date/time format found at /admin/config/regional/date-time (e.g.,
To initialize from a timestamp, you can convert a date to a timestamp using EpochConverter.
Note that datetime and format are separated by a pipe (|), not a colon (:), because datetime might contain a colon (typically separating hours and minutes).
You can use these tokens anywhere that tokens are accepted. To use the tokens in formatted text (the most common use case), install and enable the Token Filter module and then enable the "Replace tokens" filter in your text format.
Timezone Detection for Anonymous Users
There is an option to automatically detect the user's time zone (which is provided by their browser) and use that for anonymous or all users, which works even for cached pages. To use this capability you will need to install the Luxon module. With Luxon installed and enabled, on the configuration page for this module you will have the option to detect the user's time zone for anonymous or all users. This capability requires Javascript.
Beware of Caching
When using either setting that includes "Use user's timezone for authenticated users," page and/or entity caching can short-circuit UTZ tokens via this scenario:
- User in time zone A visits the page; it gets cached with time zone A data.
- User in time zone B visits the page and is served the cached version containing time zone A data.
To get around this, you can turn off caching for pages and/or relevant entities. (You can turn off entity caching on a per-bundle basis using the Entity Cache Administation module.) This will, of course, come with a cost in performance. Alternatively, you can install the Luxon module per the above and select the third option in the settings, "Use the browser's timezone for both authenticated and anonymous users (requires Luxon and Javascript).". This will work regardless of caching because the time zone localization happens in the user's browser.
Theme Function (for Developers)
Developers can incorporate the user-timezone-aware functionality of User Time Zone Tokens into their own rendering of dates/times by using the theme function, e.g.,
$datetime = '2021-04-01 12:00pm PDT' // or, for example, '@1617303600'
$format = 'l, F j, g:ia T'; // or, for example, 'long'
$output = theme('utz_datetime', array(
'datetime' => $datetime,
'format' => $format,
));
Issues
Bugs and feature requests should be reported in the Issue Queue.
Similar Modules
User Time Zone Tokens handles time-zone-aware dates and times embedded within content as token text and via the "UTZ Date and time" field formatter for fields provided by the core Date module. Another approach to applying time zone awareness to fields provided by the core Date module is the Client Side Date Field Formatter module.
Current Maintainers
Credits
- Written for Backdrop CMS by Robert J. Lang.
License
This project is GPL v2 software.
See the LICENSE.txt file in this directory for complete text.