Using TopTwits to track your Twitter linkage 

When tr.im announced that it was going open source, I said I would also release the code of the app that does my Top 40 page and that of Jay Rosen, Kevin Tofel and Zach Seward.

TopTwits is that app. It runs as an OPML Editor tool. This means you must have the OPML Editor installed on your machine, and then install topTwits.root in the OPML Editor.

You must leave the OPML Editor running if you want to use it to generate the links. Otherwise, just run it when you want to produce a report. You can do this by choosing a menu command or wait a few minutes and it will produce the report without you doing anything. I leave mine running all the time on an EC2 server. In either case, you must use tr.im or Adjix to shorten the URLs if you want TopTwits to track them.

How to set up TopTwits 

1. Install the OPML Editor if you haven't already done so.

2. Choose the Tool Catalog command from the Misc menu and click on the Install link next to TopTwits.

3. A web page opens that asks for your Twitter username, but not your password. Click Submit and then fill in FTP information indicating where you want it to upload the report. There's a bookmarklet on that page that you can drag into your browser toolbar that makes linking to something through Twitter much easier. (But to use the bookmarklet, the OPML Editor must be running on the machine you're using to link.)

4. Choose between two URL-shortening services, tr.im or Adjix. Enter your account info so TopTwits can periodically query the service to find out how many people have clicked on your links. You may want to create a special account on one of these services for just this purpose, so you don't have to share other data with the TopTwits app. (Although it won't transmit the account info anywhere but to the service it's connected to, to authorize access to the data in the report.)

The advantage of using Adjix is that you can store copies of your shortened URLs in a bucket on Amazon S3 so you're protected if Adjix should fail or go out of business. You can also use a custom domain so your URLs appear with your branding instead of someone else's. That's how Jay's links appear to come from jr.ly. for example. tr.im does not have these features as of September 2009.

It's possible that other services will be added. Since this is now an open source project it's hard to know what will happen.

Editing your template 

If you want to change the look of the report page, choose Edit Template from the TopTwits sub-menu of the Tools menu in the OPML Editor app. You'll be editing the template in the OPML Editor outliner. Screen shot.

The items in <%macrobrackets%> indicate where the report builder inserts information. You can move these around. There's also a CSS style sheet at the top, which you can edit.

Here's an outliner crib sheet that shows you how to use the outliner in case you're not familiar.

Multiple users on one installation 

It is possible to have multiple users on one installation of TopTwits, but there are caveats.

1. You have to configure it using the object database in the OPML Editor. Look in config.root, at config.topTwits.users. Copy what you see there for the single user that's configured through the Prefs screen.

2. If you want your users to use the Bookmarklet, the server must be accessible to them. Edit the bookmarklet to replace 127.0.0.1 with the address of your server. However they do not have to use the bookmarklet, but they must be logged on to either Adjix or tr.im when they create their links otherwise TopTwits won't be ablel to find them.

3. Word to the wise -- unless you're prepared to become a sysadmin, don't attempt this. Your users will have problems and will make feature requests. It might be fun for a while, but eventually it becomes work. Nothing wrong with that of course.

That's about all there is 

It's all in the setup. Now you just post links and leave the OPML Editor running, the report will be rebuilt every 5 minutes.

If you have questions or comments, post them below.

TopTwits is licensed under the GPL. Please respect open source.

Dave Winer

PS: If you get it running post a pointer to your Top 40 page here so we can have a look!

Final note