Twitter Plugin
-
Tags:
- Latest: 0.2
- Last Updated: 07 January 2009
- Grails version: 1.1.1
Dependency:
compile ":twitter:0.2"
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 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.
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'])
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.grails install-plugin twitter
Features
- provides a Service that wraps the JTwitter API
- provides a TagLib to simplify displaying users, messages, statuses, etc.
- implements a basic authentication system to remember Twitter username/password between requests
- sample controller and GSPs provided to demonstrate usage
Usage
See the sample code in src/templates for examples of usage:- copy TwitterController.groovy to your grails-app/controllers folder
- copy twitter.gsp to grails-app/views/layouts
- create the folder grails-app/views/twitter
- copy the remaining GSPs to grails-app/views/twitter
- load http://localhost:8080/yourapp/twitter in your browser, authenticate with your Twitter credentials, and you'll see a summary page with your Friends, Followers, tweets, etc.
Data classes
Message
| Property/getter name | Type |
|---|---|
| createdAt | Date |
| id | int |
| sender | User |
| recipient | User |
| text | String |
| isPublic() | boolean |
| favorited | boolean |
| inReplyToStatusId | long |
| inReplyToScreenName | String |
| inReplyToUserId | long |
| truncated | boolean |
Status
| Property/getter name | Type |
|---|---|
| createdAt | Date |
| id | long |
| text | String |
| user | User |
| inReplyToStatusId | long |
| inReplyToScreenName | String |
| inReplyToUserId | long |
| truncated | boolean |
User
| Property/getter name | Type |
|---|---|
| description | String |
| id | int |
| location | String |
| name (the display name, e.g. "Daniel Winterstein") | String |
| profileImageUrl | URI |
| protectedUser | boolean |
| screenName (the login name, e.g. "winterstein") | String |
| status | Status |
| website | URI |
TwitterService
TwitterService wraps the JTwitter API and also provides authentication methods.API wrapper methods
All API methods where 'Requires Auth' is true either need cached credentials (from a previous login() call) or can take a 'username' and 'password' in an optional 'authParams' parameter.For example, getUserTimeline() requires authentication; the method signature isList<Status> getUserTimeline(Map authParams = [:]) throws TwitterException| 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 | void | cookies, array of cookies, possibly null |
| login | Called by login controller action | boolean, true if successful | String username: Twitter login name, String password: Twitter password, request: http request, response: http response |
| logout | Delete cookie and reset cached credentials | void | request: http request, response: http response |
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 |
| publicTimeline | Convert urls to clickable links and @username to clickable Twitter homepage links | 'text', String - the text to mark up; 'links', boolean - to specify whether to mark up links (defaults to true); 'usernames', boolean - to specify whether to mark up @username (defaults to true) |
| userLink | Renders a link to a user's twitter.com page | 'name', String - the user's login name; 'text', String - optional - the link text (defaults to the user's login name); all other attributes are passed through to the tag |
| tweetLink | Renders a link to a tweet (status) twitter.com page | 'name', String - the user's login name; 'id', long - the status id; all other attributes are passed through to the tag |
| tweetLink | Renders a link for a URL with a target of '_blank' (new window). If the 'url' attribute is null, nothing is rendered | 'url', URL - the url of the link; 'text', String- the link text to display (defaults to the URL); all other attributes are passed through to the tag |
| rateLimitStatus | Gets the remaining number of API requests available to the authenticating user before the API limit is reached for the current hour | none |
Author
Burt Beckwith burt@burtbeckwith.comPlease report any issues to the Grails User mailing list and/or write up an issue in JIRA at http://jira.codehaus.org/browse/GRAILSPLUGINS under the Grails-Twitter component.History
- January 8, 2009
- released version 0.2
- January 5, 2009
- released initial version 0.1