Managing Multiple Timezones for Events in Drupal

How does a Drupal developer handle timezones when managing events in multiple locations? How do you display the correct date and time for these various locations? David Spira, one of our Experience Strategists at Phase2, created an ingenious solution for this common dilemma. In this blog post, I will walk through how we implemented David’s solution to support multiple timezones for events, using the Date, Geofield, Geocoder and Timezone field modules.

Timezones and UX Complications

Before I get into the solution, let’s touch on some of the issues at hand. Timezone display and management are always a bit tricky for both the consumer and the editor. For the display, there’s a whole set of considerations that complicate the user experience:

• Should we display the timezone abbreviation? What happens if two timezones have the same abbreviation (a problem that arises if your timezone support is global)?
• Should we display the full timezone name? How do we deal with this large amount of text on teasers?
• Should we display the UTC offset? Will the user even know the offset for his/her location?

For editing, there’s additional UX to consider:

• How does the editor determine the timezone for the event if the default timezones for the site and the editor’s user account are different?
• What if the event has multiple locations in different timezones? How should the editor manage this?

Our Solution

One way to simplify the process is to remove timezone names/abbreviations from both the display and the editor. The user viewing the event just wants to know the date and time for a given location, and doesn’t care about UTC offsets or timezones. Additionally, the editor might not know the timezone name for a location.If you’re creating an Event content type, then you’re going to have a Date field to store the start and end date and time information. Most likely, your event will have a location, or if it’s remote/online only, then a primary timezone for the event. For the sake of this example, let’s also assume that Events may have multiple locations, and these locations may be in completely different timezones.To start, you’ll need to install the following additional dependencies for the Geocoder, Geofield, and Timezone field modules:

• ctools
• geoPHP

The following modules (as a minimum) need to be enabled for this example:

• ctools
• Date
• Date API
• Geofield
• Entity API
• Geocoder
• GeoPHP
• Timezone field
• Time zone field populate from Geofield

The Date Popup module (optional) provides a friendly interface for entering calendar date information. It’s a good idea to enable this module to make things easier for your editors.Now to satisfy the requirement of additional locations and timezones, we can use either a Paragraphs or Field Collection field. For either storage solution, you’ll need to add the following combination of fields:

1. Location/Address (text, textarea, or Addressfield)
2. Geofield based on the Address
3. Timezone field based on the Geofield.

Your Event content type field set should look something like this (I chose to use the Date Popup widget for my Date field and the Field Collection field for the group of location, geocode, and timezone fields):

Exploring the Field Collection Setup

We can make the selection of the appropriate timezones for Events easier by making this determination automatically. A combination of Geofield and Timezone field fields works well for this purpose since we already have the location.To your Locations Field Collection, add a new Geofield to your Event content type, and select the Geocode from another field widget type. The field that should be used for determining the geocode should be your Address field. Select the geocoding handler you would like to use. I like using the Google Geocoder, and I use the default Point Geometry Type. The following are the defaults I used for the Geocoder Settings:

  The next step is to link up a timezone field to this chain of dependent fields. Add a Time zone field and use the Populate from Geofield widget. Link this field to your previously created Geofield. Here’s the field breakdown for the Field Collection:

  It’s a good idea to make both the Date and the Location Field Collection fields required. Adding some helpful description text to the Location and Event Date fields explaining the automatic handling of the timezone for the Event is also very user-friendly for the editor.

Adjusting the Display

Ok! We’ve got the data structure set, so now let’s adjust the display of this information. First of all, we can hide the Locations field since we’ll be handling the display of this information in our preprocess function. So the Manage Display tab for Event should look like this:

  For this example, I created a subtheme of the Bootstrap theme. I’ll walk through the preprocessing of the full node view, and we’ll keep things relatively simple. Since I subthemed the bootstrap theme, I used Bootstrap classes to style the markup. The code examples for template.php and node--event.tpl.php are available in a zip file so you can review both files. In template.php, I added a little helper logic so that I can target the Event content type when preprocessing the display of the node:

/**
 * Override or insert variables into the node template.
 */
function mt_subtheme_preprocess_node(&$variables) {
  $type = $variables['type'];
  $node_preprocess_function = 'mt_subtheme_preprocess_node_' . $type;

  if (function_exists($node_preprocess_function)) {
    $node_preprocess_function($variables);
  }
}

Adding this little bit of logic allows you to separate out your specific content type node preprocessing:

/**
 * Preprocess function for Event nodes.
 */
function mt_subtheme_preprocess_node_event(&$variables) {
   ...
}

Ok, let’s take a look at mt_subtheme_preprocess_node_event() in further detail. For this example, I’m keeping things pretty simple and just adding some preprocessing for the full node page view. The primary datetime is set in UTC. This was because the primary event location may be different from the site or editing user’s timezone. We don’t care that the timezone associated with the saved datetime is UTC. What we really care about is the actual entered values for the start and end time for the event (the month, day, year, and time without any timezone information attached). So the first step is to get the nicely formatted datetime (Y-m-d G:i) for the start and end times.

function mt_subtheme_preprocess_node_event(&$variables) {
  // Do some preprocessing for the full node page.
  if ($variables['view_mode'] == 'full' && node_is_page($variables['node'])) {

    // Primary datetime is set in UTC.
    $utc_start_date = new DateTime('@' . $variables['field_date'][0]['value']);
    $utc_start_text = $utc_start_date->format('Y-m-d G:i');

    $utc_end_date = new DateTime('@' . $variables['field_date'][0]['value2']);
    $utc_end_text = $utc_end_date->format('Y-m-d G:i');

    if (isset($variables['node']->field_locations[LANGUAGE_NONE][0]['value'])) {
      // Get the primary timezone.
      $primary_location = array_shift($variables['node']->field_locations[LANGUAGE_NONE]);
      $primary_location = field_collection_item_load($primary_location['value']);
      $primary_timezone = $primary_location->field_timezone[LANGUAGE_NONE][0]['value'];

We store the primary address to make it easily to print it in the template later.

$variables['primary_location'] = $primary_location->field_location[LANGUAGE_NONE][0]['safe_value'];

We then create a new DateTime object to associate the datetime text sans-timezone with the primary location’s timezone. (The primary location’s timezone is just the first location in the field collection in this instance). We also added Exception handling just in case the timezone label used for the new DateTimeZone’s constructor was invalid.

try {
  $primary_start_date = new DateTime($utc_start_text, new DateTimeZone($primary_timezone));
  $primary_end_date = new DateTime($utc_end_text, new DateTimeZone($primary_timezone));
}
catch(Exception $e) {
  watchdog('mt_subtheme_date_error',
    "Invalid timezone for primary timezone: %timezone",
    array('%timezone' => $primary_timezone), WATCHDOG_ERROR, current_path());

  return;
}

We also store the primary dates for the start and end times so that we can compare them to the dates for the start and end times for the additional timezones. This will be useful for determining if we should display the Month, day and year as well as the time for the additional timezones (which would be the case if another location is a day ahead or behind, for example).

// We store the day for the start and end dates so that we can compare
// them to the day for the start and end dates for the additional
// timezones.
$variables['primary_start_date'] = $primary_start_date->format('m-d-Y');
$variables['primary_end_date'] = $primary_end_date->format('m-d-Y');

As a fallback we use the UTC timezone for the primary datetime.

else {
  // Set the default timezone to UTC.
  $primary_start_date = new DateTime($utc_start_text, new DateTimeZone('UTC'));
  $primary_end_date = new DateTime($utc_end_text, new DateTimeZone('UTC'));
}

Now we can address the additional locations. For this example, I used Field Collections to hold information about the additional locations. We loop through the collection, and do some additional processing. We store the processed date information for each location in the $other_dates array.

$other_dates = array();
foreach ($variables['node']->field_locations[LANGUAGE_NONE] as $collection) {

We have to load the field collection in order to access the entered address and calculated timezone.

$location = field_collection_item_load($collection['value']);

For each location, we process and store the following information used in the Event template:

• address
• Start and End dates formatted as m-d-Y. This is used to compare against the primary start and end date. If the date is different, then it makes sense to display the formatted information (see next bullet) with the time.
• The Start and End dates formatted as l, F j, Y - G:i. This is used because I wanted to keep the text formatting the same as what would be outputted for the primary date and time.
• The Start and End dates formatted as ISO 8601. This is used for the content attribute for the date markup. Using this just makes the markup consistent with the output for the primary date.

Note, we clone the primary date object and change the timezone appropriately for each location, and store the information.

// Setup a friendly array that groups the city with the calculated time.
$other_date = array(
  'location' => $location->field_location[LANGUAGE_NONE][0]['safe_value'],
);

// We need to clone our primary dates so that we can adjust the datetime
// based on the timezone for the city.
try {
  $primary_start_clone = clone $primary_start_date;
  $primary_start_clone->setTimezone(new DateTimeZone($location->field_timezone[LANGUAGE_NONE][0]['value']));

  $other_date['start_date'] = $primary_start_clone->format('m-d-Y');
  $other_date['start_date_formatted'] = $primary_start_clone->format('l, F j, Y - G:i');
  $other_date['start_time'] = $primary_start_clone->format('G:i');
  $other_date['start_date_iso'] = $primary_start_clone->format('c');

  $primary_end_clone = clone $primary_end_date;
  $primary_end_clone->setTimezone(new DateTimeZone($location->field_timezone[LANGUAGE_NONE][0]['value']));

  $other_date['end_date'] = $primary_end_clone->format('m-d-Y');
  $other_date['end_date_formatted'] = $primary_end_clone->format('l, F j, Y - G:i');
  $other_date['end_time'] = $primary_end_clone->format('G:i');
  $other_date['end_date_iso'] = $primary_end_clone->format('c');
}
catch(Exception $e) {
  watchdog('mt_subtheme_date_error',
    "Invalid timezone for additional location: %timezone",
    array('%timezone' => $primary_timezone), WATCHDOG_ERROR, current_path());

  continue;
}

$other_dates[] = $other_date;
} // Closing foreach loop.

$variables['other_dates'] = $other_dates;

Finally, for some icing on the cake, we can present the user with an additional option to find out the date and time based on the selected timezone. You can use Chosen module to make the select dropdown more user-friendly.

$variables['my_timezone_form'] = drupal_get_form('mt_subtheme_my_timezone_form', $primary_start_date, $primary_end_date);

Here’s what the form looks like:

/**
* My Timezone form builder.
*/
function mt_subtheme_my_timezone_form($form, &$form_state, $primary_start_date, $primary_end_date) {
 $form = array();

 $form['#primary_start_date'] = $primary_start_date;
 $form['#primary_end_date'] = $primary_end_date;

 $form['my_timezone'] = array(
   '#type' => 'select',
   '#options' => mt_subtheme_system_time_zones(),
   '#prefix' => '<h5 id="my-timezone-label">Select My Timezone</h5>',
   '#ajax' => array(
     'callback' => 'mt_subtheme_my_timezone_callback',
     'wrapper' => 'my-timezone-label',
     'method' => 'replace',
     'effect' => 'fade',
   ),
 );

 return $form;
}

The list of timezones come from basically the list of system timezones, made slightly prettier by replacing ‘_’ with ‘ - ’.

/**
* Generate an array of time zones and their local time & date.
*/
function mt_subtheme_system_time_zones() {
 $zonelist = timezone_identifiers_list();
 $zones = array('' => t('- None selected -'));
 foreach ($zonelist as $zone) {
   // Because many time zones exist in PHP only for backward compatibility
   // reasons and should not be used, the list is filtered by a regular
   // expression.
   if (preg_match('!^((Africa|America|Antarctica|Arctic|Asia|Atlantic|Australia|Europe|Indian|Pacific)/|UTC$)!', $zone)) {
     $zone_pieces = explode('/', str_replace('_', ' ', $zone));
     $zone_pieces = array_reverse($zone_pieces);
     $continent = count($zone_pieces) > 1 ? array_pop($zone_pieces) : '';
     $zone_pretty = implode(', ', $zone_pieces);

     if ($continent) {
       $zone_pretty .= ' - ' . $continent;
     }

     $zones[$zone] = t('@zone', array('@zone' => $zone_pretty));
   }
 }
 // Sort the translated time zones alphabetically.
 asort($zones);
 return $zones;
}

Display of the information is handled by a simple Ajax callback:

/**
* Callback for My Timezone select.
*/
function mt_subtheme_my_timezone_callback($form, &$form_state) {
 $timezone = $form_state['values']['my_timezone'];

 try {
   $primary_start_clone = clone $form['#primary_start_date'];
   $primary_start_clone->setTimezone(new DateTimeZone($timezone));
   $start = $primary_start_clone->format('m/d/Y -
G:i');

   $primary_end_clone = clone $form['#primary_end_date'];
   $primary_end_clone->setTimezone(new DateTimeZone($timezone));
   $end = $primary_end_clone->format('m/d/Y -
G:i');
 }
 catch(Exception $e) {
   watchdog('mt_subtheme_date_error',
     "Invalid timezone given to My Timezone form: %timezone",
     array('%timezone' => $timezone), WATCHDOG_ERROR, current_path());

   return t('<h5 id="my-timezone-label">Error determining the time based on the selected timezone.</h5>');
 }

 return t('<h5 id="my-timezone-label">@start to @end</h5>', array(
   '@start' => $start,
   '@end' => $end,
 ));
}

In node--event.tpl.php, we render field_date and print the $primary_location.

<div class="date-locations">
  <?php // Display the primary datetime and location. ?>
  <div class="panel panel-default first location">
    <div class="panel-heading">
      <h3 class="panel-title">Primary Event Date and Time</h3>
    </div>
    <div class="panel-body">
      <?php print render($content['field_date']); ?>
      in <strong><?php print $primary_location; ?></strong>
    </div>
</div>

We loop through the $other_dates array, and print out the information. There’s a little logic to determine if we need to print out the month, day, and year if different from the primary date or if the date spans multiple days.

<div class="other-locations">
  <h4>Other Locations and Times</h4>
  <?php foreach($other_dates as $date): ?>
    <div class="location well well-sm">
      <?php
        // We need to check and handle cases in which the day (and possibly
        // year) is different from the primary date. We should also match the
        // markup produced from rendering a date field too.
       ?>
       <?php if (($primary_start_date != $date['start_date']) || ($date['start_date'] != $date['end_date'])): ?>
         <?php if (($primary_end_date != $date['end_date']) || ($date['start_date'] != $date['end_date'])): ?>
           <div class="date-display-range">
             <span class="date-display-start" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['start_date_iso']; ?>"><?php print $date['start_date_formatted']; ?></span>
             to
             <span class="date-display-end" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['end_date_iso']; ?>"><?php print $date['end_date_formatted']; ?></span>
           </div>
         <?php else: ?>
           <?php // Match markup that's created from rendering a date field...even the span > div ?>
           <span class="date-display-single"><?php print $date['start_date_formatted']; ?>
             <div class="date-display-range">
               <span class="date-display-start" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['start_date_iso']; ?>"><?php print $date['start_time']; ?></span>
               to
               <span class="date-display-end" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['end_date_iso']; ?>"><?php print $date['end_time']; ?></span>
             </div>
           </span>
         <?php endif; ?>

       <?php else: ?>
         <?php // The date is the same. Let's just display the time. ?>
           <span class="date-display-single">
             <div class="date-display-range">
               <span class="date-display-start" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['start_date_iso']; ?>"><?php print $date['start_time']; ?></span>
               to
               <span class="date-display-end" property="dc:date" datatype="xsd:dateTime" content="<?php print $date['end_date_iso']; ?>"><?php print $date['end_time']; ?></span>
             </div>
           </span>

      <?php endif; ?>
      in <strong><?php print $date['location']; ?></strong>
      </div>
    <?php endforeach; ?>
  </div>
</div>

You can add more logic for a more sophisticated display for the month, day, and year so that less unnecessary text is displayed to the user.Finally, we render the form that allows the user to see the date and time for the selected timezone.

<?php print render($my_timezone_form); ?>

And that’s it! Here’s a couple examples of the node edit form and the resulting output:

Single Day Event

Multi-Day Event + My Timezone Results

And that's a wrap! Here's a link to the zip file for the above code sample.