Convio Drupal : Personalization

Convio Drupal > Personalization

Overview

Drupal CMS supports personalized attributes and conditional content.

Requirements

  1. Authors can add personalized tags in their content. In preview and live pages, these personalized tags will be replaced with the C360 values.
  2. Theme designers can use Drupal CMS APIs to add personalized attributes and conditional content to any page.

Design

There are two methods for accessing personalized and conditional content:

  1. PHP ConvioUser object
  2. Personalized tokens

1. PHP ConvioUser object

The current authenticated Convio user can be accessed via:

$user = ConvioLoginHandler::getInstance()->getUser()

This method returns a ConvioUser object that represents the authenticated user, or NULL if the user is anonymous. The current user is based on user context established by the Single Sign-On mechanism. The current user is fetched once per request.

Once you have a valid ConvioUser object, you may access the C360 Cons profile, groups, and interests via the following calls:

  • $user->getProperties()
  • $user->getProperty($name)
  • $user->getGroups()
  • $user->isGroupMember($id)
  • $user->getInterests()
  • $user->hasInterest($id)

The properties, groups, and interests are lazy-loaded in order to minimize the # of C360 API calls.

//modules/ConvioLoginHandler.inc

  /**
   * Gets the user tied to the current HTTP session.
   *
   * @return the authenticated user, or NULL for the anonymous user
   */
  public function getUser() {
    $cons_id = $_SESSION[ConvioConstants::$SESSION_CONS_ID];
    if ($cons_id) {
      // We think the user is authenticated.

      // Cache the result for the duration of the request.
      global $convio_user;
      if (! isset($convio_user)) {
        $convio_user = ConvioUser::find($cons_id);
      }

      return $convio_user;

    } else {
      // Anonymous user.

      return NULL;
    }
  }

2. Personalized Tokens

For a more publisher-friendly experience, the Convio module implements the Token hook for personalized attributes. The personalized tokens are referenced by the same name as in the getUser C360 call (e.g., [name.first]). The personalized token replacement is applied to all text regions in the default lucha theme.

For efficiency, the constituent profile is cached in the Drupal session. If it is necessary to have "live" personalized data (e.g., for participation pages), then developers may add the following directive to their page:

ConvioTokenHandler::getInstance()->disableCache();

Note that the token interface does not support conditional content or loops, so user group and interest data is not as available through this method.

The ConvioTokenHandler class implements the Drupal Token hook.

//modules/convio/ConvioTokenHandler.inc

  /**
   * Fetches the constituents basic attributes.
   *
   * @return an associative array of constituent attributes.
   */
  public function getValues() {
    $properties = NULL;

    $cons = ConvioLoginHandler::getInstance()->getUser();
    if ($cons != NULL) {
      // Authenticated user.

      // Use the cached C360 data unless the convio_no_cache flag has been set.
      // If convio_no_cache is set in the request, indicates that the C360 data should always be 
      // fetched fresh.
      $cache_key = "convio_cons_properties::" . $cons->getID();

      global $convio_no_cache;
      if (! isset($convio_no_cache) && isset($_SESSION[$cache_key])) {
        // Cached result.
        $c = $_SESSION[$cache_key];

        if ($c != NULL) {
          $cons = unserialize($c);
        }
      }

      $properties = $cons->getProperties();

      // A Drupal6 limitation (http://lists.drupal.org/pipermail/development/2009-December/034510.html)
      // prevents storing of the ConvioUser object in the session. So instead we serialize the data 
      // beforehand.
      $_SESSION[$cache_key] = serialize($cons);

      unset($convio_no_cache);
    }

    return $properties;
  }

Theme Example: Automatic personalized token replacement

To enable automatic token replacement in Drupal content, add the following code to the theme pre-processor.

//template.php

function lucha_preprocess(&$vars, $hook) {

  // For all string attributes, personalize as Convio tags.
  foreach ($vars as $name => $value) {
    if (is_string($value) && strrpos($value, '[') > 0 && strrpos($value, ']') > 0) {
      if ($hook == "page" && $name == "content") {
        // Skip "content" to avoid having author entry form values personalized.
        continue;
      }
      $vars[$name] = token_replace($value,'convio');
    }
  }
}

Caveats

There are several caveats to be aware of when integrating Drupal with C360:

  • Like the SSO implementation, the personalization mechanism is not designed to be fault tolerant should COM become unavailable or unresponsive. Personalization will not work because of the timed-out API calls.
  • The token interface does not support conditional content or loops, so user group and interest data is not available through personalized tokens.


-- Michael Pih (mpih@convio.com) - 20 July 2010
Copyright (C) 2010 Convio, Inc. All rights reserved. This program is free open source software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The GNU General Public License is available at http://www.gnu.org/licenses/.