collective.simplesocial 1.2

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.

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.

Customizing the Feed Attachment

When a user submits a feed form, collective.simplesocial sends along an attachment to Facebook with information about the content item where the feed form was displayed. By default, this attachment contains the following information:

• The title of the content item

• The URL of the content item

• The content item’s description, if it provides one

• The content item’s tile image, if it provides one, or the site logo

These defaults are provided by the DefaultFeedFormDataProvider adapter. It is possible to override the defaults globally or for a particular content type by registering an adapter that provides the IFeedFormDataProvider interface. This interface provides methods for getting the attachment for the current context and for overriding the settings specified in the portlet assignment. For more information, see collective.simplesocial.feedform.facebookfeedform.IFeedFormDataProvider and the documentation for the FB.Connect.streamPublish method and Attachment object.

Configuring the ‘Post to Fan Page’ feature

1. Follow the instructions above for creating a Facebook Application.

2. Go to Site Setup.

3. Click Add/Remove Products.

4. Check ‘Post to Facebook Fan Page’ and click Install.

5. Return to Site Setup.

6. Click Facebook Connect.

7. 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.

8. Select the Facebook fan page you want to post to.

Now the ‘Post to Fan Page’ link should show up when you are logged in. To post to Facebook, click on the link. You will be prompted to confirm the message that will be posted.

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

1.2 (2010-04-06)

• Fixed a unicode decode bug in the JSON serializer. [yomatters]

1.1 (2010-03-26)

• Added the ‘Post to Fan Page’ feature. [davisagli]

• Stripped line breaks from the description in the default feed form adapter to avoid breaking the javascript. [yomatters]

• Added a view to resize the site logo to the size that Facebook requires. [yomatters]

• Added an adapter interface so that we can override the feed form portlet and attachment settings on a per-site or per-content-type basis. [yomatters]

1.0 (2009-12-22)

• Add z3c.autoinclude Plone plugin entry point. [davisagli]

• Fix control panel authenticator to work in Plone 4. [davisagli]

• Added a jq() wrapper to the feature loader initialization call so that it doesn’t happen until the DOM is fully loaded. [yomatters]

• Removed bogus dependency of the Fan Box profile on the Basic Facebook Connect integration profile. [davisagli]

1.0b1 (2009-08-13)

• Initial release. [davisagli]