with Imagination: by Dustin Diaz

./with Imagination

A JavaScript, CSS, XHTML web log focusing on usability and accessibility by Dustin Diaz

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">
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'

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

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:

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!

4 Responses to “Unofficial Twitter Widget Documentation”

  1. Ryan McGrath

    Haha, wow. I didn’t realize this was something that was being worked on at Twitter - just recently launched http://twitstat.us with a friend, but it looks like it was for naught, eh?

    Ah well, competition’s awesome. Nice job on the widget!

  2. James

    Nice work!

    One question; why not just dynamically load the StyleSheet within the JavaScript? And there’s no need for the DIV (”twtr-search-widget”), or the additional SCRIPT tag. In fact, you could just get away with this: http://gist.github.com/153958 (everything else can added dynamically, and the innerText of the SCRIPT tag can be globally eval’ed - see jQuery.globalEval)

    Just an idea… To make it simpler :)

  3. Ideas at random ...

    I clicked on the examples, but all that displayed was a black background and a Twitter logo.

    Tried the example on Firefox and Chrome.

  4. Jim

    Nice work, bro. And thanks for the insider tips!

Leave a Reply

Phone Number:

If you're about to post code in your comment, please wrap your code with the tag-combo <pre><code>. Also please escape your html entities - otherwise they will be stripped out. I recommend using postable.

Comments for this post will be closed on 22 September 2009.

Get "JavaScript Design Patterns"

"As a web developer, you'll already know that JavaScript™ is a powerful language, allowing you to add an impressive array of dynamic functionality to otherwise static web sites. But there is more power waiting to be unlocked--JavaScript is capable of full object-oriented capabilities, and by applying OOP principles, best practices, and design patterns to your code, you can make it more powerful, more efficient, and easier to work with alone or as part of a team."

Buy JS Design Patterns from Amazon.com Buy JS Design Patterns from Apress

Submit a Prototype

All content copyright © 2003 - 2007 under the Creative Commons License. Wanna know something? Just ask.

About | Archives | Blog Search

[x] close


Submit a prototype

By checking this prototype I agree that I am not submitting false credentials, pornography, or a hate crime website. I also understand that by submitting my entry I may or may not be accepted, and if accepted, my entry may be taken down at any given time if I violate these terms.