A JavaScript layer for the Twitter/Identi.ca API

Author
Daniel Glazman (Disruptive Innovations)
Date
14-apr-2009
This version
1.01
Previous version
1.0

Copyright (c) PagesJaunes 2008-2009


Abstract

This is the documentation for the Twitter/Identi.ca JavaScript layer released by PagesJaunes and implemented by Disruptive Innovations. This work is released tri-licensed under MPL/GPL/LGPL.

The last version of the source is available from here. Please see the release notes to learn more about this version.

The JavaScript source file is ready to be used as a JSM JavaScript module or a normal chrome JavaScript file. In the latter case, commenting out the line var EXPORTED_SYMBOLS = ["TwitterHelper"]; is a good thing. 

Warning: the file is not meant to be used as is inside a Web page. You will need minor tweaks to do that, a future version of the file will address that case.

Comments and suggestions on this document or on the code itself should be sent to the author.


Table of Contents

  1. Abstract
  2. Table of Contents
  3. Release Notes
  4. Creating a TwitterHelper object
  5. Callbacks
    1. Success callbacks
    2. Error callbacks
  6. Calls to the public API
    1. Statuses calls
      1. Friends Timeline
      2. User Timeline
      3. Friends
      4. Followers
      5. Show
      6. Replies
      7. Destroy
      8. Public Timeline
      9. Update
    2. Users calls
      1. Show
    3. Direct Messages calls
      1. Inbox
      2. Sent
      3. New
      4. Destroy
    4. Friendships calls
      1. Create
      2. Destroy
      3. Exists
    5. Friends calls
      1. Ids
    6. Followers calls
      1. Ids
    7. Account calls
      1. Verify credentials
      2. End session
      3. Update delivery device
      4. Update profile colors
      5. Rate limit status
    8. Favorites calls
      1. Favorites
      2. Create
      3. Destroy
    9. Notifications calls
      1. Follow
      2. Leave
    10. Blocks calls
      1. Create
      2. Destroy
    11. Help calls
      1. Test
  7. Helpers
    1. Check if a text is a mention
  8. Acknowledgements

Release Notes

Version 1.01, 14-apr-2009:

Version 1.0, 06-apr-2009:


Creating a TwitterHelper object

Creating a TwitterHelper object is the first thing you should do to use twitter in your own code:

var twh = new TwitterHelper(aAccount,
 aPassword,
aThrobber,
aServiceStr);

where

aAccount
is a string containing the account used to connect to Twitter or Identi.ca
aPassword
is a string containing the password associated to the account just above
aThrobber
is a XUL element that is supposed to carry the hidden attribute being "true". When a XmlHTTPrequest is sent to the Twitter or Identi.ca API, the attribute is removed and it's reset to its original true value when the request is completed.
aServiceStr
is a string representing the service your helper is supposed to call: "twitter" for Twitter and "identi.ca" for Identi.ca

Callbacks

All your calls to the TwitterHelper object to call the Twitter or Identi.ca API will result in asynchronous calls. After the completion of the request, one of two callbacks you provide will be called, depending on the success or failure of the request.

If you don't want to provide a callback in a call, use the null JavaScript value instead.

Success callbacks

Success callbacks are JavaScript functions that take three parameters:

parameter 1: aTwitterHelper
is a recall of the TwitterHelper object that was used to make the call
parameter 2: aAnswer
is an nsIDOMDocument if you requested an XML-based answer or a JavaScript object if you requested a JSON answer
parameter 3: aContext
is arbitrary data that you provided when you called the TwitterHelper and that is passed unchanged to the callback

Error callbacks

Error callbacks are JavaScript functions that take three parameters:

parameter 1: aTwitterHelper
is a recall of the TwitterHelper object that was used to make the call
parameter 2: aRequest
is the XmlHTTPRequest that caused an error
parameter 3: aContext
is arbitrary data that you provided when you called the TwitterHelper and that is passed unchanged to the callback

Calls to the public API

All calls to the Twitter or Identi.ca API takes the same first four parameters:

parameter 1: aCallback
a success callback
parameter 2: aErrorCallback
an error callback
parameter 3: aContext
arbitrary data to be passed to the callbacks
parameter 4: aFormat
a lower-case string containing the format of the requested answer: "xml", "rss", "atom" or "json". Please note that not all formats are available for all API calls. Please refer to the Twitter API or the Twitter-compatible Identi.ca API.

In the code chunks below, extra parameters (i.e. above the fifth one) that cannot be null or empty are bolden.

Statuses calls

Friends Timeline

Retrieves the friends timeline of the authenticated user.

twh.statuses.friends_timeline(aCallback,
aErrorCallback,
aContext,
aFormat,
aSince,
aSinceId,
aCount,
aPage);

User Timeline

Retrieves the timeline of a given user or of the authenticated user if aUserId is null.

twh.statuses.user_timeline(aCallback,
aErrorCallback,
aContext,
aFormat,
aUserId,
aSince,
aSinceId,
aCount,
aPage);

Friends

Retrieves the list of friends of the authenticated user or of a given user if aUserId is not null.

twh.statuses.friends(aCallback,
aErrorCallback,
aContext,
aFormat,
aUserId,
aPage);

Followers

Retrieves the list of followers of the authenticated user or of a given user if aUserId is not null.

twh.statuses.followers(aCallback,
aErrorCallback,
aContext,
aFormat,
aUserId,
aPage);

Show

Retrieves a single status.

twh.statuses.show(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Replies

Retrieves the list of mentions of the authenticated user in the public timeline.

twh.statuses.replies(aCallback,
 aErrorCallback,
aContext,
aFormat,
aSince,
aSinceId,
aPage);

Destroy

Destroys a status of given id. The status must have been created by the authenticated user.

twh.statuses.destroy(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Public Timeline

Retrieves the public timeline.

twh.statuses.public_timeline(aCallback,
 aErrorCallback,
 aContext,
 aFormat);

Update

Sends a new message to Twitter or Identi.ca from the authenticated user. Warning, do NOT use a non-null aSource parameter if your twitter application is not registered by Twitter...

twh.statuses.update(aCallback,
 aErrorCallback,
aContext,
aFormat,
aText,
aInReplyToStatusId,
aSource);

Users calls

Show

Retrieves information about a user. One of aUserId and aEmail parameters must not be null or empty.

twh.users.show(aCallback,
aErrorCallback,
aContext,
aFormat,
aUserId,
aEmail);

Direct Messages calls

Inbox

Retrieves the list of current direct messages for the authenticated user.

twh.direct_messages.inbox(aCallback,
 aErrorCallback,
aContext,
aFormat,
aSince,
aSinceId,
aPage);

Sent

Retrieves the list of direct messages sent by the authenticated user.

twh.direct_messages.sent(aCallback,
 aErrorCallback,
aContext,
aFormat,
aSince,
aSinceId,
aPage);

New

Sends a new direct message from the authenticated user.

twh.direct_messages.new(aCallback,
aErrorCallback,
aContext,
aFormat,
aUser,
aText);

Destroy

Destroys a direct message sent or received by the authenticated user.

twh.direct_messages.destroy(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Friendships calls

Create

Adds a new friend to the list of friends of the authenticated user.

twh.friendships.create(aCallback,
aErrorCallback,
aContext,
aFormat,
aId,
aFollow);

Destroy

Removes a friend from the list of friends of the authenticated user.

twh.friendships.destroy(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Exists

Verifies if a friendship relation exists between two users.

twh.friendships.exists(aCallback,
aErrorCallback,
aContext,
aFormat,
aUserA,
aUserB);

Friends calls

Ids

Retrieves the list of ids of the authenticated user's friends or of user aId if that parameter is not null.

twh.friends.ids(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Followers calls

Ids

Retrieves the list of ids of the authenticated user's followers or of user aId if that parameter is not null.

twh.followers.ids(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Account calls

Verify credentials

Verifies the credentials for the current authenticated user.

twh.account.verify_credentials(aCallback,
 aErrorCallback,
aContext,
aFormat);

End session

Ends the session for the current authenticated user. Warning, not implemented by identi.ca for the time being.

twh.account.end_session(aCallback,
 aErrorCallback,
aContext,
aFormat);

Update delivery device

Updates the delivery device for the authenticated user. Parameter aDevice must be a string: "sms" or "im" or "none".

twh.account.update_delivery_device(aCallback,
  aErrorCallback,
  aContext,
  aFormat,
  aDevice);

Update profile colors

Updates the colors stored in the authenticated user's profile. At least one of the color parameters must be non-null.

twh.update_profile_colors(aCallback,
 aErrorCallback,
aContext,
aFormat,
aBackgroundColor,
aTextColor,
aLinkColor,
aSidebarFillColor,
aSidebarBorderColor);

Rate limit status

Retrieves the current rate limit status of the authenticated user.

twh.account.rate_limit_status(aCallback,
 aErrorCallback,
aContext,
aFormat);

Update profile

Updates the profile of the current authenticated user.

twh.account.update_profile(aCallback,
 aErrorCallback,
aContext,
aFormat,
aName,
aEmail,
aUrl,
aLocation,
aDescription);

Favorites calls

Favorites

Retrieves the list of favorites of the authenticated user or of user aUserIf if it is not null.

twh.favorites.favorites(aCallback,
 aErrorCallback,
aContext,
aFormat,
aUserId,
aPage);

Create

Declare a status a a favorite of the authenticated user.

twh.favorites.create(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Destroy

Removes a favorite from the list of favorites of the authenticated user.

twh.favorites.destroy(aCallback,
 aErrorCallback,
aContext,
aFormat,
aId);

Notifications calls

Follow

Enables notifications for updates from the specified user aUserId to the authenticating user.

twh.notifications.follow(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Leave

Disabled notifications for updates from the specified user aId to the authenticating user.

twh.notifications.leave(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Blocks calls

Create

Blocks the user specified in the aId parameter as the authenticating user.

twh.blocks.create(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Destroy

Unblocks the user specified in the aId parameter as the authenticating user.

twh.blocks.destroy(aCallback,
aErrorCallback,
aContext,
aFormat,
aId);

Help calls

Test

Tests the API.

twh.help.test(aCallback,
 aErrorCallback,
aContext,
aFormat);

Helpers

Check if a text is a mention

Checks if a text is a mention, i.e. if it contains the account name of the authenticated user immediately following an "@" character.

twh.isMention(aText);

where aText is a string. Answer is a boolean.

Acknowledgements

This space reserved for future use.