Last updated November 24, 2010. Created by Dave Cohen on November 12, 2009.
Log in to edit this page.
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(&$fbml) {
// 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()");
// Make the form thinner
$fbml['selector']['#attributes']['cols'] = 3;
// Prompt for less info
$fbml['selector']['#attributes']['email_invite'] = FALSE;
$fbml['selector']['#attributes']['import_external_friends'] = FALSE;
}
?>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'];
?>
Comments
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).
But how to theme the box with friends?
This feature is very good but I was searching on Facebook and Drupal4Facebook and found no answear how to change the table/box size... currently it's wrapped in facebook code an the box is 100% width of my site... does not look nice...
Any suggestions how to change the "invite friends to current app" table size?
hello drupal world!
my drupal site: Wyprzedaż, promocja, przeceny
See the 'cols' attribute in
See the 'cols' attribute in dff_custom_fb_friend_invite_app_alter() example above. You can alter any part of the markup in that hook. So read facebook's doc on what the options are (there are many). Then use the drupal alter hook to build or change the markup.
Where to place the alternating code
Hi all,
I read the readme and most of the supporting documentation. Many thanks 4 all of it.
But as I am quite new to Drupal, I am unsure where to place the given code snippet.
Shouldn't it be correct, to put it inside my template.php of my theme - with the appropiate-name.
Like so:
<?php function mythemename_fb_friend_invite_app_alter(&$fbml) {
// Make the form thinner
$fbml['selector']['#attributes']['cols'] = 3;
}
P.S. Sorry for the more basic than dff-specific question.
EDIT: According to http://drupal.org/node/962410 this has to be inside a custom module. I have never developed one on my own, so this might be a great opportunity.
I'll post my result, when done.
Best wishes,
Sunny
Do it with Drupal. And the world will be sunny.
Sunny - any luck with
Sunny - any luck with implementing this? I'm also a newbie and this hook alter stuff is confusing.
_________________________
kyler boudreau
http://www.theatereleven.com
Sunny - any luck with
Sunny - any luck with implementing this? I'm also a newbie and this hook alter stuff is confusing.
_________________________
kyler boudreau
http://www.theatereleven.com