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 may not be up-to-date).

Theme functions

theme('facebook_status_item', $status = FALSE, $cacheable = FALSE, $options = array()): 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. $cacheable is a boolean indicating that the status will be used in a static context, so dynamic timestamps like "a moment ago" will be avoided. $options is an associative array of optional settings. Currently the only element of $options is 'exclude,' the value of which should be an array where the values match the names of components from the $components array (see hook_facebook_status_render_components() for what the $components array contains). The specified components will be excluded from rendering.
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 recipient of the message and the PID belongs to the sender.

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, $params = array())

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; all users are included if the array is empty. $pids is an array of User IDs of users whose posted statuses should be returned; all users are included if the array is empty. $total is the maximum amount of statuses that could be returned.

$params is an associative array containing boolean elements 'self only' and 'latest only.' $params['self only'] is disregarded if NULL, causes only statuses posted to one's own profile to be returned if TRUE, and causes only statuses posted to another user's profile to be returned if FALSE. $params['latest only'] causes only the most recent relevant status to be returned if TRUE and is disregarded otherwise. For backwards compatibility, $params can also be a boolean instead of an array. In this case, FALSE corresponds to an empty array, while TRUE corresponds to both array elements being TRUE. Setting $params['latest only'] to TRUE may cause issues in MySQL 4 and PostgreSQL.

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, $alerts = array())

Deletes a status from the database. $sid is a Status ID or a Status object. $alerts is an array specifying which alerts to call, or TRUE or FALSE to set all alerts on or off. These are the defaults:

array(
  'userpoints' => TRUE,
  'rules' => TRUE,
  'trigger' => TRUE,
  'hook_facebook_status_delete' => TRUE,
  'activity2' => TRUE,
);

If $alerts is FALSE, $alerts['hook_facebook_status_delete'] is still set to TRUE.

facebook_status_save_status($account = FALSE, $new_status = '', $options = array())

Saves a status into the database and returns the status object for the status that was just saved. $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.

$options is an array of options that affects what behaviors this function uses. These are the defaults, used if no option is specified for the relevant keys:

/**
 * Meanings of the keys:
 * 'ignore duplicate': disallows saving statuses with the exact same text consecutively.
 * 'ten second override': if a user submits a status within 10 seconds of submitting a
 *   previous status, the first one is removed on the assumption that it was a mistake.
 * 'ignore blank status': allows blank statuses to appear in some status listings.
 * 'alerts': Controls which modules are notified when a status is saved.
 */
array(
  'ignore duplicate' => TRUE,
  'ten second override' => TRUE,
  'ignore blank status' => TRUE,
  'alerts' => array(
    'userpoints' => TRUE,
    'hook_facebook_status_save' => TRUE,
    'trigger' => TRUE, //Also calls Activity 2
    'activity1' => TRUE,
    'rules' => TRUE,
    'twitter' => TRUE,
    'appbar' => TRUE,
    'pathauto' => TRUE,
  ),
);

Of course, alerts are only sent if the relevant modules are enabled. $options['alerts'] can also be TRUE or FALSE, in which case all alerts are enabled or disabled, respectively. There are two exceptions: if $options['alerts'] is a boolean, then $options['alerts']['hook_facebook_status_save'] and $options['alerts']['pathauto'] are always TRUE. Also, to preserve backwards compatibility, if $options itself is either TRUE or FALSE, that is the same as setting $options['alerts'] to the same value.

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.

facebook_status_item_components($status = FALSE, $cacheable = FALSE)

Collects status components from hook_facebook_status_render_components(). $status is a full status object. If not passed, gets the last status for the relevant user automatically. If there is none, uses a default message. $cacheable is a boolean indicating whether the complete text of the rendered status will be stored for future use, so dynamic timestamps and administrative elements (like edit/delete links) should be avoided. Returns an array of themed status components or FALSE if the current user does not have permission to view the status.

Hooks

hook_facebook_status_save($status, $edit = FALSE)

Use to manipulate the status immediately after it is saved into the database, or to react to the status being saved. $status is the new status object, with the extra property "owner" containing the owner's $user object for convenience. $edit is a boolean indicating whether the relevant status is new or being edited.

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_components($status)

Use this to add elements of a status that will appear in the themed version. (If you need to collect components from other modules, use facebook_status_item_components().) Return an array of arrays; the outer array should be keyed by the name of the component. The inner array can have the following elements (all of which are optional except "value"):

type: Either "markup" or "value." "Markup" means the HTML in the "value" element will be included in the final status HTML. "value" means FBSS will not render the component, but other modules can still access it in hook_facebook_status_render_components_alter() and facebook_status_item_components(). Defaults to "markup."
value: The formatted HTML string of this component that can appear in the final HTML of the themed status.
#value: FBSS ignores this, but you can use it to store any data that other modules might want in hook_facebook_status_render_components_alter() or facebook_status_item_components(). This is typically the same as the "value" element, sans any surrounding markup like spaces and punctuation.
#unformatted: FBSS ignores this, but you can use it to store any data that other modules might want in hook_facebook_status_render_components_alter() or facebook_status_item_components(). This is typically a raw, unformatted value.
weight: Controls the arrangement of components in the themed status. Lower values (i.e. negative numbers) appear earlier in the themed status.
prefix: HTML that will appear before the 'value' element. (The 'value' element itself is wrapped in a "span" tag.)
suffix: HTML that will appear after the 'value' element.
access callback: If specified, this component will only appear if this function returns TRUE. Most commonly "user_access." If not specified, no access restriction is applied, although users still must have permission to see the whole status ("view all statuses").
access arguments: An array of arguments to pass to the access callback, if there is one.

Note that this hook is only called in theme functions. It is not called in Views, since the purpose of Views makes this hook redundant.

hook_facebook_status_render_components_alter(&$components, $status)

Allows adding to, modifying, or removing components of the themed HTML version of a status. The $components array is structured as described above in hook_facebook_status_render_components(). $status is the relevant status object, with the extra property "cacheable." (Avoid dynamic constructions like "a moment ago" if the status is cacheable to avoid confusion.)

Note that this hook is primarily called in theme functions. It is not usually called in Views because each component is rendered separately in Views, and calling this hook for each component individually could be slow. The exception is for the "status text" field. This exception is made because it is the most common case. If you need to change the way other Views fields are rendered, do it the Views way, using hook_views_pre_render(&$views), hook_views_data_alter(&$data), or similar.

hook_facebook_status_render_alter(&$output, $status, $components)

Allows changing the final HTML of the status display immediately before it is displayed to the user. $output is the HTML string. $status is the relevant status object, with the extra property "cacheable." (Avoid dynamic constructions like "a moment ago" if the status is cacheable to avoid confusion.) $components is a structured array of the data that make up a status. See hook_facebook_status_render_components() for details about the structure of the $components array.

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.
See #680614: post only on friends' profile for examples of this hook in use.

hook_facebook_status_form_ahah_alter(&$new_form, $form)

Ensures that elements added to the status update form remain part of the form when it is refreshed using AHAH. Modules implementing this hook should copy the elements they added from $form to $new_form.

hook_facebook_status_save_options_alter(&$options)

Allows changing the $options array in facebook_status_save_status() before those options are applied.

hook_facebook_status_delete_alerts_alter(&$alerts, $sid)

Allows changing the $alerts array in facebook_status_delete_status() before those alert settings are applied. $sid is the Status ID of the status that is being deleted.

hook_facebook_status_refresh_selectors($account)

Allows specifying parts of a page to refresh via AHAH when the status update form is submitted and AHAH status submitting is enabled. Should return an array of DOM selectors valid in jQuery/CSS. $account is the $user object of the user to whose profile the status will be posted. (The global $user object is the poster.)

Example:

<?php
/**
 * Implements hook_facebook_status_refresh_selectors().
 */
function mymodule_facebook_status_refresh_selectors($account) {
  $selectors = array(
    '.view-user-example', 
    '#mymodule-block-foo', 
  );
  return $selectors;
?>

A "Refresh" link is automatically appended to any refreshable content specified by this hook. If you want to add a "Refresh" link elsewhere, you can: FBSS will automatically detect any refresh link that is wrapped in another element with the class "facebook_status_refresh_link". For example, you might write

<div class="facebook_status_refresh_link">
  <?php print l(t('Refresh'), $_GET['q']); ?>
</div>

However, note that you should ideally put the "Refresh" link outside any element wrapping a view that has AHAH enabled in its settings. It will still work if you don't, but it will slow down significantly after using Views AHAH features (like paging).

hook_facebook_status_refresh_selectors_alter(&$selectors, $account)

Allows changing the $selectors specified by implementations of hook_facebook_status_refresh_selectors().

JavaScript Events

ahah_success = function(context)

When FBSS is enabled and any form is submitted via AHAH, the "ahah_success" event is triggered. Bound events are passed a "context" variable which is basically the jQuery object representing the wrapper for the AHAH callback specified in the PHP form structure (i.e. the DOM element with ID $form['mysubmitbutton']['#ahah']['wrapper']). Use this to make sure you're only reacting when the correct form is submitted. For example, you may want to do something like this:

  //#facebook_status_replace is the wrapper ID specified by the status update form.
  $('#facebook_status_replace').bind('ahah_success', function(context) {
    //Only run this function if the status update form was submitted.
    if ($(context.target).html() != $(this).html()) {
      return;
    }
    //Do stuff...
  }

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/statuses/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:

<statuses>
  <status>
    <text>is happy.</text>
    <time>1234567890</time>
    <sid>50</sid>
    <uid>1</uid>
  </status>
</statuses>

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.