jTweetsAnywhere V1.2.0 is released.

In this release you will find a lot new features and also big changes under the hood. Let me summarize the main building blocks of the new release.

Support for auto-refreshing tweet feeds and the ability to access earlier tweets by several paging variants

Two of the most requested features from the jTweetsAnywhere users were the support for auto-refreshing tweet feeds – to be able to build realtime or live tickers and the ability to access earlier tweets by several paging variants. Both requests are fullfilled and can easily be adjusted by the configuration options.

Let’s look at an example. This script is used in the demo Auto-refreshing Realtime Ticker and More Tweets to populate the placeholder.

$('#jTweetsAnywhereSample').jTweetsAnywhere({
    searchParams: ['q=html5'],
    count: 10,
    showTweetFeed: {
        autorefresh: {
            mode: 'trigger-insert',
            interval: 30
        },
        paging: {
            mode: 'more'
        };
        showTimestamp: {
            refreshInterval: 15
        }
    };
});

The parameters searchParams and count should be well-known: They select what tweets and how many of them should be presented. More interesting is what comes next.

The autorefresh configuration option specifies that jTweetsAnywhere should look for new tweets every 30 seconds. If there are new tweets, a button (trigger control) will be presented at the top of the tweet feed that shows the number of new tweets available (similar to Twitter). This behaviour is configured by the mode: 'trigger-insert' parameter. As an alternative you can set the mode to 'auto-insert' if you want the new tweets to be inserted on top of the tweet feed automatically without user interaction.

The paging configuration option specifies that earlier tweets should be accessible by a click on the ‘more’ button at the end of the tweet feed. Each click adds 10 earlier tweets to the feed. Other paging modes are 'prev-next' which offers flipping through the pages of tweets back and forth (see a demo here) and 'endless-scroll' where earlier tweets will be loaded automatically when reaching the bottom of the feed (see a demo here).

Finally the showTimestamp configuration option makes sure that all visible tweet timestamps in the widget are updated at an interval of 15 seconds. This is desireable for tweet timestamps like ‘17 seconds ago’ which would’t be true after a while.

This is important:

Please always keep in mind, that the use of the Twitter API is rate limited. Non-authenticated users are rated IP-based and you have only 150 calls per hour available. Every retrieval of tweets counts and so does for example hovering over a profile image to show the hovercard. jTweetsAnywhere will always check the remaining count of free API calls before actually calling Twitter to avoid black listing your visitor’s IP.

However – choose your settings wisely to keep your visitors happy. A refresh interval of 30 seconds on a tweet feed that is updated averaged once per hour does not make sense and is a total waste of remaining API calls!

The benefits of caching tweets

Caching is always good, isn’t it? Well … yes … of course.

Berfore Version 1.2.0 jTweetsAnywhere requested the number of tweets from the Twitter API that you configured through the count parameter. Some of you then realized that less than count tweets were delivered by Twitter. The reasons for that behaviour might have been deleted tweets that were just flagged ‘deleted’ and not yet eliminated from the databases (but filtered out from the response) or native retweets that were skipped by Twitter because the request parameter 'include_rts=true' was missing.

From now on jTweetsAnywhere will always deliver the requested amount of tweets, given that there exist enough tweets. For this reason jTweetsAnywhere will always request the maximum number of tweets for the given type of Twitter API call. For a user’s feed or a user’s list feed the maximum is 20 tweets while for a search request you can get up to 100 tweets per API call from Twitter. The loaded tweets will then be stored in the cache. If more (earlier) tweets are requested by one of the paging variants jTweetsAnywhere will try to fulfill that demand from the cache first. If there aren’t enough tweets available, additional tweets are loaded and cached. Thereby the amount of API calls is minimized and Twitter’s rate limit exhaustion will be defered. This is especially important when using the auto-refresh feature.

Before executing any Twitter API call the rate limit is checked and only if there still are possible API calls remaining the request will be sent. This ensures that no calls will be executed if the rate limit is already exhausted and saves your visitors from getting black-listed.

Another benefit is the ability for the user to filter out certain tweets by supplying a customized tweet filter. Each tweet loaded from Twitter will pass the filter and is stored in the cache only if the filter allows it.

By the way, native retweets are supported in V1.2.0 and their presence in the displayed tweet feed can be configured by the includeRetweets option.

New decorators, formatters, visualizers and event handlers

Since the initial release jTweetsAnywhere used the concept of decorators to produce each element’s html markup and supplied a default decorator for each of these elements. Version 1.2.0 adds a few more new decorators to the already existing ones reflecting the new elements, like the tweetUsernameDecorator, tweetGeoLocationDecorator, tweetInReplyToDecorator, tweetRetweeterDecorator, tweetFeedControlsDecorator, tweetFeedControlsMoreBtnDecorator, tweetFeedControlsPrevBtnDecorator, tweetFeedControlsNextBtnDecorator, tweetFeedAutorefreshTriggerDecorator, tweetFeedAutorefreshTriggerContentDecorator and the noDataDecorator.

As a user you had the option to overwrite the default decorators to adjust the resulting markup by your needs. V1.2.0 continues this concept by supplying default formatters, visualizers and event handlers for the various needs.

The formatters, tweetTimestampFormatter and tweetTimestampTooltipFormatter, are currently used only for tweet timestamp formatting purposes and makes the provision of other timestamp formats much easier than the previous way of overwriting the tweetTimestampDecorator.

Visualizers are functions that are responsible for adding one or more elements to the DOM and thereby making them visible to the user. Furthermore a visualizer might also be responsible to do the opposite effect: To remove one or more elements from the DOM. The tweetVisualizer for example gets called each time a tweet element should be appended or prepended to the tweet feed element. For details, see the implementation of the defaultTweetVisualizer. The other visualizers that currently exist are the loadingIndicatorVisualizer and the autorefreshTriggerVisualizer.

An event handler is a function that gets called whenever the event you are interested in, occurs. The onDataRequest event handler will be called immediatly before calling Twitter to retrieve new data and gives you the opportunity to deny the call by returning false from the event handler. This feature might be used in conjunction with the paging feature, especially when using the ‘endless-scroll’ paging mode, to avoid the exhaustion of remaining Twitter API calls, before the rate limit is reached. The stats parameter contains statistical infos and counters that you can examine to base your decision whether to return true or false. The onRateLimitData event handler is called each time jTweetsAnywhere retrieved the rate limit data from Twitter. The actual rate limit data is contained in the stats object.

This is important:

Due to the fact that native retweets are supported now, if you have supplied your own decorators, you might have a look at jTweetsAnywhere’s default decorators to check if your decorators need to be updated to handle these retweets correctly.

Some more configuration options

A view more configuration options have been added to the tweet feed configuration, regarding a tweet’s attributes. These are: showTweetFeed.showTimestamp, showTweetFeed.showProfileImages, showTweetFeed.showUserScreenNames, showTweetFeed.showUserFullNames, showTweetFeed.showGeoLocation and showTweetFeed.showInReplyTo.

Changelog

Here is the complete list of new features and changes for this release.

• Feature: Support for auto-refreshing tweet feeds to build realtime/live tickers
• Feature: Support for several paging modes to show more tweets (mode: ‘more’ | ‘prev-next’ | ‘endless-scroll’)
• Feature: Native retweets support
• Feature: Tweet filter support
• Feature: Element visualizer support
• Feature: Event handler support
• Feature: Value formatter support
• Feature: Tweets cache support to minimize rate-limited Twitter API calls
• Feature: Taking care of Twitter’s rate limit when loading data from Twitter
• Feature: Added configuration option showTweetFeed.showTimestamp
  (show/hide/auto-refresh a tweet’s timestamp’)
• Feature: Added configuration option showTweetFeed.showProfileImages
  (show/hide a user’s profile image’)
• Feature: Added configuration option showTweetFeed.showUserScreenNames
  (show/hide a user’s screen name’)
• Feature: Added configuration option showTweetFeed.showUserFullNames
  (show/hide a user’s full name
• Feature: Added configuration option showTweetFeed.showGeoLocation
  (show/hide a tweet’s geolocation attribute)
• Feature: Added configuration option showTweetFeed.showInReplyTo
  (show/hide a tweet’s in-reply-to attribute)
• Feature: Added configuration option tweetUsernameDecorator
• Feature: Added configuration option tweetGeoLocationDecorator
• Feature: Added configuration option tweetInReplyToDecorator
• Feature: Added configuration option tweetRetweeterDecorator
• Feature: Added configuration option tweetFeedControlsDecorator
• Feature: Added configuration option tweetFeedControlsMoreBtnDecorator
• Feature: Added configuration option tweetFeedControlsPrevBtnDecorator
• Feature: Added configuration option tweetFeedControlsNextBtnDecorator
• Feature: Added configuration option tweetFeedAutorefreshTriggerDecorator
• Feature: Added configuration option tweetFeedAutorefreshTriggerContentDecorator
• Feature: Added configuration option noDataDecorator
• Feature: Added configuration option tweetTimestampFormatter
• Feature: Added configuration option tweetTimestampTooltipFormatter
• Feature: Added configuration option tweetVisualizer
• Feature: Added configuration option loadingIndicatorVisualizer
• Feature: Added configuration option autorefreshTriggerVisualizer
• Feature: Added configuration option onDataRequestHandler
• Feature: Added configuration option onRateLimitDataHandler
• Cleanup: tweetProfileImagePresent is deprecated now. Use showTweetFeed.showProfileImages instead

For additional information take a look at the documentation. Each new feature described there is tagged with
“Since: 1.2.0″.

Finally …

I hope you like the new features and will find them useful. As always: Any feedback would be appreciated, so give it a try and let me know. Thanks.