Facebook-style Statuses: API and Theming

Facebook-style Statuses provides a robust API to allow developers (and themers) to shape their site the way they want it. This page refers to the 2.x branch of Facebook-style Statuses.

See also the drupalcontrib.org function documentation taken straight out of the code (but be aware that it is based on a beta version of the FBSS code and so is not up-to-date).

Theme functions

See also the Facebook-style Statuses Tags theme functions.

theme('facebook_status_item', $status = FALSE, $historical = FALSE)

Formats a status as text. $status is a full status object; the latest status for the current user will be used if no status is passed. $historical indicates that the status will be used in a static context, so dynamic timestamps like "a moment ago" will be avoided.

theme('facebook_status_form_display', $account = FALSE, $size = FALSE, $view = FALSE)

Builds a status update form and everything associated with it according to settings, or displays the status if the current user does not have permission to edit the status of the user specified by $account. $account is the $user object for the user whose status or status update form will be displayed; if it is FALSE, the user will be automatically detected according to settings. $size is the length of the status update textfield; leave at FALSE to use the setting. $view is the name of a view to append to the form in order to allow the view to update via AJAX when a status is submitted. Of course, this only works if Views is enabled. More on that feature here.

theme('facebook_status_time', $status_time)

Formats times to be user-friendly. "A moment ago" (or its translation) is displayed for statuses submitted under a minute ago; "[time] ago" is displayed for statuses submitted within the last 3 days; a short date/time is displayed for statuses submitted earlier than that. $status_time is the Unix timestamp for when the relevant status was submitted.

Developer API

See also the Facebook-style Statuses Tags API.

Note that "status objects" contain a Status ID (sid), User ID (uid), Poster ID (pid), timestamp (status_time), and status text (status). If the UID and PID are not the same, then the UID belongs to the user who owns the profile on which the relevant status was posted.

facebook_status_get_status($uid = 0, $pid = 0, $count = 1, $instance = -1, $exclude_blank = TRUE)

This function handles most of the responsibility for retrieving statuses from the database. It gets $count number of status updates by the user whose User ID is $pid from the profile of the user whose User ID is $uid and returns an array of status objects (or FALSE if it fails). If $uid or $pid is zero, the current user is assumed. If either is FALSE, it is ignored. If $instance is negative, it starts from the $instance-th most recent status; if it is positive, it gets statuses submitted after the timestamp. For example, facebook_status_get_status(FALSE, 1, 3, -10) will get the tenth, ninth, and eighth most recent statuses posted by User 1. If $count or $instance is zero, all statuses are retrieved that meet the other existing conditions; setting both $count and $instance to zero will retrieve all statuses. $exclude_blank controls whether blank statuses will be included in the results that are returned.

facebook_status_get_statuses($uids = array(), $pids = array(), $total = 0, $latest_only = FALSE)

Gets the most recent statuses for multiple users and returns an array of status objects. Does not return blank statuses. $uids is an array of User IDs of users on whose profiles are statuses that should be returned. $pids is an array of User IDs of users whose posted statuses should be returned. $total is the maximum amount of statuses that could be returned; $latest_only will cause only the most recent status for each specified user to be returned. If $uids or $pids is an empty array, those restrictions will be ignored. This function can be slow on large sites, particularly depending on the parameters passed to it.

facebook_status_has_status($uid = FALSE, $pid = FALSE)

Returns the number of statuses a user has, which (obviously) can be used to determine whether the user has any statuses at all. Statuses that are counted were posted to the profile of the user whose UID is $uid and were posted by the user whose UID is $pid. If $uid is FALSE, the current user is assumed. If $pid is FALSE, it is ignored.

facebook_status_load($sid)

Returns a status object. $sid is the Status ID. Status objects contain a Status ID (sid), User ID (uid), Poster UID (pid), timestamp (status_time), and status text (status). The User ID belongs to the user on whose profile the relevant status was posted.

facebook_status_delete_status($sid)

Deletes a status from the database. $sid is a Status ID or a Status object.

facebook_status_save_status($account = FALSE, $new_status = '', $save_alerts = TRUE)

Saves a status into the database. $account is the $user object for the user onto whose profile the new status will be saved (the current user by default), and $new_status is the status text to be saved. If $save_alerts is TRUE, other modules will be alerted that FBSS is saving a status; otherwise the status will save silently, which is useful for modules wishing to record their own alert messages. Returns the status object for the status that was just saved.

facebook_status_choose_owner($legacy = array())

Returns the $user object of the user whose status should be displayed on the current page. If $legacy is an array, it can hold either no values, or TRUE in the keys 'user,' 'node,' or 'user' and 'node.' If 'user' is in the array, the owner of the profile page will be returned if the current page is a user profile; similarly, if 'node' is in the array, the author of the node will be returned if the current page is a node. Otherwise, the current user is returned. If $legacy is FALSE, the module's settings are used.

facebook_status_can_post($owner = NULL, $poster = NULL)

Determines whether a user has permission to post a message on another user's profile. $owner is the $user object for the user onto whose profile the message will be posted. If not specified, the module automatically determines the user. $poster is the $user object for the user posting the message. If not specified, the current user is assumed. Returns TRUE if $poster has permission to post on $owner's profile, and FALSE otherwise.

Hooks

hook_facebook_status_save($account, $status, $sid, $edit = FALSE)

Use to manipulate the status immediately after it is saved into the database, or to react to the status being saved. $account is the $user object for the user on whose profile the relevant status was posted. (The global $user is the poster.) $status is the new status text that was just saved. $sid is the new Status ID. $edit is a boolean indicating whether the relevant status is new or being edited. This hook is not called if the status being "saved" is identical to the previous one.

hook_facebook_status_delete($sid)

Used to manipulate the status before it is deleted, or to react to the status being deleted. $sid is the status ID of the status that is about to be deleted.

hook_facebook_status_render_alter(&$status_text, $owner, $poster, $status)

Allows changing the status before it is displayed to the user, for example to add links or extra information. $status_text is the text of the status display, already run through input filters if the admin has set an input format. $owner is the $user object for the user on whose profile the status was posted; $poster is the $user object of the user who posted the status. $status is the full status object. $status also has the extra property "historical," which is a boolean indicating whether the status is static. In other words, if $status->historical is TRUE, avoid dynamic constructions like "a moment ago" which are confusing when displaying historical records (such as those displayed by the Activity module). No return is necessary.

hook_facebook_status_post_access_alter(&$allow, $owner, $poster)

Allows setting whether $poster is allowed to write a message to $owner. User relationship modules could use this for instance to only allow users who are "friends" to write on each others' profiles. $allow is a boolean; set it to FALSE if your module determines that $poster is not allowed to write a message to $owner, but don't change it otherwise. $owner is the $user object for the user on whose profile the message will be posted; $poster is the $user object of the user who is posting the message. $owner and $poster can represent the same user.

Open API

The Open API allows other sites or applications to get data about the statuses on your site via a GET request that can return XML, JSON, or simple text. The request must be made to http://example.com/status/openapi and can have the following parameters:

type

One of "user," "tag," "public," "userref," or "trend." "User" gets statuses from a specific user, "tag" gets statuses tagged with the relevant term, "public" gets all statuses, "userref" gets statuses referencing the relevant user, and "trend" gets taxonomy terms that have been used frequently in the relevant time period. "Userref" is only available if the Facebook-style Statuses Tags submodule is enabled; "tag" and "trend" also require this module, and Taxonomy must be enabled as well. If no type is given and the "name" parameter is not present, defaults to "public." If none is given and the name parameter is present, defaults to "user."

format

One of "xml," "json," or "short." XML and JSON are self-explanatory; "short" returns only the most recent status of those requested. If none is given, defaults to "short." All error messages are presented as if "short" was the format.

name

If type is "user," the name of the user for which to retrieve statuses (assumes the owner and poster are the same). If type is "tag," the name of the term which retrieved statuses will be tagged with. Do not include the hash character (#). If type is "userref," the name of the user who is referenced in the retrieved statuses. If type is "trend," a word indicating the time period to use to measure term popularity: "day," "week," "month," "year," "all." Ignored if type is "public."

count

The number of statuses to return (or terms to return if type is "trend"). Defaults to 1. Ignored if format is "short."

In XML, the result of a good request will provide a structure similar to this:

The result of a JSON request has the same structure but the data is in arrays. Requests of type "trend" will look similar.

HTTP Response codes

If the response is successful, the server will return the HTTP/1.x 200 OK header. If there is an error, the server will return the header HTTP/1.x 400 Bad Request. If the server finds no results for the request, the header will be set to HTTP/1.x 204 No Content.