Twitter

Jetpack's Twitter library, jetpack.lib.twitter, is a very simple, lightweight layer on top of Twitter's REST API. In fact it's hardly more than syntactic sugar for doing XMLHttpRequests.

To use this library, you therefore need to be familiar with Twitter's own API. (It's easy!)

Methods

Each method in Twitter's API maps to a method here. For example, the Twitter method for tweeting, statuses/update, maps to jetpack.lib.twitter.statuses.update(). To call trends/current, use jetpack.lib.twitter.trends.current(). For search, jetpack.lib.twitter.search(). Replace slashes with dots.

Most of Twitter's methods are supported, but not all.  List methods, spam reporting methods, and OAuth are not currently supported.  If something is not supported but you would like it to be, please file a bug.  (Or write a patch!)

Arguments

Each and every method in the library takes a single argument, an object. There are two styles you can use to define this object.

The first is simple: Define properties on the object corresponding to the parameters of the Twitter method. For instance, some Twitter methods have an id parameter, so you would define an id property and set its value to a user's ID. (You can read about the parameters of the various methods at Twitter's API reference.) There are two special, optional properties: success and error. success is a function that's called when the request successfully completes, and error is a function called when it fails to complete. The library simply passes them to jQuery.ajax(), and so they are called like so:

• success(data, textStatus)
  • data is Twitter's decoded JSON response.
  • textStatus is a simple string describing the status.
• error(xmlHttpRequest, textStatus, errorThrown)
  • xmlHttpRequest is the XHR used in the request.
  • textStatus is a simple string describing the type of error.
  • errorThrown is an exception object, if one was thrown.

The examples below all use this first, simpler style.

The second style will be familiar if you have used jQuery.ajax() -- in fact the object is passed as-is (almost) to it. In other words, define a data property that is itself an object whose properties correspond to the parameters of the Twitter method. With this style you can use any of the various jQuery.ajax() options in your request: data, success, complete, etc. Example:

jetpack.lib.twitter.statuses.update({
  data: {
    status: "O frabjous day!"
  },
  username: "basic_auth_username",
  password: "basic_auth_password",
  success: function () console.log("Hey!")
});

User authentication

You can supply a username and password to methods that require authentication using the second, more advanced call style described above.

Or you can simply rely on Firefox. When you call a method that requires authentication -- such as jetpack.lib.twitter.statuses.update() -- without providing a username or password, Firefox will prompt the user for them if she is not already authenticated with Twitter.

Both methods use HTTP basic authentication.  In the future, the library may support OAuth.  See Twitter's authentication documentation for related information.

FAQ

See Twitter's API FAQ.  Since Jetpack's Twitter library is a very thin wrapper around Twitter's API, most everything there applies here, and not much applies here that doesn't apply there.

Example usage

Tweeting

jetpack.lib.twitter.statuses.update({ status: "O frabjous day!" });

Firefox will prompt for a username and password if the user is not already authenticated with Twitter.

User info

jetpack.lib.twitter.users.show({
  id: "mozlabs",
  success: function (data, status) console.log(data.toSource()),
  error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});

Friends of a user

jetpack.lib.twitter.statuses.friends({
  id: "mozlabs",
  page: 3,
  success: function (data, status) console.log(data.toSource()),
  error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});

Trends

jetpack.lib.twitter.trends({
  success: function (data, status) console.log(data.toSource()),
  error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});

Searching

jetpack.lib.twitter.search({
  q: "#jetpack",
  lang: "ja",
  rpp: 10,
  page: 5,
  since_id: 1337,
  success: function (data, status) console.log(data.toSource()),
  error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});