Invite Friends to Authorize the Current Application
It's nice to give users a way to invite friends to use the app. Not only because users share something useful with their friends, but also because it makes your application more viral. Facebook has imposed limits on how many invites a user can send, and may even deprecate the invite function in the future. Still, for the time being, its a nice thing for your app.
Background
Invite forms are an example of fb:request-form. This is a special FBML tag that will build the entire form, including buttons. While this renders a form on the page, from the Drupal perspective, it is markup with a <fb:request-form> tag, not a <form> and therefore it is not built with Drupal's FAPI. However, we want third-party modules to customize these forms. So, we build a data structure very similar to a $form array, then call drupal_alter(), so that modules can customize, then finally call drupal_render() to turn our data structure into markup.
Recipe
Note that this recipe works for FBML Canvas Pages, and HTML Facebook Connect sites.
- Enable the fb/contrib/fb_friends.module, currently called "Friend Features".
- Under Site Building >> Blocks >> YOUR THEME, enable the block called Invite Facebook friends to install the current app. Choose a wide region (i.e. footer), because the resulting form will be large.
- Optionally, configure the block to appear only on certain pages. This is standard Drupal stuff.
- View a page where your block appears. Do you see the form?
Done!
Advanced
Read up on request forms, multi-friend-selectors and other input options for the form. Now that you're an expert in Facebook's soon-to-be deprecated API, do you want to customize your apps invite form? Oh, about the API being deprecated - don't be surprised, facebook has changed every API they've ever come up with. What's surprising is that this time, they tell us in advance! But I digress...
Behind the scenes, Drupal for Facebook builds a data structure that bridges the gap between Facebook's FBML markup, and Drupal's way of rendering. So a savvy Drupal developer can customize everything about the markup, before the fb:request-form is rendered. Your module can implement two hooks. Remember we're not, strictly speaking, building a FAPI form, so we're not using hook_form_alter().
hook_fb_friend_invite_app_alter()
This function is passed a reference to $fbml, the data structure representing the <fb:request-form> tag.
<?php
function dff_custom_fb_friend_invite_app_alter(&$elem) {
// Here's a way to see the data structure...
dpm(func_get_args(), "Here's what was passed to hook_fb_friend_invite_app_alter()");
// TODO: need an example here!
}
?>hook_fb_friend_invite_app_wrap_alter()
For Facebook Connect app, the fb_friend module then wraps the <fb:request-form> in the <fb:server-fbml> tag. On FBML canvas pages this is not done, but on Facebook Connect it is necessary. But maybe its not what your application wants. Here's a neat alter to make the form appear in a popup instead of embedded in the page:
<?php
/**
* Implementation of hook_fb_friend_invite_app_wrap_alter(). See 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 dff_custom_fb_friend_invite_app_wrap_alter(&$elem) {
// Replace serverfbml with popup
if ($elem['#type'] == 'fb_form_serverfbml') {
$elem['#type'] = 'fb_connect_fbml_popup';
$elem['#title'] = t('Invite Friends');
$elem['#link_text'] = t('Invite Friends');
$elem['#attributes'] = array('width' => 760);
}
}
?>This hook replaces the form with a link that says "Invite Friends". Now, its safe to place the block in a thin sidebar. The markup will no longer be wide. Clicking on the "Invite Friends" link will cause a wide popup to appear over the page.
More Advanced
If you don't like the blocks provided by fb_friends.module, you have other options.
First, Drupal for Facebook sets up your canvas page or connect page so that you can embed any FBML or XFBML inside it. Now that you're expert in <fb:request-form> and all that, just get that markup into your page any old way that you know how. Drupal is great; Drupal is flexible; so is Drupal for Facebook.
Second, you can take a look at fb_friends.module source code. And fb_form.module, which has the code to render the element types. If you find this hard to follow, read up on drupal_render(). Emulate the code in fb_friends.module in your own module to do whatever you need.
Third, you can build a node with the PHP input filter. This could be used in a live site, but is also great for testing. Put something like this in your node body. Don't forget the PHP input filter!
<?php
$block = fb_friend_block('view', FB_FRIEND_DELTA_INVITE_APP);
//dpm($block['content'], "Markup"); // for debugging
print $block['content'];
?>
Another Invite Form
The fb_friends.module provides another block, Invite Facebook friends to current page. The behavior is almost identical to the current application invitation. In hook names, replace 'app' with 'page'.
Use app to invite users to authorize the application. fb_friends.module will exclude users who have already done this.
Use page to invite users to see a specific piece of content or perform a specific action. Users will not be excluded (unless you do so in the alter hook).