Since my last post outlining the different iPhone web apps, I’ve had a chance to play around with iUI a little more and get a successful app (for my side project, Notes/Tasks) up and running. As there still is not a lot of documentation on using iUI, I figured I would sit and write down some of what I’ve learned. As I’ve been developing the backend in Ruby on Rails, I figured I’d also add some tips and tricks for getting iUI to work well with dynamic content. This article will cover the basic of creating a web application with iUI, including creating buttons, using forms and lists, and also how to integrate it with rails’ MVC framework.
Background
The app I’m using for demonstration is a side project of mine – building a web interface for a notes and tasks desktop application that synchs with an online server. The desired functionality for the web is fairly simple: it needs restrict access to uses who have logged in, be able to display lists of notes and tasks, details for each individual note or task, edit the text of a note, mark a task as completed, and create new notes and tasks. I’ve already written the API for the server (also in rails) so this project will focus on creating the user front end, rather than the backend application code.
Getting Started
I’m assuming you have a rails project already set up and configured. The first step is downloading the iUI files. In my original short review of iUI, I downloaded the last stable released version of the code, which was published in 2007. There were some significant shortcomings so for this go around, I tried the latest SVN snapshot, available here. To get started, download all the files into your ‘public/images’, ‘public/javascripts’ and ‘public/stylesheets’ directories. Next you’ll want to open the ‘iui.css’ file in your favorite text editor and replace the beginning of the image file urls with ‘/images/’.
The Basics
The iUI ‘framework’ is composed of two parts, a javascript file containing handler code, and a stylesheet/images that mimick the look of the iPhone. The magic of iUI happens when you click on a link: rather than taking you directly to the link, the javascript captures the event and downloads the page content using an AJAX call. The HTML is then loaded into a div and appended to the existing page. The new panel is then made visible to the user using a sliding transition that mimicks a compiled iPhone app. For the end user, the effect is that all the content appears on one page seamlessly without having to click back and forth. The other advantage is that the iUI javascript can manage the buttons in the top bar of the page, giving you the standard ‘back’ button that displays the title of the last panel.
Now, for those of you familiar with Rails, you’re probably thinking ‘Wow! AJAX! I use that to load my partials!’ For those of you not familiar with Rails, let me explain: when using AJAX (or rather the XmlHTTPRequest method to be more precise) you are downloading arbitrary HTML transparently to the user. Because of this, you don’t need really need the <head> and <body> tags, and all that goes with them; rather you need only the new content on the page. Rails is, in part, built to take advantage of this through a mechanism called partials. Partials are what they sound like: partial pieces of a page that can be rendered and delivered to the user. Normally, this would not be enough to view a webpage, because you are missing the <head> and <body> tags, but for our purposes that is exactly what we need because the <head> and <body> tags have already been downloaded when the page was first loaded.
But I digress. The component pieces of an iUI enabled web page are <div> tags and <ul> tags. By default, Divs represent a group of elements on the page (usually details or something) and the ul tags are for the standard iPhone list.
 |
 |
| ul ‘list’ layout with arrows |
div ‘panel’ layout – notice the spiffy pinstripe background |
Setting up iUI with Rails
The first thing to do is set up your application’s layout to load the iUI javascript and css files, and add the top ‘toolbar’.
<!DOCTYPE html PUBLIC "-//W3C//D
TD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<title>Notes/Tasks</title>
<meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;"/>
<meta name="apple-touch-fullscreen" content="YES" />
<style type="text/css" media="screen">@import "/stylesheets/iui.css";</style>
<script type="application/x-javascript" src="/javascripts/iui.js"></script>
<body>
<div class="toolbar">
<h1 id="pageTitle"></h1>
<a id="backButton" class="button" href="#"></a>
</div>
<%= yield %>
</body>
</html>
The two meta tags are iPhone specific, and let safari know that the content should not be zoomable and should be fullscreen. The <div class=”toolbar”> tag is the source for the toolbar that will appear at the top of the page. In the above example, only the back button and the title are present, but I’ll show you how to add custom buttons later. And of course, the <%= yield %> statement is where your partials will be rendered.
Creating Forms
One of the requirements for my web app is to require users to login to view their notes and tasks. The default way the iUI handles forms is to load them using the standard AJAX call. For a login screen, this isn’t desirable: once a user logs in, the URL is still ‘/user/login’ (for example) rather than the actual application url which can cause confusion when bookmarking. I want the form to actually submit and redirect to the ‘index’ page. Below is the basic login code I’m using:
<form id="Login" title="Login" class="panel" selected="true" action="/user/authenticate" method="post" redirect="true">
<fieldset>
<div class="row">
<label>Name</label>
<input type="text" name="username"/>
</div>
<div class="row">
<label>Password</label>
<input type="password" name="password"/>
</div>
</fieldset>
<a class="whiteButton" type="submit" href="#" target="_self">Login</a>
</form>
By default, iUI tries to asynchronously submit the form and load the next page using javascript, however as mentioned above, I want the functionality of a normal form submit, i.e. redirect the entire page to the new url. To accomplish this, I added this simple switch to iUI’s default ’submitForm’ method (starting on line 390):
function submitForm(form)
{
if (form.getAttribute("redirect") == "true")
form.submit();
else
iui.showPageByHref(form.action || "POST", encodeForm(form), form.method);
}
The above code will use the default functionality unless a “redirect=’true’” attribute has been added to the <form> tag (as you can see in the example above.
A nice feature of iUI is that you don’t need to use the standard <input> submit button – you can pretty much use anything, like the link and image above. Also, by using the <div class=”row”> tag, you can get the standard white row with rounded corners. Pretty cool.
The Main Page
The rest of the requirements for my app revolve around lists: I want to display all the notes and tasks in a list that users drill down into to get at details for specific notes and tasks. iUI makes this type of navigation dead simple by using the <ul> tag.
To start, we need to create a new method in the rails controller – in my case, I created a new ‘view’ controller to handle the iPhone specific traffic and will use the ‘index’ method as the start page. To create the main page, the code is pretty simple:
<ul id="home" title="Notes/Tasks" selected="true">
<li><a href="#notes">Notes</a></li>
<li><a href="#tasks">Tasks</a></li>
</ul>
<ul id="notes" title="Notes">
<% for note in @notes %>
<li><%= link_to note.title, :controller => :view, :action => :note, :id_hash => note.id_hash %></li>
<% end %>
</ul>
<ul id="tasks" title="Tasks">
<% for task in @tasks %>
<li><%= link_to task.title, :controller => :view, :action => :task, :id => task.id_hash %></li>
<% end %>
</ul>
The partial takes two instance vairables, ‘@notes’ and ‘@tasks’ to load the data. Notice we go ahead and create the root menu (‘home’) as well as the sub menus in the same page, rather than use an AJAX call. This is up to you, but the method above reduces the overhead of another ajax call – the data is already available. However, the submenus link to a ‘note’ and ‘task’ detail page, passing the unique id of each, that is loaded dynamically.
Stay tuned to part 2, where I’ll go over some of the more advanced features of iUI and some tweaks you can make to add functionality to the base library.
Thanks for this great post. Super helpful – especially the javascript patch to redirect the form. You should submit that to the iui team as an improvement on the code. I think a lot of people would like to see that added.
Yes, thanks for this great post. It saved me a lot of work. I’m glad I found your blog, as cooking and coding are the two things I do (and enjoy doing) the most.
Hey, when is Part 2 coming? I just got started with iPhone WebDev. We use ColdFusion here, so I need to be able to make some simple forms and process some data. Just need some more basic functionality explained… Thanks for the post.
Hey Mike,
Great post! Just wanted to add my bump to part 2, if you’re still messing around with iui!
Cheers,
-Henry
Many people who were using iUI came to the problem when they tried to implement image gallery. That’s why I wrote a Jaipho – iPhone optimized image gallery, which looks just like native iPhone Photos application.
And here is an article how to use it with iUI http://www.jaipho.com/content/using-jaipho-iui
Cheers,
Tole
Hi! I was surfing and found your blog post… nice! I love your blog.
Cheers! Sandra. R.
This article was great!
+1 for Part 2!!!