Customized Widget Tutorial with Twitter Developer Tools

Twitter is one of the biggest social networks out there, and it can certainly drive a lot of traffic offering plenty of exposure and good conversion rates. Whether you are a developer or not you can make use of Twitter’s developer tools to interact with users on your own site. You can do this with these four tools offered by Twitter:

1. Embedded Timelines – a.k.a. widgets, that’s what we’ll be looking at today!
2. Twitter Cards – Similar to Facebook’s “share” tool, where you can include external content, excerpts and images.
3. Embedded Tweets – Allows you to add a single Tweet on your own site as a cool and styled quote.
4. Twitter API – This is the powerful and advanced way to interact beyond simply pulling data.

Today we’ll take a quick look at some methods of adding custom and styled widgets to your web site, taking things beyond the basic and standard five latest Tweets. Because at the end of the day we all want to stand out of the crowd, don’t we?

Warming Up

The easiest way to get started is using Twitter’s own tools. Most people don’t actually know that Twitter offers a cool “wizard” to create customized timelines.

If you are logged in you’ll see a screen with the most common functionalities, like so:

The current version offers 4 widget types:

1. Profile (or timeline) – The ol’ common widget we see pretty much anywhere. It show the latest Tweets.
2. Favorites – This will create a custom timeline of your own favorites. Those who are used to Google Readers sharing tools have seen this feature before (where you can share your own favorites as a RSS feed).
3. Lists – It’s good to group people with things in common, like activity field, Tweets type, company.
4. Search – You can show the results of your own searches or hashtags.

They are pretty straightforward, but that does mean little or no customization. That is a fair trade, since you can’t have everything in your life, right? Well, actually you can.

Getting Your Hands Dirty

Feel like coding today? Yes? Good. Let’s dig a little deeper and create a customized widgets.

The first thing you’ll need to do is to call the Twitter widgets functionality. This pretty line will do the job:

<script src="http://widgets.twimg.com/j/2/widget.js"></script>

Next, we’ll need another snippet to actually create the widget. This will do it:

<script>
	new TWTR.Widget({
		version: 2,
		type: 'profile',
		rpp: 5,
		interval: 5000,
		width: 400,
		height: 400,
		theme: {
			shell: {
				background: 'black',
				color: 'white'
			},
			tweets: {
				background: 'white',
				color: 'black',
				links: 'red'
			}
		},
		features: {
			scrollbar: false,
			loop: false,
			live: false,
			hashtags: false,
			timestamp: false,
			avatars: false,
			toptweets: false
		}
	}).render().setUser(' speckyboy').start();
</script>

Now, let’s translate these attributes into plain English:

• Type: Pretty much those 4 types we’ve seen before. Possible values are ‘profile’, ‘favorites’, ‘list’, ‘search’.
• Rpp: Is the number of Tweets to be shown.
• Interval: How many milliseconds should the widget wait before attempting to retrieve new Tweets. The higher the number, the more JS calls you’ll have.
• Width and Height: You guessed right, dimensions for twitter box.
• Shell and Tweets: The basic styling options for your boxes (hang on though, things are about to get better).
• Scrollbar: False will force only the number of Tweets you selected to be shown, true and the user can navigate through past Tweets.
• Loop: False won’t bring duplicated results, true will bring the same results if the search doesn’t find anything new.
• Live: True will reload the search continuously, not just on page load.
• Hashtags, Timestamp, Avatars: false/true to hide or show those items.
• Toptweets: false to show all Tweets related to your search and true to show only the popular ones.

Notice that we have the mandatory call setUser(‘UserName') for the profile widget. It doesn’t ask for any password nor have any control method, so you have pretty much the same capabilities as you’d have in your wizard but here we have a whole set of new cool things we can do.

And since the Twitter API doesn’t have any inline CSS rules we’ll use our own code. It has a lot of obvious class names and all you will need to know is a little CSS to customize it, for example:

.twtr-widget {
	width: 400px;
	margin: 50px 0 0 50px;
	padding: 0 0 25px;
	background: white url(background.png);
}

The same rule applies for the header: .twtr-hd, the body: .twtr-bd and the footer: .twtr-ft. A piece of cake. You can pretty much use any CSS rule you want to change the colors, sizes, backgrounds, shadows, gradients and you can even make use of pseudo-elements like :before and :after.

How to Customize your Search

We could also make use of the widget to show a custom search. Just change the type to search and add the title, subjects, and search attributes to the widget. The same CSS styling will apply, so you can easily add more than one widget.

Its the search attribute itself is where all the magic happens. Here are the possible search terms:

• Regular Text Search: Nothing new here. You can search by “speckyboy” and will get a lot of results.
• Hashtag: If you add the “#” operator you’ll filter the hashtags for that item.
• Excluding: If you are getting too many results you can remove the trash by adding -undesiredTerm.
• Authorship: Using from:speckyboy will return only Tweets from a certain user.

But in order to get a really good result you can chain multiple search methods into a single string, using the AND/OR operators. But the OR works as a XOR operator (exclusive or) which means that it’ll bring one result OR the other, but not both.

For instance, if you search “dev OR frontend” and you have a Tweet saying “@speckyboy is the coolest dev blog out there. Seriously good frontend tips there” this Tweet won’t show in your search, because of the XOR behavior. You could simply search for “dev frontend” to get both results.

Long Story Short

This is just the beginning, the eye opener to a much bigger world than simple Twitter widgets. Now I ask you, have seen any good widget implementations or customizations our there? Feel free to share!