Comments Box

From Facebook Developer Wiki

Jump to: navigation, search

A Comments Box is a standalone social widget for any website or IFrame application. You can use it to easily allow your users to comment on your content -- whether it's for a Web page, article, photo, or other piece of content -- right on your site or application. Then the user can share the comment on Facebook as a Feed story -- both on that user's Wall and in the user's friends' streams. This is a great way to have your users engage in an asynchronous way on your site, whether it's a blog, news site, or review application.

The Comments Box lets users:

  • Log in to your site using their Facebook accounts with Facebook Connect or comment anonymously.
  • Add comments directly onto your site or application.
  • Display their Facebook profile information next to their comments.
  • View and browse through all comments made in the Comments Box.
  • Share their comments directly on their Facebook profile and in their friends' home page streams. Each story on Facebook includes a link back to the page the comments box is on (per your configuration)

Contents

Technical Notes

The Comments Box is simply the XFBML version of the fb:comments tag.

You can access all comments made through the Comments Box via an API call or FQL query for further use in your application or for archival purposes.

The Comments Box can handle substantial load, and you can even deploy multiple Comments Boxes on your site or in your application. But for an individual Comments Box, you should not have more than 100,000 simultaneous accesses per minute by your users.

Adding a Comments Box to Your Site or IFrame Application

To add a Comments Box to your site, all you need to do is get a Facebook Platform API key, add a small file to your site, and add a few lines of code.

  1. Go to http://www.facebook.com/developers/createapp.php to create a new application.
    1. Enter the name of your site in the Application Name field, read and accept the Developer Terms of Service, then click Save Changes.
    2. On the Basic tab, keep all of the defaults and you should upload an Icon. This icon appears in Feed stories published on Facebook. Take note of the API Key, you'll need this shortly.
      Note: If you already have an API key for your Facebook Connect site or another Facebook social widget like the Fan Box or Live Stream Box), then you must use that API key instead.
    3. On the Connect tab, set the Connect URL to your server so Facebook can verify the call is coming from you (previously this was known as the Callback URL).
    4. You should include a logo that appears in the Facebook Connect dialog. Next to Facebook Connect Logo, click Change your Facebook Connect logo and browse to an image file. The logo can be up to 99 pixels wide by 22 pixels tall, and must be in JPG, GIF, or PNG format.
    5. Click Save Changes.
  2. Download a cross-domain communication channel file, then upload it to the directory with the file that will reference the Comments Box. This file will allow your site and Facebook to send data back and forth.
  3. Edit the HTML file where you plan to reference the Comments Box.
    1. Within the <html> tag, add this attribute: xmlns:fb="http://www.facebook.com/2008/fbml", as in:
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

    2. Next, add the following code to each file where you want a Comments Box to appear. Replace YOUR_API_KEY_HERE with the API key you received earlier (or you received for another Facebook Connect implementation), and include the path to xd_receiver.htm.
      <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
      <fb:comments></fb:comments>
      <script type="text/javascript"> FB.init("YOUR_API_KEY_HERE", "<path from web root>/xd_receiver.htm"); </script>

  4. That's it! You've just installed your own Comments Box, now try it out!

Important: If you want to place a Comments Box on a page on your site that already references Facebook Connect (that is, the page contains one script that calls FeatureLoader.js.php and another that calls FB.init), then you must not reference these scripts again. You simply can just put in the fb:comments tag where you want the Comments Box to appear. As in:

<fb:comments></fb:comments>

Publishing Comments to Facebook

The Comments Box integrates with Facebook. When a user posts a comment, the user is prompted to publish the comment on Facebook. Facebook provides one line and short story templates for the Feed stories, so you don't have to worry about creating Feed story templates.

Once a comment appears on a user's profile, the user and any friends can post new comments on the user's Wall on Facebook. However, those comments do not get posted back to the Comments Box on your site.

Users also can delete the comments they made, either on Facebook or in your Comments Box. Comments deleted from the profile do not get deleted from the Comments Box.

Administering Your Comments Box

Administering your Comments Box is simple. You can assign administrators and moderators and set permissions inline (click the Administer Comments link). Or do it on the Widgets tab in the Developer application. You can also see the XID for your Comments Box here.

The administrator of the Comments Box can delete any comments directly or on Facebook. Only a developer of your application can add administrators and moderators. To add a moderator or admin, enter the name of a Facebook friend.

Decide whether you want a blacklist or a whitelist for allowing comments. In blacklist mode, any users you specify cannot comment on your site. In whitelist mode, only the users you specify can comment on your site. You can also allow anonymous comments.

Sample Comments Box File

Here's the entire content of a file

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml"> <head></head> <body> <div> YOUR PAGE CONTENT </div> <fb:comments></fb:comments> <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script> <script type="text/javascript"> FB.init("YOUR_API_KEY_HERE", "xd_receiver.htm"); </script> </body> </html>


Keep in mind that we generally recommend that you specify an XID to keep randomly appended/modified GET parameters from unintentionally specifying a different, unique Comments Box. See fb:comments (XFBML) for the full documentation.

Retrieving Comments Box Comments

As the administrator of your Comments Box, you can retrieve all the comments made to your Comments Box by calling comments.get or querying the comment (FQL) table with fql.query. Make sure to specify your XID, which you can find in the admin panel for the Comments Box.

Listening for Comments Box Events

You can listen for the login/logout actions of your Comments Box just like Facebook Connect. See Detecting Connect Status. You can also receive a JavaScript action with the comment whenever one is added. This involves the using these two methods:

  • FB.CommentClient.add_onComment: registers a handler to be called with a comment object (with properties post and user) when a user makes a comment.
  • FB.CommentClient.remove_onComment: deregisters a handler (given above).

Example

<script type="text/javascript"> FB.init("<YOUR API KEY>", "/xd_receiver.html"); FB_RequireFeatures(["Comments"], function() { FB.CommentClient.add_onComment(function(comment){ alert("user " + comment.user + " wrote: " + comment.post); }); }); </script>

See Also

Retrieved from "http://wiki.developers.facebook.com/index.php/Comments_Box"