./with Imagination

Unofficial Twitter Widget Documentation

Friday, July 24th, 2009

So, the Twitter Search Widget has officially launched. And the installation is fairly self-explanatory (as a matter of fact, I don’t think we even explained it at all??). But nonetheless, if you haven’t checked it out, it’s worth doing that now. The new widgets are hot! Ok. On with this.

So, what’s this do?

The Twitter Search Widget allows you to track any topic, live, in real-time. You can even use our advanced search operators which dogfoods straight into our own search API.

So what are these other features?

Well, for the advanced JavaScripters; or actually, I should say, ANYONE who can read JavaScript should be able to try some of these things out on your own. Which brings us to the hidden undocumented features

But first…

Let’s look at the base widget code to start off with.

base twitter widget code

<div id="twtr-search-widget"></div>
<script src="http://widgets.twimg.com/j/1/widget.js"></script>
<link href="http://widgets.twimg.com/j/1/widget.css" type="text/css" rel="stylesheet">
<script>
new TWTR.Widget({
  search: 'my search query',
  id: 'twtr-search-widget',
  loop: true,
  title: 'what people say about...',
  subject: 'stuff and things',
  width: 250,
  height: 300,
  theme: {
    shell: {
      background: '#111',
      color: '#000000'
    },
    tweets: {
      background: '#000000',
      color: '#ffffff',
      links: '#f59f00'
    }
  }
}).render().start();
</script>

What this does is load our base functionality and stylesheet. It then instantiates a new Widget object, and points to an id representing an HTML element. What this tells you already is that you could technically have multiple widgets on a page by simply instantiating new objects, populating existing <div> elements. Hey, you could create your own web version of tweet deck this way by stacking a few of them into columns :)

The features object

So there is a features object that you can pass into your constructor. There are currently four of these features.

the features object

new TWTR.Widget({
  id: 'my-element-id',
  .
  .
  .
  features: {
    hashtags: true,
    timestamp: true,
    avatars: true,
    fullscreen: false
  }
}).render().start();

Albeit mostly self explanatory, they each do this:

• hashtags: defaults to true. setting to false will hide them.
• timestamp: defaults to true. setting to false will hide them.
• avatars: defaults to true for search. and false for profile widget. setting to false will hide them.
• fullscreen: (I love this feature!) defaults to false. setting to true will give you a full viewport sized widget, perfect for displaying on large screens at events, conferences, etc.

Overall, these features are pretty great. I especially love the hashtag and fullscreen features since they are perfect for pairing.

Let’s say for instance you’re running a conference like SxSW — you could search for “#sxsw OR #sxsw09″ — and in the results, hide the hashtags so it doesn’t distract the readability of all the searches. Neat, eh?

Some examples

I went ahead and installed the widget on my own site — And here’s a few examples:

• fullscreen, hidden hashtag search for #iranelection
• fullscreen iphone to:apple (hey, we all do it)
• Or sometimes you just want to know what Evan Weaver is doing

That’s it for now

This will all undoubtedly be on our FAQ website soon enough, but it’s enough to have a play.

Happy Twidget Searching!