Unofficial Twitter Widget Documentation
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!
July 24th, 2009 at 12:10 am
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!
July 24th, 2009 at 3:34 am
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 :)
July 24th, 2009 at 8:18 am
I clicked on the examples, but all that displayed was a black background and a Twitter logo.
Tried the example on Firefox and Chrome.
July 25th, 2009 at 3:23 pm
Nice work, bro. And thanks for the insider tips!
July 27th, 2009 at 1:43 pm
It would be great if the HREF’s utilized TARGET=”_blank” so that links would render in a new window (or tab). I would love to add this widget to my site, but am hesitant because it will divert users off of my page.
July 30th, 2009 at 10:06 am
If retweets are defaulted to off, how do we turn them back on?
Also, is there a way to customize the profile or search widget to only show one’s favorited tweets?
Any help would be greatly appreciated.
July 30th, 2009 at 11:06 am
Thanks so much for creating this widget! I work for a nonprofit and we’re using it tonight for a hashtag virtual tweetup that benefits feeding hungry children — and we couldn’t do it nearly so gracefully without your help!
July 30th, 2009 at 12:24 pm
ok, so how do I make it show the latest tweet on the top instead of pushing it down? as it loads, it ends up pushing the latest tweet off the visible area leaving older comments visible.
July 30th, 2009 at 10:46 pm
search the google then find your site.
that is a really excellent post.
Thanks for the post.
July 30th, 2009 at 11:28 pm
@Jim, thanks :)
@Kevin, noted. will most likely become a feature.
@Abhi It’s in your best interest that they’re off according to our research. Really.
On another note, regarding your other question — Yes! There is a way (also undocumented).
In your constructor…
That should get you what you want. There is an example on my homepage.
@Eric that’s great to hear.
@Ben most likely a future version will have no effects with just a simple scroll bar
@Tylor :)
July 31st, 2009 at 1:03 am
I’d like an option to have the latest tweet at the top and for it to stay there until superceeded by a newer one, not dissappear off the bottom.
Also a parameter to state the maximum number of historical tweets to list.
Allowing brackets in advanced search would be nice too, but I guess that’s not your area :-)
July 31st, 2009 at 10:55 am
I have to agree with Ben - seems like most recent tweets should be on top - even in a future version without effects and a scroll bar.
July 31st, 2009 at 12:16 pm
Nice widget!
Is there a way to set the effect delay?
Is there a non-minified version of the js available?
Thanks!
July 31st, 2009 at 5:24 pm
how about a target for links? target: ‘Blank’, ??
August 3rd, 2009 at 12:22 am
hey guys, sorry for the delay in replying.
@Chris Ward, currently, the best way to do this is to turn off looping. No old tweets will appear. And when it finds a new one… it will show up at the top.
and regarding [brackets]… do you mean “quotes”? because that “does” work.
@ecw, this may just be a matter of confusion. the most recent tweets always come in first since it is the most important — and they are loaded from the bottom up… so it’s reversed. does that make sense? trust me, it would be awkward the other way around if you had the oldest tweets always load in first. you would perhaps never see the latest tweets thereby never getting the true value of it being “live”
@Warren, you can set the ‘interval’ property in the constructor object to a longer time in milliseconds. currently the default is 7000 (the time between each tweet). do this as such:
@dbegor noted.
August 3rd, 2009 at 2:31 pm
First—let me say that this is awesome. Really nice work.
Second—is there any way to limit how far into the past it reaches? I’d like to keep it from showing tweets from, say, a year ago.
August 4th, 2009 at 12:19 am
Hi Josh,
Let me first just say, thanks — and you’ll most likely ‘never’ have to worry about that problem of showing tweets that long ago. try a few sample searches out on the demo page, and note how far back they go.
August 4th, 2009 at 8:14 am
Thanks for the new Widgets Dustin :)
Though I seem to be experiencing the problem Josh mentioned above… Tweets from a year ago are appearing (with and without the loop). If I place the widget further down the page on my blog, by the time a guest sees it, it shows some really old tweets.
I know you’ve tried to create a scrolling “live” feed look… but I think I’d prefer a “static” widget that only displayed the latest tweets, with the newest one at the top. If a new tweet came in, it would pop-in at the top and push the older ones down. That way visitors would be guaranteed of only seeing the most recent ones.
It would also be nice if links could open in a new page… I’m not that worried about loosing traffic on my personal blog, but I wouldn’t want to take traffic away from some of my more popular sites.
Thanks again, and keep up the good work! Cheers
August 5th, 2009 at 8:12 am
I’m using the profile widget on my site and I want to change some things but I don’t know how.
1st I want to change it so that if you click on a link it opens in a new tab or window so that it doesn’t link away from my site.
2nd I only want to to display the updates made within the past 21 days.
Can you help me out?
new TWTR.Widget({
profile: true,
id: 'twtr-profile-widget',
loop: true,
width: 230,
height: 250,
theme: {
shell: {
background: '#dcdcdc',
color: '#434343'
},
tweets: {
background: '#ffffff',
color: '#444444',
links: '#0389ff'
}
}
}).render().setProfile('BCSProSoft').start();
August 5th, 2009 at 9:05 am
Great widget. Anyway to change the order. It seems to be in descending order which doesn’t make sense. I want to see the newest tweets always at the top and the older ones move towards the bottom eventually out of view.
August 6th, 2009 at 2:13 am
Really fantastic application, well done!
Have encountered one issue though - tweets including hashtags not appearing in my search widget regardless of what the hashtag feature is set to.
http://www.top-consultant.com/twitter_consulting_news.asp
This has the search parameters set as
to:tonyrestell OR from:tonyrestell OR tonyrestell
However I have received a tweet from @sayanghosh that is not appearing on the above search page. Conduct the same search on twitter search and it appears. There’s no RT in the message so that’s not the source of the problem.
Any ideas how to resolve? Thanks! Tony
August 8th, 2009 at 4:50 am
Anybody have any idea to make the widget SSL?
August 10th, 2009 at 3:00 pm
Hi Dustin,
I just added your profile widget to our website (mrinkbee.com) and noticed that the link to Join the conversation takes me away from our website.
I tried using _blank for the link target attribute but that doesn’t work.
Any suggestins?
August 10th, 2009 at 4:19 pm
Hi Dustin -
Quick question for you. I changed my Twitter picture, but the Profile Widget still calls for the old picture that no longer exists. Twitter and the old flash widget call the new picture, but not the new widget. What’s up with that? It’s driving me a bit crazy. Thanks!
August 12th, 2009 at 8:41 am
Love the widget. One problem I’m having is that the widget won’t load my Twitter icon/avatar it uses the default o_O one in all three versions.
http://www.twitter.com/SUMOYouth shows the icon
but sumo.SalemUM.com doesn’t.
To make sure it wasn’t a TYPO3 issue i created this page: http://www.salemum.com/revo.html to test it and when I try to login I get a “This method requires a GET” error message.
Thanks!
August 13th, 2009 at 4:16 am
I am new to Twitter but am confused about the pound sign preceding words. I do not see reference to it in the help section. I think this is what you are referring to as a hashmark but what it the function of the pound sign preceding a word? I would appreciate an email reply if possible. - MR
August 19th, 2009 at 10:52 am
Is there a way to affect the time stamp? Instead of ‘x days ago’ can the script put the actual time stamp?
August 21st, 2009 at 10:32 am
Dustin,
I would like to add this widget to a govt site but govt law dictates that all code must be 508 compliant. The only problem we are having with the widget is that the images are missing alt attributes. Any way to easily do this? I can handle the header and footer images using jquery but cannot handle the tweet imgs since they are intermittent. Any help or ideas would be appreciated. thanks.
August 21st, 2009 at 1:01 pm
Hi Patrick,
try the search widget instead… and pass this to your search:
The rest is up to you to kinda do the math.
Endora,
I sent you an email - and i’ve filed a ticket to put in the alt attribute
Chris,
it needs to proprogate in the API. i know, it can be frustrating. it should be working by now though.
Tony,
I fixed that bug :) (it was a bug)
Josh,
check out the advanced operators
http://search.twitter.com/operators
August 23rd, 2009 at 7:38 pm
Hi Dustin,
I’m also trying to get the search widget to only display posts from the last 24hours. Is this possible? If so, would you mind sharing the code with us?
Thanks
August 23rd, 2009 at 10:06 pm
After a couple of hours of playing around with some simple Javascript, I’ve worked out how to limit how far it will search prior from the current day.
dSearch = new Date();
var numDays = X; //days prior to current day
dSearch.setDate(dSearch.getDate() - numDays)
sMonth = '00' + (dSearch.getMonth() + 1);
sMonth = sMonth.substr(sMonth.length - 2);
searchDate = dSearch.getFullYear() + "-" + sMonth + "-" + dSearch.getDate();
new TWTR.Widget({
search: "(your search here) since:" + searchDate,
August 25th, 2009 at 7:35 pm
Good work. But please don’t dictate how you think we want to sort the tweets. I also think the newest tweets should be on the top of the list. If a newer tweet comes in while a user is on the web site, it should be shown on top and all other bumped down.
A better approach is to default to the current behavior (since you seem attached to it) and give us an option to change the sorting.
August 27th, 2009 at 6:46 am
Hi Dustin,
I love your widget but I have a question. When I put it on my Blogger site, the header is too tall. Is there any way to fix this? I’ve tried changing the dimensions but it doesn’t change the header.
Thanks so much,
Carol
August 27th, 2009 at 10:35 am
Hi
How can I display multiple profile widgets on the same page. I have tried changing the div id for each , but it is still not working.
Thanks
Jaco
August 30th, 2009 at 8:08 pm
Also, change this line of code,
this.results = this.results.slice(0, this.rpp);
with
this.results = this.results.slice(0, this.rpp).reverse();
August 31st, 2009 at 2:53 am
karthik,
you might think that’s better, but it’s not. really.
August 31st, 2009 at 8:57 pm
I like this widget quite a lot. I’m using it for a course web site–my first experiment in using Twitter for teaching.
The only problem is that the widget doesn’t seem to be updating. I had some problems relating to the Blogger template I’m using — it ate up part of the code, but a friend helped me fix that.
There should be three tweets showing up currently, and one is not appearing. It does show up if you do the search directly through Twitter. It is not a RT.
I’m mystified, and my assiduous Googling has turned up nothing in the way of troubleshooting. I would love some help, if possible.
September 1st, 2009 at 10:23 am
We cannot get the twitter widget to work at all. We can get twitstat that Ryan McGrath posted to work fine, but his wont scroll though results.
Is there some other code that we “should” have in our site to make this work? Sent your code to our webmaster and he swears taht it is missing some code or something. We just get “emptyness” no box, no color, nothing.
September 1st, 2009 at 10:33 am
yes, I know. But I had to do that for my customer :)
September 4th, 2009 at 1:18 pm
I am setting up the search widget for our web site, but for some reason it will not display any results for
search: ‘from:ncrr_nih_gov’,
Is this an issue with my code, a setting that I need to change in Twitter to allow the ncrr_nih_gov tweets to be discoverable by the search, or something else entirely?
Thanks for your consideration,
Craig
September 4th, 2009 at 1:20 pm
Hi Dustin,
I am setting up the search widget for our web site, but for some reason it will not display any results for
search: ‘from:ncrr_nih_gov’,
Is this an issue with my code, a setting that I need to change in Twitter to allow the ncrr_nih_gov tweets to be discoverable by the search, or something else entirely?
Thanks for your consideration,
Craig
September 6th, 2009 at 2:58 pm
Is there a way to change the colors of the Myspace Twitter Widget? If not, can the HTML version of the diget be modified to include the reply, mark as favorite buttons like the Myspace widget?
September 8th, 2009 at 7:39 am
Sorry for all the redundant posts. My browser kept returning error messages that suggested my comment was not posting.
September 8th, 2009 at 11:04 pm
Location based search operators don’t seem to be working (ie. “near:” or “within:”) Is this another bug?
September 10th, 2009 at 1:32 am
I have the profile widget on our site and I have the loop set to false but it is still showing old tweets. Any suggestions?
Thanks!
Kim
September 10th, 2009 at 4:07 pm
Dustin - This is a great widget…and no good deed goes unpunished. We’d love to use this on our Public Safety website, but don’t want an update on a fire from 10 days ago showing up.
Know it’s been asked previously, but a feature to disable scrolling and only show X most recent tweets would be great.
Thx
September 12th, 2009 at 7:59 pm
Hi, Dustin! Even though my code reads false for looping, the widget continues to scroll through old tweets. Can you help me? Thank you in advance!
September 13th, 2009 at 4:50 pm
Hi Dustin,
Love the work you’ve done here. I’m having a similar issue to Jaco’s. I’m trying to display two search widgets on the same page. The widgets appear just fine, but all of the tweets show up in the second widget. I gave them unique id’s, matching the div id’s, but no dice.
Thanks,
Nick
September 14th, 2009 at 12:53 am
I love the Twitter Search Widget so I have spent some time trying to get it to work for me. The problem I am having is when I put the widget in an iframe on my page,then when a link is clicked in the widget the webpage that opens is opened INSIDE the widget. I need it to open in a new win dow OUTSIDE the widget. I have tried adding Target=_”blank” to the href with no luck. Can you help me? Like I said, i really like this widget and have spent hours trying to find a soultion so i could keep it..in fact, its 3AM here and Im still looking…pls help
September 15th, 2009 at 7:37 am
How can you limit the number of tweets? I would only like to show the last tweet.
September 15th, 2009 at 7:57 am
How do you show the tweets in the last 3 days?
September 15th, 2009 at 3:13 pm
Hi Dustin,
I’ve got a widget pulling in multiple “from:” searches, however, I want to display the username but not the avatar. It seems that when I set avatares: false, it also hides the username.
Is there a feature to show username but not avatar?