Ever since I saw the Bit.ly JavaScript API I’ve been wanting to build a simple script for tracking the number of people visiting a blog post from Twitter. This past weekend I built a little script for doing just that – and in a completely unobtrusive manner.

The script itself is completely standalone (no dependencies) and can be included in any page relatively painlessly. Additionally, since it’s just HTML, CSS, and JavaScript, it’s completely themeable and customizable to the style of your site. Before explaining how to use it, some demos:

Demos

Simple Style

Sample Code <a class="retweet" href="https://johnresig.com/">John Resig's Blog</a> Tweet Text: “John Resig’s Blog http://bit.ly/vqYAg” <a class="retweet" href="http://jquery.com/">jQuery JavaScript Library</a> Tweet Text: “jQuery JavaScript Library http://bit.ly/FGybD” <a class="retweet" href="http://google.com/" title="Google Search Engine">Google</a> Tweet Text: “Google Search Engine http://bit.ly/ScCbV” <a class="retweet self" href=""></a> Tweet Text: “John Resig – Easy Retweet Button http://bit.ly/1cliT”





Vertical Style

Sample Code <a class="retweet vert" href="https://johnresig.com/">John Resig's Blog</a> Tweet Text: “John Resig’s Blog http://bit.ly/vqYAg” <a class="retweet vert" href="http://jquery.com/">jQuery JavaScript Library</a> Tweet Text: “jQuery JavaScript Library http://bit.ly/FGybD” <a class="retweet vert" href="http://google.com/" title="Google Search Engine">Google</a> Tweet Text: “Google Search Engine http://bit.ly/ScCbV” <a class="retweet vert self" href=""></a> Tweet Text: “John Resig – Easy Retweet Button http://bit.ly/1cliT”

How to Use / Installation

Getting the Easy Retweet Button running on your site is painfully easy (ha!).

Step 1: Include the retweet.js file in the <head> of your web site.

<script src="https://johnresig.com/files/retweet.js"></script>

(Note: You should place and use a copy from your own site, in case mine ever goes down.)

(Note 2: You DO NOT need a bit.ly account in order to use this script. A working one is provided for you by default.)

Step 2: Add a class of ‘retweet’ to any anchor that you wish to turn into a Retweet button – or add a link with classes of ‘retweet’ and ‘self’ to add a retweet button for the current page.

Retweet link for the current page: (See example at the end of this blog post.)

<a class="retweet self"></a>

Retweet link for other page:

<a class="retweet" href="https://johnresig.com/">John Resig's Blog</a>

WordPress: If you’re using WordPress you could sculpt a custom button like so, placed in your single.php theme file (although, the above link types should be more than sufficient for most cases):

<a href="<?php the_permalink() ?>" class="retweet"><?php the_title(); ?></a>

The script has been tested in Internet Explorer 6-8, Opera 9-10, Safari 3.2-4, Chrome 2, and Firefox 3-3.5. Please write a comment if you encounter any problems.

Configuration and Themeing

There are a few options for the Retweet button that you can use. If you’re going to change them you can do so by changing the following properties after you’ve already loaded the retweet.js file. However, I highly recommend that you download a copy of the retweet.js file, make the changes in the file itself, and simply load that result instead.

RetweetJS.link_text (Default: “Retweet”)

You can change this to another value and change the text in all of the Retweet buttons. (Good for handling different languages.)

RetweetJS.count_text (Default: “clicks”)

Right now only “clicks” are supported but if you specify “none” it will show no count (and load much faster, as a result).

RetweetJS.prefix (Default: “”)

Setting to “RT @jeresig ” will add it to the front of the tweets.

RetweetJS.styling (Default: The full CSS used for styling the retweet button.)

You’ll probably want to either tweak the CSS from inside the file itself or completely overwrite it and include your own styling elsewhere. The markup for the button is surprisingly simple:

<a href="..." class="retweet"><strong>4 </strong><span>Retweet</span></a>

And if you have a vertical-style button the markup is:

<a href="..." class="retweet vert"><strong class="vert">4 </strong><span class="vert">Retweet</span></a>

RetweetJS.bitly_user

RetweetJS.bitly_key

These default to a dummy account (‘retweetjs’) that can be used indefinitely. However if you wish to keep track of your own links and add them to your own Bit.ly account then please add in your Bit.ly username and API key (which can be found on your Bit.ly account page). These values should be changed within the retweet.js file itself.

Alternatives

Two alternatives that I know about are the Tweetmeme Button and the Backtype Tweetcount.

Some of the major differences between this script and those are:

Completely Unobtrusive You can place the script in the <head> of your document instead of inline. The other scripts rely upon document.write() and write out iframes into your document.

You can place the script in the <head> of your document instead of inline. The other scripts rely upon document.write() and write out iframes into your document. Speed Retweet.js works completely asynchronously, loading data and updating the rendering as it comes in. This means that the buttons won’t block your page while they’re loading (unlike the other buttons).

Retweet.js works completely asynchronously, loading data and updating the rendering as it comes in. This means that the buttons won’t block your page while they’re loading (unlike the other buttons). Pure HTML/CSS The result is just pure HTML styled with CSS – you can customize it however you wish, no images are required.

The result is just pure HTML styled with CSS – you can customize it however you wish, no images are required. Number of clicks, not retweets. The number of retweets may be interesting to some but it’s a poor indicator of actual traffic. Instead, the number of clicks coming in is shown instead (a much more useful number).

The number of retweets may be interesting to some but it’s a poor indicator of actual traffic. Instead, the number of clicks coming in is shown instead (a much more useful number). You control the data All tracking works directly through Bit.ly, not a third party – this means that all the clicks and traffic can be stored straight in your bit.ly account, not some third parties.

All tracking works directly through Bit.ly, not a third party – this means that all the clicks and traffic can be stored straight in your bit.ly account, not some third parties. 100% Open Source This script is released under the MIT license and is completely open to modification and redistribution. The full source is available on Github.

If you have any questions regarding the script please feel free to post them her in the comments. If you have any tweaks for the script, please apply them against the source repository. Enjoy!