A jQuery plugin for working with the Twitter Search API to put twitter searches on websites. jQuery.twitter has a simple syntax that follows the Twitter Search API URL parameters.
In addition to supporting the default Twitter Search API URL parameters,
$.fn.twitter creates a <ul> of tweets for you, and puts it in the DOM. This plugin comes with a static $.twitter which $.fn.twitter uses under the hood for doing twitter searches.
We've got a handy demo up at http://bl.ocks.org/1813727
Download "Cowboy" Ben Alman's JavaScript Linkify - v0.3.
Download the production version or the development version of jQuery.twitter.
In the browser:
<script src="http://code.jquery.com/jquery.js"></script>
<script src="ba-linkify.min.js"></script>
<script src="jquery.twitter.min.js"></script>
<style type="text/css">
.twitter-posts li {margin-bottom: 10px; font-size: 12px; clear: both; list-style-type:none;}
.twitter-posts li img {float:left; margin:0px 10px 10px 0px;border:1px solid #c2c2c2; -moz-box-shadow: 0px 0px 4px #c2c2c2; -webkit-box-shadow: 0px 0px 4px #c2c2c2; box-shadow: 0px 0px 4px #c2c2c2;}
.twitter-posts li a {text-decoration:none; color: #009;}
</style>
<script>
$('myselector').twitter({from: 'boazsender', replies: false})
</script>
You can see a pretty thorough overview of this plugins usage from this Gist.
Passing in a string to the plugin simply performs a search with that string.
$('selector').twitter('search terms');
There are lots of options, so you could do something more like:
$('selector').twitter({
// From this person
from : 'BoazSender',
// Include @replies?
replies : false,
// All of these words
ands : 'jquery bocoup',
// Any of these words
ors : 'gangster javascript',
// None of these words
nots : 'dirty words',
// don't include user avatars in the list.
avatar : false
});
The jQuery Twitter Plugin provides two methods and a public default options object:
$.twitter(options, callback)
options: the string or object used to configure the search
callback: the function to run when the results come back from twitter. Three arguments are passed to this callback(tweets, query, exclusionsExp)
This method allows you to get twitter results and work with the JSON response. Fore example:
$.twitter({from: 'BoazSender', replies : false}, function(tweets){
console.log(tweets);
});
$.fn.twitter(options, callback)
options: the string or object used to configure the search
callback: the function to run when the results come back from twitter. One boolean is passed to this callback. True if tweets were injected, False if no tweets were returned
This method uses $.twitter() internally to go and get the tweets you ask for, and render them in a <ul> within each element in the jQuery collection you call it on. For example:
$('selector').twitter('search terms', function(tweets){
if(tweets){
console.log('Tweets have been added');
}else{
console.log('Zero tweets retruned, no tweets added to the page');
}
});
$.twitter.options
This is the publicly available object that
// Default all twitter lists to exclude @replies and dirty words
$.twitter.options.replies = false;
// Set a whole bunch of defaults at once
$.extend($.twitter.options, {
replies : false,
retweets : false,
limit : 20,
nots : 'dirty words'
});
You can pass the following default Twitter Search API Parameters to $.fn.twitter() as properties of the options object:
- q: Default query
- ands: All of these words
- phrase: This exact phrase
- ors: Any of these words
- nots: None of these word
- tag: This hashtag
- lang: Written in language
- from: From this person
- to: To this person
- ref: Referencing this person
- near: Near this place
- within: Within this distance
- units: Distance unit (miles or kilometers)
- since: Since this date
- until: Until this date
- tude: Attitude: '?' or ':)' or ':('
- filter: Containing**: 'links'
- include: Include retweet?**: 'retweets'
- rpp: Results per page
In addition to supporting the default Twitter Search API URL parameters, $.fn.twitter() also supports five of it's own options for filtering out mentions and retweets and for handling no results cases client side.
- limit: Number of tweets to get. Maps to and supersedes rpp (results per page).
- exclusions: Space delimited list of strings (eg: '_ s gr @b'). Use this to exclude tweets containing strings that are part of a word
- avatar: Include user avatars? true by default. (Boolean)
- notFoundText: Text to display if no results are found
- replies: Include replies? (Boolean)
- retweets: Include retweets (Boolean)
To get started contributing to jQuery.twitter.js, install grunt globally ($ npm install grunt -g ).
This project generally follows Idiomatic.js from Rick Waldron, take care to maintain the existing coding style. Add unit tests and written documentation for any new or changed functionality, and make sure all your code passes this project's grunt. This project's gruntfile was generated with $ grunt init:jquery.
Do not edit files in the "dist" directory as they are generated via grunt. You'll find source code in the "src" subdirectory. Work inside of the src directory, and use grunt to concat/min/test/lint the code before making a pull request. Running $ grunt watch from the root of this project will do this for you as you go.
- 2012/01/22 - v0.2.1 - Added callback support to .fn.twitter, upgrading to grunt v0.3.9 and QUnit v1.7.0pre
- 2012/01/22 - v0.2.0 - Moved to grunt based project organization and concat/min/lint/test, started passing lint.
- 2012/01/21 - v0.1.1 - Upgraded to jQuery 1.7.1, fixed classname bug, got rid of all globals.
- 2011/08/11 - v0.1.0 - Initial release.
Copyright (c) 2012 Boaz Sender
Licensed under the MIT, GPL licenses.
http://code.bocoup.com/license/
jQuery-Twitter depends on JavaScript Linkify - v0.3 (code) from "Cowboy" Ben Alman.
Some of jQuery-Twitter's regexps adapted from http://userscripts.org/scripts/review/7122
This project is built with "Cowboy" Ben Alman's Grunt.