jTweetsAnywhere

jQuery Twitter Widget with @Anywhere support

jTweetsAnywhere is a jQuery Twitter Widget that simplifies the integration of Twitter services into your site.
With just a few lines of Javascript you can

Download

Current Release: V1.0.1

$('#twts').jTweetsAnywhere({
    username: 'tbillenstein',
    count: 5
});

Display tweets from users' feeds and users' lists
Show results from a Twitter search
Integrate a customizable TweetBox
Let your visitors follow you directly from your site
Handle secure authentication with Twitter

Features

Displays tweets from one or more user's feeds
Displays tweets from a user's list
Displays the results of a Twitter search
Supports all Twitter search params
Supports Twitter's @Anywhere features
Optionally displays profile images in TweetFeeds
Automatically detects and marks up links in tweets
Automatically links #hashtags to Twitter search requests
Automatically links @username to Twitter profiles
Automatically shows Hovercards when hovering @username or profile images
Integrates a customizable TweetBox, so your visitors can update their status on the fly
Adds a Twitter "Follow Button" to your site
Adds a "Connect with Twitter" button to your site
Provides secure user authentication
Handles low level user login and signup procedures
Customize the style and layout of the widget with your own stylesheets
Overwrite the generated HTML markup by providing your own Decorators
Small code size for fast download
Does not interrupt the loading of your page

Usage

1. Download the plugin

The downloadable zip archive contains the Javascript source file in it's original and a fastloading minified version and a basic CSS file that serves as a sample for tweaking the UI.

Download

Current Release: V1.0.1

2. Include the Javascript and CSS resources in your page's `<head>` section

You will need the jQuery library. jQuery Version 1.4.2 (minified) is recommended. You can also hotlink to one of the hosted versions

<head>
    <script type="text/javascript" src="jquery-1.4.2.min.js"></script>
    <script type="text/javascript" src="jquery.jtweetsanywhere-1.0.1.min.js"></script>

    <link rel="stylesheet" type="text/css" href="jquery.jtweetsanywhere-1.0.1.css" />
</head>

Twitter's @Anywhere features (like Hovercards, Tweet Box, Follow Button, etc.) are optional. If you don't need them, just skip the next paragraphs and continue with the next section. Keep in mind that you can integrate any kind of tweet feed into your site without the need of @Anywhere.

If you want to use Twitter's @Anywhere features, you must include Twitter's anywhere.js inside your <head> section. In order to start using @Anywhere, you have to register your site (application) and obtain an APIKey (also called Consumer Key) from Twitter. When registering, be sure to select "Read & Write" for the Default Access type.

<script type="text/javascript" src="http://platform.twitter.com/anywhere.js?id=APIKey&v=1"></script>

Read this note for registration details and how to set up a local web server for testing purposes.

3. Add a placeholder for the widget to your page

<body>
    ...
    <div id="tweetsFeed">
    </div>
    ...
</body>

4. Add the Javascript that will populate the placeholder

$(document).ready(function(){
    $('#tweetsFeed').jTweetsAnywhere({
        username: 'tbillenstein',
        count: 5,
        showTweetBox: { label: '<span style="color: #D1C7BA">Spread the word ...</span>' }
    });
});

5. View the results

6. Find more Samples on the Demo page

The Demo page shows a lot more samples of what can be done with the widget and how it can be tweaked to display the results you expect.

Documentation

This section describes all configurable plugin options.

username

The user's name who's tweet feed or list feed is displayed. This param is also used when a Twitter "Follow Button" is displayed. Usually this param is a string, but can also be an array of strings. If an array is supplied (and the params 'list' and 'searchParams' are null), a combined feed of all users is displayed.
Default value: tbillenstein
Sample: 'tbillenstein' or ['twitterapi', 'ChromiumDev']
See Sample 2 and Sample 6 on the Demo page.

list

The name of a user's list where the tweet feed is generated from.
Default value: null
Sample: 'ajaxians'
See Sample 7 on the Demo page.

searchParams

A single search param string or an array of search params, to be used in a Twitter search call. All Twitter Search Params are supported.
Default value: null
Sample: 'q=twitter' or ['q=twitter', 'geocode=48.856667,2.350833,30km']
See Sample 1 on the Demo page.

count

The number of tweets shown in the tweet feed. If this param is 0, no feed is displayed.
Default value: 0

tweetProfileImagePresent

A flag (true/false) that specifies whether to display profile images in tweets. If the param is set to null (the default value), a profile image is displayed only if the feed represents a user's list or the result of a Twitter search.
Default value: null

showFollowButton

A flag (true/false) that specifies whether to display a Twitter "Follow Button".
Default value: false
Sample: See Sample 2 on the Demo page.

showConnectButton

A flag (true/false) that specifies whether to display a Twitter "Connect Button" or an object literal representing the configuration options for the "Connect Button". The configuration options and their default values are:
```
{
    size: "medium"                // String  - The size of the Connect Button.
                                  //           Valid values are: small, medium,
                                  //           large, xlarge
}
```
Default value: false
Sample: See Sample 3 and Sample 8 on the Demo page.

showLoginInfo

A flag (true/false) that specifies whether to display Login Infos.
Default value: false
Sample: See Sample 3 on the Demo page.

showTweetBox

A flag (true/false) that specifies whether to display a Twitter "Tweet Box" or an object literal representing the configuration options for the "Tweet Box". The configuration options and their default values are:

{
    counter: true,                // Boolean  - Display a counter in the Tweet Box
                                  //            for counting characters
    width: 515,                   // Number   - The width of the Tweet Box in px
    height: 65,                   // Number   - The height of the Tweet Box in px
    label: "What's happening",    // String   - The text above the Tweet Box
    defaultContent: <none>,       // String   - Pre-populated text in the Tweet Box.
                                  //            Useful for an @mention, a #hashtag,
                                  //            a link, etc.
    onTweet: <none>               // Function - Specify a listener for when a tweet
                                  //            is sent from the Tweet Box. The
                                  //            listener receives two arguments:
                                  //            a plaintext tweet and an HTML tweet
}

Default value: false
Sample: { counter: true, width: 380, height: 65 }
See Sample 4 on the Demo page.

mainDecorator

Defines the sequence of the widget's components.
Default value: defaultMainDecorator
A decorator is a function that is responsible for constructing a certain element of the widget. Most of the decorators return a HTML string. Exceptions are the mainDecorator, which defines the basic sequence of the widget's components, plus the linkDecorator, the usernameDecorator and the hashtagDecorator which return the string that is supplied as a function param, enriched with HTML tags. For details, see the implementations of the default decorators. Each default decorator can be overwritten by your own implementation. See Sample 5 on the Demo page.

tweetFeedDecorator

Returns the placeholder for the tweet feed (default is an unordered list).
Default value: defaultTweetFeedDecorator

tweetDecorator

Returns the tweet HTML. The default tweet is made of the optional user's profile image and the tweet body inside a list item element.
Default value: defaultTweetDecorator

tweetProfileImageDecorator

Returns the profile image HTML. The default profile image decorator simply adds a link to the user's Twitter profile.
Default value: defaultTweetProfileImageDecorator

tweetBodyDecorator

Returns the tweet body HTML. The default tweet body contains the tweet text and the tweet's creation date.
Default value: defaultTweetBodyDecorator

tweetTextDecorator

Returns the tweet text HTML. The default tweet text decorator marks links, @usernames, and #hashtags.
Default value: defaultTweetTextDecorator

tweetTimestampDecorator

Returns the tweet timestamp HTML. The default tweet timestamp decorator does a little bit of Twitter like formatting.
Default value: defaultTweetTimestampDecorator

connectButtonDecorator

Returns the default placeholder for the @Anywhere Connect Button.
Default value: defaultConnectButtonDecorator

loginInfoDecorator

Returns the default placeholder for the LoginInfo.
Default value: defaultLoginInfoDecorator

loginInfoContentDecorator

Returns the LoginInfo content HTML. The default markup of the LoginInfo content: the user's profile image, the user's screen_name and a "button" to sign out.
Default value: defaultLoginInfoContentDecorator

followButtonDecorator

Returns the default placeholder for the @Anywhere Follow Button.
Default value: defaultFollowButtonDecorator

tweetBoxDecorator

Returns the default placeholder for the @Anywhere Tweet Box.
Default value: defaultTweetBoxDecorator

linkDecorator

Adds the markup for links in tweets.
Default value: defaultLinkDecorator

usernameDecorator

Adds the markup for @usernames in tweets. if @Anywhere is present the task is left to them.
Default value: defaultUsernameDecorator

hashtagDecorator

Adds the markup for #hashtags in tweets.
Default value: defaultHashtagDecorator

loadingDecorator

Returns the loading indicator HTML. The default loading decorator simply says: loading ...
Default value: defaultLoadingDecorator

Changelog

V1.0.0

Initial release.

V1.0.1

Fixed an IE issue with parsing the tweet timestamp.

License

jTweetsAnywhere is licensed under the MIT license.

Support

In case of any question, suggestion or problem you have using jTweetsAnywhere, please don't hesitate to contact me.
There are several ways to get in touch.