NOTE (7/2013): this page is probably deprecated, as fb_friend.module is deprecated.

Users of your applications can invite their friends by way of a request form. This mechanism presents the user with a list of friends; they can choose one or more to invite.

Drupal for Facebook includes some support for invitations, in the fb_friend.module. The syntax for a request-form is rather complex and this module will help you get it right. Also, it saves invitations to the fb_friend table which is helpful in keeping track of invitations and preventing one user from inviting the same friend more than once. The examples on this page assume you are using the fb_friend.module (the other option being to build the request-form markup yourself).

Request/Invitation form in a block

Required modules

• fb_app.module
• fb_friend.module

Configuration

• Go to Admin >> Site building >> Blocks.
• Enable one of the "Invite Facebook friends..." blocks by placing it in a reqion. Choose a wide region, such as the "footer" or "content", because this is a wide block.

To confirm the block works, open another browser (don't administer Drupal and test Facebook apps in the same browser). Login to your application and visit a page with the block enabled. You should see the invite form like shown below:

Additional details about blocks

The fb_friend.module provides two invitation blocks.

• Invite Facebook friends to install the current app - This invitation sends the invitees to the application home page, prompting them to authorize the application which would look like this:

  

• Invite Facebook friends to the current page as shown here:

  

  This invitation is a more specific invitation. Invitees will be sent to the same page that the invitation was sent from like this:

  

When fb_friend renders invitation forms, it invokes hooks, allowing third-party modules to customize the appearance and behavior of both the form and the invitations/requests which it sends. This often makes it better to start with the forms produced by these blocks, even if your application needs a highly customized behavior. While request-forms are not "forms" in the Drupal form API sense (i.e. they will not appear in hook_form_alter()), fb_friend.module does build them using a similar data structure and allows them to be customized in a similar way.

Invitation form in a popup window

Required Modules

Same as above, plus fb_connect.module.

Configuration

Start by enabling an invite block as described above. This example uses the "Invite friends to current page" block also exhibited in the above screenshot.

We need a module to customize the block's markup. This example comes from modules/fb/contrib/fb_example.module and is the code used on http://drupalforfacebook.org. For your own customization, replace "fb_example" with the name of your module.

When fb_friend.module produces this block, it calls two hooks.

• hook_fb_friend_invite_page_alter(&$fbml) is passed a data structure representing the request-form markup, and gives you an opportunity to change that markup.
• hook_fb_friend_invite_page_wrap_alter(&$elem) is passed a similar data structure for a wrapper element, which surrounds the FBML. This is necessary because request-forms must be inside a fb:serverFBML tag. Happily, we can swap out the fb:serverFBML for a special tag that renders the form in a popup.

Note, for the block which invites friends to install the application, the hook names are hook_fb_friend_invite_app_alter(&$fbml) and hook_fb_friend_invite_app_wrap_alter(&$elem).

To change the inline form into a popup, we need to implement one hook as follows.

/**
 * Implements hook_fb_friend_invite_page_wrap_alter().
 *
 * @see modules/fb/contrib/fb_friend.module
 *
 * Here we customize the block which invites Facebook friends to visit
 * the current page.
 *
 * By default the invite form is wrapped in serverfbml and embedded
 * within a page.  Here we alter the data before it is rendered.  We
 * change the wrapper type to fb_connect_fbml_popup.  The result is a
 * link which pops up the invite form.
 */
function fb_example_fb_friend_invite_page_wrap_alter(&$elem) {
  // Replace serverfbml with popup
  if ($elem['#type'] == 'fb_form_serverfbml') {
    $elem['#type'] = 'fb_fbml_popup';
    $elem['#title'] = t('Invite Friends to View This Page');
    $elem['#link_text'] = t('Invite friends to view this page');
    $elem['#attributes'] = array('width' => 760);
  }
}

Note, the fb_fbml_popup markup is handled by fb_connect.js. Comments in that file describe the markup in detail. It relies on Facebook's poorly documented FB.ui javascript.

We can change other aspects of the request-form by implementing the other hook. Here's an example below.

/**
 * Implements hook_fb_friend_invite_page_alter().
 *
 * Customizes aspects of the invitation form.
 */
function fb_example_fb_friend_invite_page_alter(&$fbml) {
  $fbml['selector']['#attributes']['cols'] = 3;
  $fbml['selector']['#attributes']['email_invite'] = FALSE;
  $fbml['selector']['#attributes']['import_external_friends'] = FALSE;
}

Consult Facebook's documentation to learn more about all the options for request-forms (it's more complicated than it should be!).