Connecting Facebook with Drupal, the easy way.

There are a few heavyweight modules contending to provide Facebook integration for Drupal. Which module is right for you? Simply looking at the Reported installs and Maintenance Status won't present a clear answer.

Choices

A recent project of mine required the use of Facebook's OAuth service. Here are the three modules that I considered:

• Drupal for Facebook
• Facebook Connect
• Facebook OAuth

Decisions

I installed and configured each of these modules before coming to a decision. Here's a quick summary of what I found:

• Drupal for Facebook
  is still very much in development. It isn't production ready, so if you're not willing to contribute, you may want to cross it off the list. Beyond that, it's important to realize that DFF's strength lies in providing a rough framework for using Drupal to build Facebook Applications. It is not ideal (or intended) for providing polished Facebook features to a pre-existing Drupal site. If you're looking for a good launch pad for some serious Facebook App development, give it a shot-- it may be just what you need. Otherwise, you may want to consider another module.

• Facebook Connect
  provides a number of unique out-of-the-box Facebook features, like finding Facebook friends on your Drupal site, or publishing a customizable message on their Facebook feed. However, this module is still in beta— it is not in a stable state. It should also be noted that FC uses the Facebook Javascript SDK, which means that you need to be familiar with the SDK if you'd like to extend the module's functionality.

• Facebook OAuth
  is best described in its author's own words, "This module is built with simplicity and flexibility in mind, it provides login services (and does it well), and an API for performing any other actions you may want to write yourself to query against Facebook's APIs."

The Winner (for me)

After attempting to extend Drupal for Facebook and Facebook Connect, Facebook OAuth was like a breath of fresh air. It's simple and flexible, and best of all, you don't need to learn Facebook's Javascript SDK to use it! Facebook OAuth has a well documented and well designed API that any PHP (particularly Drupal) programmer would be comfortable with. Some key features include:

• One-click login through Facebook.
• Automatic import of user e-mail and profile information during initial login.
• A flexible and direct API for modules to get authenticated and query Facebook's APIs (plus extensive documentation).
• Does not require any external libraries or downloads.

Harnessing the Power (the fun part)

Before I jump in, take note that you can find detailed information about all of FBOAuth's API functions in fboauth.api.php, which is bundled with the module. And don't forget to read the README.txt!

Now let's run through a quick example of how you can utilize the API.

Facebook OAuth allows you to import values from a user's facebook account and map them to that user's Drupal account during registration. In addition to providing a nice GUI for this mapping, it also allows you to define custom field types and callbacks for accomplishing the mapping and for processing the data. Most popular field types are supported by default.

For my site, I wanted to import a user's facebook address to an addressfield and geocode the location for storage in a geofield. By default, FBOAuth does not support mapping to fields of type addressfield. No problem! We'll use a few handy hooks to add that ability.

First, I want to let FBOAuth know that it can map Facebook location information to fields of type addressfield. I'll use hook_fboauth_user_properties_alter() to do that:

/**
 * Implements hook_fboauth_user_properties_alter().
 */
function grasmash_fboauth_user_properties_alter(&$properties) {
  // Allow the location property to be mapped to Addressfield typed fields.
  $properties['location']['field_types'][] = 'addressfield';
}

That was easy. Some detail:

• The first array key 'location' specifies the Facebook source field. Change that to another acceptable value in order to map a different source field to a new field type.
• You can add as many target 'field_types' as you'd like.
• For a full list of possible source field values, just take a look at fboauth_user_properties().

Next, let's tell FBOAuth what it should do with data that's been mapped to an addressfield by defining a callback that will process the data.

/**
 * Implements hook_fboauth_field_convert_info().
 */
function grasmash_fboauth_field_convert_info_alter(&$convert_info) {
  $convert_info += array(
    'addressfield' => array(
      'label' => t('Address Field'),
      'callback' => 'grasmash_fboauth_field_convert_location',
    ),
  );
}

If you're familiar with Drupal's array-heavy architecture, this snippet shouldn't surprise you at all. We're just adding another row to $convert_info. It specifies the name of the function that FBOAuth should look for when dealing with an addressfield. Now let's actually create that function!

/**
 * Facebook data conversion function.
 * Converts an incoming Facebook location (which is an object) into an array compatible with the addressfield module.
 */
function grasmash_fboauth_field_convert_location($facebook_property_name, $fbuser, $field, $instance) {
  $value = NULL;
  if ($field['type'] == 'addressfield' && isset($fbuser->location) && module_exists('geocoder')) {
    $geodata = geocoder('google', $fbuser->location->name);
    foreach ($geodata->data['geocoder_address_components'] as $key => $components) {
      switch($components->types[0]) {
        // Set city.
        case 'locality':
          $value['locality'] = $components->short_name;
          break;
        // Set state.
        case 'administrative_area_level_1':
          $value['administrative_area'] = $components->short_name;
          break;
         // Set country.
         case 'country':
          $value['country'] = $components->short_name;
          break;
      }
    }
  }
  return $value;
}

Clearly, this will be completely different for fields of any other type. The example above is specifically tailored for populating addressfield fields, and it relies entirely on the output returned by the geocoder module. If you're looking for some guidance in creating your own callback, just look at some of the default callbacks in fboauth.field.inc, like fboauth_field_convert_text().

The last step is to simply configure which field on the user object FBOAuth should actually import the data to. That is done through FBOAuth's admin page, located at admin/config/people/fboauth.

Other Awesome Things

From the README.txt:
"The Facebook OAuth module provides an API for executing queries against Facebook's vast store of user data." The README.txt goes on to explain the workflow for this process, and how you can write your own custom actions.

I plan to write a subsequent blog post about how you can programmatically execute these custom actions, but that's for another day!

Enjoy!