Skip to content
chrismichaelscott edited this page Mar 20, 2013 · 6 revisions

Overview

In this tutorial we are going to use iugo to create a Twitter search client. It should take less than 5 minutes. All of the source material is available under the "sample application" folder in the file repository (http://github.com/chrismichaelscott/iugo/tree/master/sample%20application).

Stage 1: Review the data

The aim of iugo is to decouple content (data) from markup, so a good place to start is usually the data model.

We are going to take advantage of the Twitter search API, so first off let's get a feel for the result. Head to:

http://search.twitter.com/search.json?q=Javascript

You may want to pass the results to a service like http://jsonlint.org to get a clearer view of the response. You should be able to make out the data model, including an array called results, which has most of the data we want. Specifically, we are going to use results[x].from_user and results[x].text.

Stage 2: Build the shell markup

Now we are going to design a page for our app. Let's keep it really simple. First off, a boilerplate HTML5 page:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <script src="iugo-mvvc.min.js"></script>
  <script src="jquery-1.7.1.min.js"></script>
</head>
<body>
	<form>
		<input type="text"></input><button id="search">search</button>
	</form>
	<ul>
		<li>
			<img src="PROFILE IMAGE URL" />
			<p>Name: @ACCOUNT</p>
			<p>BODY OF TWEET</p>
		</li>
	</ul>
</body>
</html>

We've included iugo and JQuery in the head as we'll use them both later. The form will be used to input a search expression and the ul will contain each result, displaying the name of the Twitter user and the message.

Stage 3: Implement the model

This part is easy - for us, the model is just a reflection of the Twitter API's response. We could mimic the fields all the way down but it is sufficient to just define the top level of the model; in this case the results list.

Add a script tag to the head, below the two libraries, with the Iugo constructor and a simple model:

<script>
	$(document).ready(function() {
		tweets = new Iugo({
			results: []
		});
	});
</script>

Stage 4: Link the model to the DOM

We need to tell iugo where to put the results when they arrive. We will add the class bindto-results to the ul and the data attribute data-bind_each to the li. Then, looking back at the data review, we will use the profile_image_url, from_user and text keys to fill in the blanks in the HTML. For the actual text we will use the data-bind_key attribute, which binds the element to the value of that key in the model. For the img URL and the user's Twitter name we will use the ${path.to.variable} syntax to inject the content into the HTML. You can find out about the details of both methods on the documentation page.

Your body tag should now read:

<body>
	<form>
		<input type="text"></input><button id="search">search</button>
	</form>
	<ul class="bindto-results">
		<li data-bind_each class="tweet">
			<img src="${profile_image_url}" />
			<p>Name: @${from_user}</p>
			<p data-bind_key="text"></p>
		</li>
	</ul>
</body>

Stage 5: Link the API to the data model

As it stands, if the data model is updated the DOM will reflect that - exactly what we want but we don't have the data to add to the model. To get the data, we are going to use a simple JQuery ajax call to the Twitter API.

First, add an event listener just under the Iugo constructor, to listen for clicks on the "search" button:

<script>
	$(document).ready(function() {
		tweets = new Iugo({
			results: []
		});

		$('#search').on('click', function(event) {
			event.preventDefault(); // don't let the page refresh!

			var query = $(this).siblings('input').val();
		});
	});
</script>

Then, make the AJAX call and set tweets.results to the results array from the API response. When that is done, iugo will bind the results to the DOM.

<script>
	$(document).ready(function() {
		tweets = new Iugo({
			results: []
		});

		$('#search').on('click', function(event) {
			event.preventDefault(); // don't let the page refresh!

			var query = $(this).siblings('input').val();
			$.ajax({
				url: 'http://search.twitter.com/search.json?q=' + query,
				dataType: "jsonp",
				success: function(data) {
					tweets.results = data.results;
				}
			});
		});
	});
</script>

That's it! Go ahead and try a query. If all is working well, you should get a results list on screen

Sanding the corners

Even though the functionality is in place, it still looks a little ugly. Applying the following stylesheet to the head tag will make things a little prettier.

<style>
html {
	height: 100%;
}
body {
	background-image: radial-gradient(lightgrey, white);
	min-height: 100%;
}
ul {
	padding: 0;
}
.tweet {
	padding: 12px;
	margin-bottom: 6px;
	list-style: none;
	border-radius: 8px;
	border: 1px solid black;
	box-shadow: 1px 3px 6px grey;
	background-color: white;
}
.tweet img {
	float: left;
}
.tweet p {
	margin: 0 0 8px 60px;
}
</style>

Also, if you open your Web browser's inspector / debugger, you may notice some 404s occuring when the page loads. This is because the browser is looking for the URL, "${profile_image_url}", before iugo has substituted it. This issue is explained on the documentation page, here.

In a nutshell, you can use an aliased tag attribute to avoid the confusion. Try changing the img tag to read:

			<img data-iugo_alias-src="${profile_image_url}" />

Finished

I hope the tutorial went well - and hopefully you learned a bit about iugo. The key points to take away from this are the clear decoupling of the data and the markup. No need to inject HTML into the page by hand, for each result. And it someone where attempting to update the HTML later it would be easy to find the li tags and the ps and strong under them.

Thanks!