Twitter Plugin

Summary

Installation

To integrate the plugin into your application just run the 'install-plugin' Grails script, e.g.

grails install-plugin twitter

Description

The Twitter plugin allows you to view and update Twitter information.

The current release (0.2) of the plugin ships with a jar that was built using JDK6. If you're using JDK5 please replace plugins/twitter-0.2/lib/json-112808.jar with the fixed version found here. This was unintentional - there's no JDK6-specific code - and will be fixed in the next release.

The plugin uses the JTwitter API, although it uses a slightly modified version with some bug fixes that have been submitted back to the API author.

Installation

To integrate the plugin into your application just run the 'install-plugin' Grails script, e.g.

so if you're logged in you would call getUserTimeline() and if you need to pass credentials you would call getUserTimeline([username: 'foo', password: 'bar'])

Name

Description

Return

Parameters

Requires Auth

befriend

Befriends the specified user

User

String username: the ID or screen name of the user to befriend

true

breakFriendship

Discontinues friendship with the specified user

User

String username: the ID or screen name of the user with whom to discontinue friendship

true

destroyStatus

Destroys the status specified by the required ID parameter. The authenticated user must be the author of the specified status.

void

Status status: the status to delete

true

destroyStatus

Destroys the given status. The authenticated user must be the author of the status post.

void

int statusId: the id of the status to delete

true

getDirectMessages

Returns direct messages sent to the authenticated user.

List<Message>

none

true

getRateLimitStatus

Get the remaining number of API requests available to the authenticated user before the API limit is reached for the current hour.

int, the remaining number

none

true

getRecentDirectMessages

Returns the last 20 direct messages sent to the authenticated user

List<Message>

none

true

getDirectMessages

Returns the direct messages sent to the authenticated user

List<Message>

Date since: narrows the resulting list of direct messages to just those sent after the specified date

true

getDirectMessages

Returns the direct messages sent to the authenticated user

List<Message>

long sinceId: the id of a direct message, narrows the resulting list of direct messages to just those sent after the specified message id

true

getFeatured

Returns the users currently featured on the site

List<User>

none

false

getFollowers

Returns the authenticated user's followers

List<User>

none

true

getFriends

Returns the (latest 100) authenticated user's friends

List<User>

none

true

getFriends

Returns the (latest 100) given user's friends

List<User>

String username: the ID or screen name of the user

false

getFriendsTimeline

Returns the 20 most recent statuses posted in the last 24 hours from the authenticated user and that user's friends

List<Status>

none

true

getFriendsTimeline

Returns the 20 most recent statuses posted in the last 24 hours from the user and that user's friends

List<Status>

String id: optional, specifies the ID or screen name of the user for whom to return the friends_timeline, Date since: optional, narrows the returned results to just those statuses created after the specified date

true

getPublicTimeline

Returns the 20 most recent statuses from non-protected users who have set a custom user icon

List<Status>

none

false

getReplies

Returns the 20 most recent replies (status updates prefixed with @username) to the authenticated user

List<Message>

none

true

getStatus

Get the current status of the authenticated user

Status

none

true

getStatus

Returns a single status

Status

int id: the numerical ID of the status

true

getStatus

Get the current status of the given user

Status

String username: the username

false

getUserTimeline

Returns the 20 most recent statuses posted in the last 24 hours from the authenticated user

List<Status>

none

true

getUserTimeline

Returns the most recent statuses posted in the last 24 hours from the specified user

List<Status>

String id: optional, specifies the ID or screen name of the user, Integer count: optional (defaults to 20), specifies the number of statuses to retrieve; may not be greater than 20 for performance purposes, Date since: optional, narrows the returned results to just those statuses created after the specified date

Authentication is needed to see the posts of a private user

sendMessage

Sends a new direct message to the specified user from the authenticated user

Message, the sent message

String recipient: the ID or screen name of the recipient user, String text the text of your direct message - keep it under 140 characters!

true

setStatus

Sets the authenticated user's status

Status, the posted status

String text: the text of your status update. Must not be more than 160 characters and should not be more than 140 characters to ensure optimal display

true

show

Get the user, specified by ID or screen name

User

String id: the ID or screen name of a user

true

API wrapper methods

Name

Description

Return type

Parameters

isLoggedIn

Check if there are cached creditials from a session cookie

boolean, true if there are cached creditials

none

findCredentials

Called by TwitterFilter to extract username/password from the session cookie

TwitterTagLib

The taglib's namespace is 'twitter', e.g. <twitter:directMessages>...</twitter:directMessages>. See src/templates/index.gsp for sample usage of all tags.

Most tags are iterative, i.e. they call TwitterService to get a List of Statuses, Users, or Messages and loop through them, invoking the tag's body on each instance. The variable name inside the tag body is 'it'.

All taglib code is wrapped in a try/catch since Twitter fails sporadically (the 'fail whale'). When this happens the taglib logs the error and exposes the exception as a request attribute 'twitterException' and renders no output.

Tags

Tag name

Description

Attributes

directMessages

Gets direct messages and loops through them

'since' (Date) and 'sinceId' (long), both optional, used to limit the message count

recentDirectMessages

Gets recent direct messages and loops through them

none

replies

Gets reply messages and loops through them

none

followers

Gets followers and loops through them

none

friends

Gets friends (people you follow) and loops through them

if the 'username' attribute (login name or numeric id) is present it finds that user's friends, otherwise it finds the logged-in user's

featured

Gets Twitter 'featured users' and loops through them

none

user

Gets a single user

'userId', username or numeric ID

status

Gets the current status for a user

If the 'username' attribute (login name) is present it finds that user's friends, otherwise if the 'userId' attribute (numeric id) is present it finds that user's friends, otherwise it finds the logged-in user's

friendsTimeline

Gets the 20 most recent statuses posted in the last 24 hours from the authenticated user and that user's friends

if the 'userId' attribute (login name or numeric id) is present it finds that user's statuses, otherwise it finds the logged-in user's; if the 'since' attribute (Date) is present it limits results to only those after that date

publicTimeline

Gets the 20 most recent statuses from non-protected users who have set a custom user icon

none

userTimeline

Gets the 20 most recent statuses posted in the last 24 hours from the authenticated user

If the 'userId' attribute (login name or numeric id) is present it finds that user's statuses, otherwise it finds the logged-in user's; if the 'since' attribute (Date) is present it limits results to only those after that date; if the 'count' attribute (int) is present it limits results to no more than that number

profileImage

Renders an <img> tag for a user's profile image

'user', the user; 'alt', String - optional - for the tag's 'alt' attribute; 'border', int - optional - for the tag's 'border' attribute (defaults to 0); all other attributes are rendered in the html tag