# Tweet!

## put twitter on your website with tweet!, an unobtrusive javascript plugin for jquery.

Check out the script in action at seaofclouds.com, and see the following demos.

### Examples

#1 - Displaying three tweets from the seaofclouds twitter feed:

          jQuery(function($){
            $(".tweet").tweet({
              join_text: "auto",
              username: "seaofclouds",
              avatar_size: 48,
              count: 3,
              auto_join_text_default: "we said,",
              auto_join_text_ed: "we",
              auto_join_text_ing: "we were",
              auto_join_text_reply: "we replied",
              auto_join_text_url: "we were checking out",
              loading_text: "loading tweets..."
            });
          });

#2 - Displaying up to four tweets with the query "tweet.seaofclouds.com":

          jQuery(function($){
            $("#query").tweet({
              avatar_size: 32,
              count: 4,
              query: "tweet.seaofclouds.com",
              loading_text: "searching twitter..."
            });
          });

#3 - Displaying up to three links with the search query "from:seaofclouds http":

          jQuery(function($){
            $("#userandquery").tweet({
              count: 3,
              query: "from:seaofclouds http",
              loading_text: "searching twitter..."
            });
          });

#4 - Displaying four tweets from the two users "seaofclouds" and "laughingsquid", refreshing every 60 seconds:

(Note that it's more reliable to display multiple users' tweets by using a list - see below)

          jQuery(function($){
            $("#fromtwo").tweet({
              avatar_size: 32,
              count: 4,
              username: ["seaofclouds", "laughingsquid"],
              loading_text: "searching twitter...",
              refresh_interval: 60
            });
          });

#5 - Displaying tweets from users on the 'team' list of 'twitter':

          jQuery(function($){
            $("#list").tweet({
              avatar_size: 32,
              count: 4,
              username: "twitter",
              list: "team",
              loading_text: "loading list..."
            });
          });

#6 - Displaying the user sanityinc's favorite tweets, and using a handler for tweet's "loaded" event to make links open in a new window:

          jQuery(function($){
            $("#favorites").tweet({
              avatar_size: 32,
              count: 3,
              username: "sanityinc",
              favorites: true,
              loading_text: "loading list..."
            }).bind("loaded",function(){$(this).find("a").attr("target","_blank");});
          });

#7 - Fetch 20 tweets, but filter out @replies, and display only 3:

          jQuery(function($){
            $("#filter").tweet({
              avatar_size: 32,
              count: 3,
              fetch: 20,
              filter: function(t){ return ! /^@\w+/.test(t.tweet_raw_text); },
              username: "sanityinc"
            });
          });

#8 - Customize the layout to eliminate the date stamps and avatars, add an action (aka "web intent") link, and make it open in a popup window:

          jQuery(function($){
            $("#custom").tweet({
              avatar_size: 32,
              count: 4,
              username: "seaofclouds",
              template: "{text} » {retweet_action}"
            });
          }).bind("loaded", function(){
            $(this).find("a.tweet_action").click(function(ev) {
              window.open(this.href, "Retweet",
                          'menubar=0,resizable=0,width=550,height=420,top=200,left=400');
              ev.preventDefault();
            });
          });

#9 - Adding a message when no tweets matching 'somerandomstring' are found:

          jQuery(function($){
            $("#empty").tweet({
              avatar_size: 32,
              count: 4,
              query: rnd,
              loading_text: "searching twitter..."
            }).bind("empty", function() { $(this).append("No matching tweets found"); });
          });

#10 - use button to page forwards and backwards:

          jQuery(function($){
            var options = {
              username: "seaofclouds",
              page: 1,
              avatar_size: 32,
              count: 4,
              loading_text: "loading ..."
            };

            var widget = $("#paging .widget"),
              next = $("#paging .next"),
              prev = $("#paging .prev");

            var enable = function(el, yes) {
              yes ? $(el).removeAttr('disabled') :
                    $(el).attr('disabled', true);
            };

            var stepClick = function(incr) {
              return function() {
                options.page = options.page + incr;
                enable(this, false);
                widget.tweet(options);
              };
            };

            next.bind("checkstate", function() {
              enable(this, widget.find("li").length == options.count)
            }).click(stepClick(1));

            prev.bind("checkstate", function() {
              enable(this, options.page > 1)
            }).click(stepClick(-1));

            widget.tweet(options).bind("loaded", function() { next.add(prev).trigger("checkstate"); });
          });

#11 - display one tweet at a time like a ticker:

          jQuery(function($){
            $("#ticker").tweet({
              username: "seaofclouds",
              page: 1,
              avatar_size: 32,
              count: 20,
              loading_text: "loading ..."
            }).bind("loaded", function() {
              var ul = $(this).find(".tweet_list");
              var ticker = function() {
                setTimeout(function() {
                  ul.find('li:first').animate( {marginTop: '-4em'}, 500, function() {
                    $(this).detach().appendTo(ul).removeAttr('style');
                  });
                  ticker();
                }, 5000);
              };
              ticker();
            });
          });

### Features

- small size and fast download time
- will not slow down or pause your page while tweets are loading
- display up to 100 tweets, as permitted by the twitter search api
- display tweets from a twitter search, or from your own feed
- optional verb tense matching, for human readable tweets
- optionally display your avatar
- optionally display tweets from multiple accounts!
- display tweets from a list, or display a user's favorites
- optional reloading after a specified delay
- automatic linking of @replies to users’ twitter page
- automatic linking of URLs
- uses Twitter's Search API, so you can display any tweets you like
- Display up to 100 tweets that have been posted within 7 days (limit set by Twitter's Search API)
- automatic linking of #hashtags, to a twitter search of all your tags
- converts <3 to a css styleable ♥ (we ♥ hearts)
- customize the layout for tweets within the widget
- apply custom filters, e.g. to remove @replies
- define a custom sort order for tweets
- customize the style with your own stylesheet or with other jquery plugins
- compatible with most jquery versions, from 1.2.6 to the latest 1.7
- supports RequireJS and other AMD-compatible javascript loaders

NOTE: Some users have reported that they do not show up in Twitter's search results.

### Download

### Usage

1. Get JQuery. In these examples, we use Google's AJAX Libraries API.

2. include jQuery and jquery.tweet.js files in your template's <head>.

`<script language="javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js" type="text/javascript"></script>
<script language="javascript" src="/tweet/jquery.tweet.js" type="text/javascript"></script>`

3. Also in <head>, Initialize tweet! on page load with your Username and other options

`<script type='text/javascript'>
jQuery(function($){
$(".tweet").tweet({
username: "seaofclouds",
join_text: "auto",
avatar_size: 32,
count: 3,
auto_join_text_default: "we said,",
auto_join_text_ed: "we",
auto_join_text_ing: "we were",
auto_join_text_reply: "we replied to",
auto_join_text_url: "we were checking out",
loading_text: "loading tweets..."
});
});
</script>`

4. In <body>, include a placeholder for your tweets. They'll get loaded in via JSON. How fancy!

`<div class="tweet"></div>`

5. Style with our stylesheet in <head>, or modify as you like!

`<link href="jquery.tweet.css" media="all" rel="stylesheet" type="text/css"/>`

### Contribute

Bring your code slinging skills to Github and help us develop new features for tweet!

`git clone git://github.com/seaofclouds/tweet.git`

Report bugs and request features in Github Issues

### Licensed under the MIT

`http://www.opensource.org/licenses/mit-license.php`

something nifty from seaofclouds™ | contribute