Topsy Retweet Button for Web Sites

The Topsy Retweet Button allows your readers to retweet any page on your site, and shows a count of how many times the page has been retweeted. The button can be embedded on any page by adding the JavaScript code shown below.

Already using the Topsy Retweet Button? The the old-style button will still work. But you can speed up your page loads by switching to the new version of the Topsy Retweet Button. See the instructions under Notes for Previous Users.

Quick Two-Step Install

Step One: Include the Topsy JavaScript Library

Create a tag to include Topsy’s JavaScript. This must go your page’s <head> section. (Previous versions allowed you to place it anywhere; this is no longer possible.) Use this code:

Step Two: Set Up the Buttons Themselves

Every place you want to put a Topsy button, make a <div> with the class topsy_widget_data. Inside it, put an HTML comment containing a JSON structure that supplies information for each button, like this example:

You can see an example of how this button will look to the right of this paragraph.

The JSON variables you can use are:

  • url: (required) The URL of the page the button refers to. If you have a listing page, this means you can have a list of links to your pages, and buttons alongside them that refer to the linked pages, not the listing page.
  • title: (optional) The title of the page the button refers to. Will be used as retweet text, if supplied.
  • shorturl: (optional) If you have a shortened URL that points to your page, you can enter it here.

You can put the code all on one line, if you want. The indentations in the code above are just to show the URL and title more clearly. The following will work just the same (it’s just harder to read!):

Note: If you need to include two dashes in a row inside your title, you must put a backslash between them. You can also use a backslash if you want to include a double-quote mark. For example, to produce the title Topsy — A search engine powered by “tweets”, you’d use the code:

Customizing Your Buttons

The two-step install above will get buttons on your page. But that’s just the start; you can make them look different so they fit with your site.

Make the Buttons Big

You can produce a big button (like the one to the right) by adding "style": "big" to any button div. For example:

Change the Button Colors

Topsy offers 8 different color themes. You can choose your theme by adding "theme": "any-theme-name" to the inside of your topsy_widget_data div. There is a list of all theme names, plus examples of how they look. If you don’t pick one, the button will default to being blue.

Add Your Own CSS Styles

You can add inline CSS on your topsy_widget_data divs, and it will not interfere with the buttons. Look at the next code sample for an example of this.

Change the Retweet Username

When someone visits your site and clicks on one of your retweet buttons, who should their tweet give credit to? You want to set your own Twitter username to be used for retweets. You can use the “nick” (short for nickname) setting for that.

The code below shows custom CSS, and a custom retweet username, as well as the “jade” color theme. You can see an example of the button it makes at the top right corner of this paragraph.

Make Your Buttons Load More Quickly

If you want the buttons to show up as quickly as possible, you can use the “preload” feature. To turn this on, use a <script> tag and wrap the curly braces in a “topsyWidgetPreload” function call, like this:

This code is just like the previous one, except that it will try to load a clickable button and a blank count even before contacting Topsy’s servers to get the correct retweet count. This means the retweet button will be usable instantly, even if Topsy’s servers are unreachable.

Note that the topsyWidgetPreload() function must be used in your page’s actual HTML. You cannot use this kind of call in AJAX code or other dynamic page-loading methods.

Use the “Streaming” Feature

Topsy’s new Streaming buttons can automatically update their tweet counts as more people retweet your links. Each time the tweet count increases, you’ll see a brief flash of light around the number in your button as it changes to the new total.

To turn on streaming, just set the topsy_streaming variable to “on”, as described in the List of Global Settings, below.

Note: Streaming only works on links that are under 72 hours old. If you have multiple buttons on one page, only the ones that point to pages that are less than 72 hours old will continue to update.

Make Your Settings Global

If you have more than 1 or 2 buttons on a single page, you might want to enter your settings in just 1 place. You can put them in a script tag with the ID topsy_global_settings. Like the topsy.js script tag, this must go in your page’s <head> section. You can use this tag to set as many global options as you want, like this example:

Important: The settings in the global tag must have topsy_ at the beginning of them. This is to avoid conflicting with any other JavaScripts you might have on your page.

You cannot put “url”, “shorturl”, or “title” settings into the topsy_global_settings tag, because those are things that only apply to a single button.

If you have a setting in a button that conflicts with one on the global settings tag, the button setting will override the global setting just for that one tag. this allows you to make one button be a different color, or otherwise “special” or different from the others.

List of Global Settings

  • topsy_theme: Set this to any one of the following themes to change the button colors (see below for examples): blue, brick-red, brown, hot-pink, jade, light-blue, monochrome, mustard, red, sand, sea-foam, silver, wisteria. Default: blue.
  • topsy_nick: This should be set to the Twitter username that you want to appear in retweet text (without an @). Default: “TopsyRT”.
  • topsy_style: This can be set to “big” if you want a large, squarish button, or “small” for the one-line “capsule” or “Chiclet”-style buttons. Default: “small”.
  • topsy_order: Sets the order the small button elements will be displayed in. This variable must be a comma-separated list of three items: “count”, “retweet”, and “badge”. Whatever order you place those items in, that’s the order they’ll appear in. Badge refers to Topsy TopLinks badges, which are displayed for pages that are in the Topsy Top5k or above. This setting will have no effect if you use the “big” setting for topsy_style. Default: “count,retweet,badge”.
  • topsy_tweet_text: Sets the text of the tweet button when there are no tweets yet. You can use this to customize your button text if your web site isn’t in English. Default: “tweet”.
  • topsy_retweet_text: Sets the text of the retweet button when there have been tweets. Default: “retweet”.
  • topsy_streaming: If set to “on”, turns on the Streaming feature, which makes the Topsy buttons update their tweet counts when new retweets happen. (This used to be called “topsy_livecount”.) Default: “off”.
  • topsy_shorturl_service, topsy_shorturl_user, and topsy_shorturl_auth: These three items together allow you to supply your own URL shortening service, username, and API key (or password). For now, the only allowable topsy_shorturl_service is ‘bit.ly’. We intend to add others soon. Default: nothing.

If you are using a setting in a single button, you can remove the “topsy_” at the beginning of the setting name. If it’s in the topsy_global_settings tag, you must include the full topsy_whatever name.

List of Color Themes

Here are examples of all eight of the available color themes:

wisteria

brown

monochrome

jade

brick-red

sea-foam

mustard

light-blue

hot-pink

silver

sand

red

blue

Notes for Previous Users

If you’ve already been using the Topsy Retweet Button on your web site, you can upgrade to the new version. The new version uses “lazy loading” technology so that even if Topsy’s site is slow, yours will still load quickly. The Topsy Retweet Buttons will load after the rest of your site’s code.

To upgrade, just add the topsy.js tag from the top of the page, then convert all of your current button tags into <div class="topsy_widget_data"> tags, with HTML comments inside them.

Important Note: You should not be using button.js if you switch to the new style! Do not call both topsy.js and button.js on the same page; they will conflict with each other, and the results will probably not be what you want.

Example of button code conversion:

Suppose you originally had a button whose code looked like this:

<script type="text/javascript">
     var topsy_nick = "YourTwitterName";
     var topsy_style = "big";
     var topsy_url = "http://example.com/some/page";
     var topsy_title = "This is my example page!";
</script>
<script type="text/javascript" src="http://cdn.topsy.com/button.js"></script>

To convert this into the new style, you probably want to move the topsy_nick and topsy_style variables into the topsy_global_settings tag, so:

Then you’d make your button code look like this: