About¶

The plugin allows to build a Twitter client in Servoy.
It gives access to most of the Twitter API functions using simple JavaScript calls and return usable JavaScript objects.

Most Twitter API calls require a user to be authenticated, and having given an authorization for the plugin to act on his behalf... this is done using a specific authentication/authorization mechanism.

Application Registering¶

But first the application itself must be registered with Twitter.
Right now the plugin itself is registered as a "ServoyStuffPlugin" application and you can use this registered application for your tests.
NB: I recommend however that you do register your own application if you are to use this plugin in production.

With a valid Twitter account, you can do so by browsing to https://dev.twitter.com/apps/new and filling the form, giving your application a unique name, a description, a home page URL (which can be your company's home page), a type (set this to client), - no callback url is need since you have set the type to 'client' -, the kind of access you need (read & write), and an optional icon.

Once registered, you will be given a OAuth Consumer Key token and a Consumer Secret token, these are the values you will need to use on your solution onOpen method to setup the plugin, using setApplication(key, secret).
This is done only once per session.

User Authentication¶

Once your application is registered, you will need to authenticate the users. This is done using a special protocol named OAuth

The first time (and the first time only!) a user is accessing the plugin through your application, you will have to get his authorization tokens, a set of two special Strings (key and secret) which will validate that this user has authorized your application to act on his behalf. You do this using the plugin's initAccount(accountName) method which will do a few things: it will open a modal dialog asking for a token and it will also open the user's browser, navigating to a Twitter page, asking him to login (if he has saved cookies on his computer, he will be recognized already).
Upon login Twitter will return a token number to be used by the application, the user will then have to copy this token number into the dialog and click OK to complete the process.

This is all done by the initAccount(accountName) method.
Once the user have copied the Twitter authorization token into the modal dialog and clicked OK, this method will return an array of 2 Strings, a key token and a secret token respectively.
These 2 Strings are to be saved along with the account name of the user because they will be needed once for each session of this user in your application, so make sure you save these 2 strings along with the user's information in your database.

Now that you have the user's tokens, you will be able to authenticate on Twitter on his behalf, using the connect(accountName, tokens) method (where tokens is a String[]), this is done once per client's session as the plugin will keep this information in memory for the time of the client's session.

Note that a user can revoke the authorization he has given to your application at any time, by going to his Settings/Applications page on Twitter: https://twitter.com/settings/applications
This is one of the reasons why you should always use try/catch blocks around all the plugin method calls since they will spill an Exception in case the user is no longer authorizing your application.
If that is the case, you will have to go through the first time authorization process again, to retrieve new authorization tokens...

Exceptions¶

Beware that all the methods in this object might cause an Exception to occur in your client, for various reasons (network, authentication, invalid call, etc...)

So make sure to encapsulate ALL your calls to plugins.twitter.xxxx() inside a try/catch block to avoid your clients getting an annoying Java Exception message dialog (the exception will always be of type TwitterPluginException).

Objects¶

The plugin is returning a few objects from various methods, these are:

• Tweet - a tweet message
• Message - a direct message
• Profile - a user's profile information
• RateLimit - API rate limit associated with a user

Properties and methods¶

autoTruncate¶

Get/Set the autoTruncate option which will truncate any messages to the 140 characters Twitter limit - default is false

connect()¶

boolean connect(String account, String[] tokens)

This method will attempt to create a Twitter client for a the user account, given his authorization tokens - must be the first call before any access to other methods.

destroyMessage()¶

void destroyMessage(String account, String id)

Deletes a Message sent by that account given its id

destroyStatus()¶

void destroyStatus(String account, String id)

Deletes a Tweet sent by that account given its id

follow()¶

String follow(String account, String user)

Add the user to the list of users followed by the related account, returns the userName if successful, null if not (and spill an Exception in that case)

getAccountTimeLine()¶

[[Tweet]][] getAccountTimeLine(String account, [boolean withRetweets], [Integer maxCount])

Get a list of Tweets (the timeline) for a connected account, with optional re-Tweets, and a max number (default=20, max=200)

getCurrentStatus()¶

[[Tweet]] getCurrentStatus(String account, [String user])

Returns the current status (last Tweet) for the account connect or for a specified user

getDirectMessages()¶

[[Message]][] getDirectMessages(String account, [Integer maxCount])

Get the direct messages sent to the connected account, optionally limited to a maximum number (default=20, max=200)

getFavorites()¶

[[Tweet]][] getFavorites(String account, [String user], [Integer maxCount])

Get a list of Tweets marked as favorites by a connected account, or by a specified user, optionally limited to a maximum number (default=20, max=200)

getProfile()¶

[[Profile]] getProfile(String account, [String user])

Returns the Profile of the connected account, or of a specified user

getRateLimit()¶

[[RateLimit]] getRateLimit(String account)

Returns a RateLimit object for the connected account

getReplies()¶

[[Tweet]][] getReplies(String account, [Integer maxCount])

Returns an array of Tweets being replied (or mentions using the @ notation) to the connected account, optionally limited to a maximum number (default=20, max=200)

getRetweeters()¶

String[] getRetweeters(account, Tweet tweet|String tweetId)

Returns an array of user names of people having re-tweeted the related tweet (if you provide an id instead of a Tweet object, be aware that this will perform an extra call to the Twitter API to retrieve the Tweet object)

getRetweetsByMe()¶

[[Tweet]][] getRetweetsByMe(String account, [Integer maxCount])

Returns an array of Tweets being re-tweets the connected account have sent, optionally limited to a maximum number (default=20, max=200)

getRetweetsOfMe()¶

[[Tweet]][] getRetweetsOfMe(String account, [Integer maxCount])

Return an array of Tweets by the connected account that other users have re-Tweeted, optionally limited to a maximum number (default=20, max=200)

getTweet()¶

[[Tweet]] getTweet([String account], String tweetId)

Returns a Tweet object for the id provided (using the connected account, or anonymously if not provided)

getUserTimeLine()¶

Tweet[] getUserTimeLine([String user], [boolean withRetweets], [Integer maxCount])

Get a list of Tweets the timeline for a user (or the public timeline if user is null), with optional re-Tweets, optionally limited to a maximum number (default=20, max=200)

getVersion()¶

String getVersion()

Returns the version of the plugin

initAccount()¶

String[] initAccount(String account, [String prompt])

If a user account doesn't have his authorization tokens already, attempts to retrieve them (using a browser session and a JDialog)
NB: Be aware that this is the only method which is NOT web compatible!

isFollower()¶

boolean isFollower(String account, String user)

Returns true if the specified user is a follower of the connected account

isFollowing()¶

boolean isFollowing(String account, String user)

Returns true if the connected account is following the specified user

reply()¶

[[Tweet]] reply(account, message, [[Tweet]] tweet|String tweetId, [String user])

Replies to a Tweet (provided as Tweet object or tweet id and optional user) on behalf of the connected account, using the provided message, will return the new Tweet created if successful

retweet()¶

[[Tweet]] retweet(account, [[Tweet]] tweet|String tweetId)

Retweets the related Tweet (if you provide an id instead of a Tweet object, be aware that this will perform an extra call to the Twitter API to retrieve the Tweet object)

search()¶

[[Tweet]][] search(String account, String searchCriteria, [String lang], [Integer maxCount])

Performs a search (on behalf of the connected account or anonymously if no account is provided), using the searchCriteria, optionally forcing the language to be used (lang is ISO 639-1 code - [[http://en.wikipedia.org/wiki/ISO_639-1]]), and optionally limited to a maximum number (default=20, max=200)

Additional criteria that you can use to filter your searches:

• "from:servoystuff" - tweets from user servoystuff
• "to:servoystuff" - tweets start with Patrick Talbot
• "source:ServoyStuffPlugin" - originating from the application ServoyStuffPlugin - your query must also must contain at least one keyword parameter.
• "filter:links" - tweets contain a link
• "apples OR pears" - or search ("apples pears" would give you apples and pears).

sendDirectMessage()¶

[[Message]] sendDirectMessage(String account, String user, String message)

Sends a direct message to the user provided on behalf of the connected account, returns the new Message upon success

sendTweet()¶

[[Tweet]] sendTweet(String account, String message)

Sends a new tweet message on behalf of a connected user, returns the related Tweet object created upon success

setApplication()¶

void setApplication(String applicationKey, String applicationSecret)

Allows you to set your Twitter application credentials (key, secret) to use for the Servoy session

setFavorite()¶

void setFavorite(String account, [[Tweet]] tweet|String tweetId, boolean isFavorite)

Sets the favorite flag of a Tweet for that account, from a given Tweet or Tweet id

stopFollowing()¶

String stopFollowing(String account, String user)

Removes the user from the list of users followed by the connected account