Last updated March 24, 2012. Created by IceCreamYou on May 18, 2011.
Edited by alexmc. Log in to edit this page.
Documentation for the Comments and Tags submodules are on their respective handbook pages. This page provides API documentation for the Facebook-style Statuses (Microblog) module. (It also forms part of the documentation for the Drupal 7 version of Facebook Statuses which is now called Statuses. There are small differences between the two as the 7.1.x version is a straight port of the D6 version)
Overview
From a user's perspective, this module provides a small form where they type in some text and click "share" and everything updates via AJAX. From a developer's perspective, this is backed by status objects and an AHAH form (ID facebook_status_box). Each status object consists of an ID, message, created time, sender, recipient, and recipient type. The recipient type is important because different kinds of recipients are possible. Status messages can be sent to users, groups, other kinds of nodes, and potentially other entities like taxonomy terms as well. In the familiar language of Facebook, the places where these status messages are collected are user walls, group walls, and page walls. In Facebook-style Statuses, they are called user streams, group streams, and node streams.
Contexts
A context system determines what type of recipient the current user is looking at (and consequently, who the recipient of status messages is). In code, a $context array consists of various properties defined in hook_facebook_status_context_info(). Of these, the most important is the "handler" property, which contains a context handler object. If you need to work with contexts, you will likely be doing most of your work with $context['handler']. The default context handlers are defined and fully documented in facebook_status.contexts.inc. You can get the current context by calling facebook_status_determine_context(), or get an array of all of them by calling facebook_status_all_contexts().
CRUD API
FBSS also has a robust CRUD API that consists of the facebook_status_save_status(), facebook_status_edit_status(), facebook_status_delete_status(), facebook_status_load()/facebook_status_get_statuses() functions. A number of hooks and alters also allow responding to CRUD events and altering various options and properties. Drupal Core's hook_link() system for nodes and comments is extended for use with statuses.
AJAX form
When a status update form is submitted, FBSS uses JQuery to re-load the current page silently in the background. It then uses this new version of the page to replace specified regions on the old one without a visible page refresh. The regions are specified in PHP using hook_facebook_status_refresh_selectors() and its accompanying alter hook. This allows building an array of DOM paths that is passed to the JavaScript. The system is flexible enough to accommodate DOM paths that identify multiple regions on the same page, but at the time of writing it can't handle content that is loaded onto the page via AJAX (since that content won't be on the refreshed page that is loaded silently in the background).
API functions, Hooks, Templates, and Theme functions
The code that you should use to interact with FBSS is explained in the children of this page (click the links below).