collective.simplesocial 1.0b1

Basic Facebook Connect support for Plone

Introduction

collective.simplesocial exposes some basic features of Facebook’s “Facebook Connect” API for use within Plone.

The goals of this Plone add-on product are to:

• Provide the basic infrastructure required as a foundation for custom Facebook API integrations. (e.g. API key configuration, inclusion of needed code snippets)

• Expose selected high-value prepackaged components of Facebook’s API without requiring deep knowledge of the inner workings of the API.

Current features include:

• Basic Facebook Connect integration

• Fan Box portlet

• Feed Form portlet

(Each feature appears separately in the quick installer and Add/Remove Products configlet.)

To see a demonstration of the feed form portlet in use, watch the screencast.

Compatibility

collective.simplesocial requires Plone 3.

It has been tested with Firefox 3.5, Safari 4, and IE 6, 7, and 8.

Fan Box Portlet

Facebook provides a basic “Fan Box” widget which can be used to promote a Facebook Page by prompting visitors to your website to become a fan and allowing them to view the Page’s activity stream and fans.

collective.simplesocial allows insertion of a Fan Box as a portlet.

Prerequisites

This product loads the Fan Box within an iframe, so it does not require a Facebook API key or creating a Facebook application. You must already have created a Facebook Page, however. Take note of the numeric ID of the Page (it appears in the URL when viewing the page in Facebook).

Adding a Fan Box

1. Go to Site Setup.

2. Click Add/Remove Products.

3. Check ‘Facebook Fan Box portlet’ and click Install.

4. Navigate to the location in the site where you want to add the portlet.

5. Click ‘Manage portlets’.

6. Click on the dropdown to add a portlet to the column where you want the fan box to appear, and select ‘Facebook Fan Box’.

7. Paste in the numeric ID of the Facebook Page you want to promote.

8. You may configure whether or not an activity stream appears, the number of fan connections to display, and the width and height of the fan box.

9. Click save and return to the location where you assigned the portlet to view the fan box.

Feed Form Portlet

Facebook allows Facebook Connect sites to publish messages to users’ activity streams via the Open Stream API – in particular, via the FB.Connect.streamPublish method.

collective.simplesocial provides a “Feed Form” portlet. This allows you to configure a dialog which will pop up on page load and prompt the user to post a message to his or her Facebook feed. This can be used to prompt a visitor to your Plone site to publicize some action that they took on the site. For example, you could add this portlet to the thank you page of a PloneFormGen form, asking the user to tell his or her friends about the site.

Since it makes use of the full Facebook Connect API, using the feed form portlet requires first setting up a Facebook Application and setting its API Key in the Facebook Connect control panel in Plone’s site setup.

Creating a Facebook Application

1. Go to the Facebook Developer application. If prompted, allow it access to your profile.

2. Click the Set Up New Application button and fill out the form.

3. Take note of the API Key that is displayed.

4. In the Facebook application’s settings, click on the Connect tab. Enter the URL of the site into the Connect URL field. Note: This site must be publicly accessible in order for communication between Facebook and the site to work.

Adding a Feed Form

1. Go to Site Setup.

2. Click Add/Remove Products.

3. Check ‘Facebook Feed Form portlet’ and click Install.

4. Return to Site Setup.

5. Click Facebook Connect.

6. Paste in the API Key that you recorded above when creating your Facebook application. Click Save. If successful, you should see a yellow message saying that the connection has been verified.

7. Navigate to the location in the site where you want to add the portlet.

8. Click ‘Manage portlets’.

9. Click on the dropdown to add a portlet to the column where you want the feed form to appear, and select ‘Facebook Feed Form’.

10. Edit the settings as prompted. When finished, click Save.

11. Return to the location where you assigned the portlet to view the feed form.

If a visitor to a page with a feed form is not logged into Facebook, then the feed form will not appear automatically. Instead, a message will be shown along with a Facebook Connect button. Clicking this button will allow the visitor to log into Facebook, after which the feed form will be displayed.

Custom Facebook Connect Integration

This product provides the basic pieces needed to integrate with Facebook using custom XFBML and/or the Facebook Javascript API. It is possible to install these basic components without installing either of the above two portlets, by selecting and installing Basic Facebook Connect Integration from the Add/Remove Products configlet.

This will install:

• The Facebook Connect configlet for configuring your API key.

• A browser resource called xd_receiver.htm for facilitating cross-domain communication with Facebook.

• A “feature loader” viewlet in the portaltop viewlet manager, which loads the Facebook Connect javascript and initializes Facebook Connect with the configured API key.

With these pieces in place and a correct API key, you should be able to use XFBML and the Facebook Javascript API wherever you like in Plone templates.

Miscellaneous tips

• The TAL parser likes to complain about mismatched tags when using tags with the ‘fb’ XML namespace. You may need to escape such tags and include them with a tal:replace (see configlet.pt in this package for an example). Or put them in a separate file and include them via a browser view method that reads that file.

• Use the FB.ensureInit method to wrap code that should not run until the Facebook components (which load in a deferred fashion) have completed loading. For example, the following will alert the UID of the logged-in Facebook user once initialization is complete:

  FB.ensureInit(function() {
    alert(FB.Connect.get_loggedInUser());
  });

• Use logic like the following to do something different depending on whether or not the user is already logged into Facebook:

  var fb_status = FB.Connect.get_status().result;
  if (fb_status == FB.ConnectState.connected ||
      fb_status == FB.ConnectState.appNotAuthorized) {
      // -- action if logged in --
  } else {
      // -- action if logged out --
  }

Additional Facebook Connect API Resources

• Facebook Developer Wiki

• Facebook Connect documentation

• Facebook Javascript API

• XFBML

Credits

collective.simplesocial was developed by David Glick as part of ONE/Northwest’s Online Civic Engagement Platform.

Changelog

1.0b1 (2009-08-13)

• Initial release. [davisagli]