Creating native-like user experiences in PhoneGap with App-UI
Created
4 June 2012
Requirements
User level
Intermediate
Sample files
Adobe products used in this article
Additional products used in this article
App-UI: A free and open-source collection of reusable "application container" user interface components that may be helpful to web and mobile developers for creating interactive applications using HTML and JavaScript, especially those targeting mobile devices.
Rotten Tomatoes API: This API provides reviews of the latest movies out in theaters. You will need to obtain an API key from Rotten Tomatoes for use in this example. I explain how to do so in the Build the app section of this tutorial.
PhoneGap is a free, open-source technology that enables developers to build natively installed mobile applications for all of the major mobile platforms, using traditional web-based technologies. The best way to think of a PhoneGap application is to think of it as a "chromeless" web browser, where the web view takes up the full width and height of the screen. You build your entire application interface using HTML, CSS, and JavaScript.
Since you build applications with HTML, CSS, and JavaScript, you have complete control over how everything looks, feels, and how users interact with it. However, since the user interface is based on a web view, it is very easy to create applications that feel like web pages rather than applications. To create application experiences that feel more like "apps," you have to consider the overall user experience, and how people interact with the application's visual content.
To aid you develop and create native-like user experiences in PhoneGap applications, I'd like to introduce you to app-UI, a pet project that I've been working on, which you can download from the Requirements section at the beginning of this article. App-UI is a free open-source set of containers created with HTML, CSS, and JavaScript, which provide a native-like user interface shell for use within your PhoneGap or web applications. App-UI provides the following:
- A simple ViewNavigator for "pushing" and "popping" views in and out of the user interface
- A SplitViewController that allows for side-by-side content and adjusts itself when you change the device orientation
- A SlidingView that enables you to use a swipe gesture to reveal content behind the main content.
App-UI handles the hard part of swapping content with nice animations and transitions, allowing you to focus on building your application experiences.
In this article, you will learn how to create a basic application in Dreamweaver using the ViewController and deploy that application to multiple devices using the latest PhoneGap Build (download using the link in the Requirements section). PhoneGap Build is a cloud-based compiler for PhoneGap applications. All you need to do is upload your raw HTML, CSS, and JavaScript code to PhoneGap Build, and the PhoneGap Build service will provide you with links to download platform-specific binaries directly to your device. Note that Dreamweaver nor PhoneGap Build is required to use app-UI. app-UI will work in any HTML-based experience.
Getting Started
The first thing you'll need to do is download app-UI from the Addiional products section at the beginning of this article.
Once you have downloaded app-UI, let's set up the development environment in Dreamweaver.
- Open Dreamweaver and select the Create new Dreamweaver Site option on the Dreamweaver Welcome Screen (Figure 1).
- Specify a site name and a folder where you will store the site content on your local machine. Ignore the Servers tab, since you will use this locally (Figure 2).
Enter your information and click Save to proceed. Dreamweaver creates the new site, but it is empty because you don't have any files in it yet; Dreamweaver will display the Welcome Screen again.
Now that you've set up your Dreamweaver site, you can start building the app.
Building the app
Now you that you've set up your Dreamweaver site, you can start building your app. First you will set up the libraries and then learn about the code that makes up this application.
Setting up the libraries in your app
- On the Dreamweaver Welcome Screen, select the Create New HTML option to create a new HTML file, as shown in Figure 3.
Dreamweaver displays its HTML editor interface. First, you must set up the initial HTML content using the following steps.
- Add the following HTML code, and save it as index.html. This will be the starting point of your application.
<!DOCTYPE html>
<html>
<head>
<title>Rotten Tomatoes</title>
<meta name="viewport" content="width=device-width, user-scalable=no">
</head>
<body></body>
</html>
- Locate the ZIP file archive containing app-UI that you downloaded earlier. Extract the ZIP file and copy the the libs and viewnavigator folders into your Dreamweaver project. If you have copied the folders correctly, then you should be able to see them in the Files view in Dreamweaver.
- To include the appropriate script and CSS links in the HTML file (to be able to use them inside of the HTML experience), add the following lines as children of the <head> tag in the index.html file to include the appropriate dependencies:
<script src="cordova-1.7.0.js"></script>
<script src="libs/jquery-1.7.1.js"></script>
<script src="libs/jquery.animate-enhanced.js"></script>
<script src="libs/iscroll.js"></script>
<script src="libs/noClickDelay.js"></script>
<link rel="stylesheet" href="viewnavigator/viewnavigator.css" type="text/css"/>
<script src="viewnavigator/viewnavigator.js"></script>
<link rel="stylesheet" href="libs/css/activityIndicator.css" type="text/css" />
App-UI uses jQuery, jQuery.animate.enhanced, iScroll, and a few other open source libraries, to create the overall app-like experience. The jQuery library is a solution accelerator tool, making the overall coding experience in JavaScript easier. The jQuery.animate.enhanced library is used for CSS3 transform animations instead of "top" or "left" positioning. CSS3 transforms are hardware accelerated on many mobile platforms, including Apple iOS and the latest version of Android, and will provide a better user experience. The iScroll library is used for consistent touch-based scrolling of content on mobile devices. The files viewnavigator.css and viewnavigator.js contain the core logic of the ViewNavigator component that we use in this example.
You may have also noticed that there is a link to cordova-1.7.0.js, but that there isn't actually a file of that name within the project. Don't worry, you are not missing a file. PhoneGap Build adds this file automatically when it uploads code. I discuss this in detail later in this article.
Initialize the app-UI application container and provide it with a default view. In the app-UI ViewNavigator, views are added or removed from the user interface using the pushView , popView , or replaceView functions. The parameter of the pushView function is a JavaScript object that requires the attributes title and view , which I refer to as a "view descriptor." The view attribute should be a jQuery reference to a DOM element.
The following code is triggered on the jQuery "ready" event. It will create an initial view descriptor, create the ViewNavigator instance targeting the HTML <body> tag, and will push the initial view descriptor into the ViewNavigator instance.
<script>
$(document).ready( function() {
rootView = { title: "Rotten Tomatoes",
view: $("<div id='rootView'><div class='activityIndicator'></div></div>")
};
window.viewNavigator = new ViewNavigator( 'body' );
window.viewNavigator.pushView( rootView );
});
</script>
You can enable live preview inside of Dreamweaver to see your code side-by-side next to an interactive view of the application. If you do so, you will see a blue header containing the title, and the main body area will contain the spinning animation div, as specified in the view descriptor.
Next, let's request some data and put it into the view. In this example, we'll be consuming data from the Rotten Tomatoes API, which provides reviews of the latest movies out in theaters. You will need to obtain an API key from Rotten Tomatoes for use in this example.
- Within the <script> block, add the following variables, which your code will use throughout this example:
var API_KEY = "PUT YOUR API KEY HERE";
var data = [], rootView=undefined, rootData=undefined;
- Add the following code inside of your "ready" event handler function. This uses the jQuery ajax method to asynchronously request data from the Rotten Tomatoes, which you can use to update the user interface.
var url = "http://api.rottentomatoes.com/api/public/v1.0/lists/movies/box_office.json?limit=25&country=us&apikey=" + API_KEY;
$.ajax({
url: url,
dataType: "json",
success: function(data, textStatus, jqXHR) {
rootData = data;
renderDefaultView();
},
error: function(jqXHR, textStatus, errorThrown) {
alert("error")
}
});
Once data has been retrieved from the server, it will be stored in the rootData variable, and then the renderDefaultView function will be invoked. Let's now examine that function.
The renderDefaultView function
The renderDefaultView function will access the root view that we created earlier and will remove its child elements. Next, it will loop over the movies that were retrieved from the Rotten Tomatoes API and create an HTML string containing a of all the movies. Once the API creates the list, the HTML string is set as the HTML of the root view, and then the ViewNavigator's scrollable area is reset using the resetScroller() function.
function renderDefaultView() {
rootView.view.children().remove();
var html = "<ul>";
for ( var i = 0; i < rootData.movies.length; i ++ )
{
var movie = rootData.movies[i];
html += "<li id='" + movie.id
+ "'onclick='renderDetails(\"" + i + "\")'>"
+ movie.title + "</li>";
}
html += "</ul>";
rootView.view.html( html );
window.viewNavigator.resetScroller();
}
If you stop and preview this content now, you will see that once the data is loaded, it displays as an HTML list inside of the ViewNavigator.
Inside of the renderDefaultView() function, you may have noticed that each list item has a click event handler. If you were to click a list item now, you would receive a runtime error because we haven't defined the renderDetails function yet. Let's do that now…
The renderDetails() function
The renderDetails() function converts the data for the selected row, turns it into a HTML string, creates a view descriptor and then pushes it into the ViewNavigator instance using the pushView() function. The renderDetails function accepts an integer index parameter, which corresponds to the appropriate array index in the rootData array, which contains the data retrieved from the Rotten Tomatoes API.
The first thing that renderDetails does is remove the listSelected CSS class from all <li> elements in the default view, then applies the listSelected CSS class to the <li> that a user clicks. Since we haven't added any CSS styles yet, you won't notice a difference at this point, however, we will later add a CSS class that to show which list item a user has clicked.
After setting styles on the list item, renderDetails generates an HTML string that will be used to display the movie's details. In this case, it is just using raw string manipulation, however, if you wanted to use an HTML templating library, you could use it here.
Once the HTML string has been generated, a view descriptor is created, and pushed into the ViewNavigator using the pushView() function.
function renderDetails(index) {
var movie = rootData.movies[index];
rootView.view.find( "li" ).each(function(index) {
$(this).removeClass( "listSelected" );
});
$( "#"+movie.id ).addClass( "listSelected" );
var html = "<div id='detail'>";
html += "<h1>" + movie.title + "</h1>";
html += "<p><strong>" + movie.mpaa_rating + "</strong>, " + movie.runtime + "min. - (" + movie.year + ")</p>";
html += "<img src=\"" + movie.posters.profile + "\" class='moviePoster'>";
html += "<p>" + movie.synopsis + "</p>";
html += "<h3>Ratings:</h3><p>";
html += "<strong>Audience:</strong> " + movie.ratings.audience_score + " - " + movie.ratings.audience_rating + "<br>"
html += "<strong>Critics:</strong> " + movie.ratings.critics_score + " - " + movie.ratings.critics_rating + "<br>"
html += "</p>"
html += "<h4>What the critics say:</h4><p>" + movie.critics_consensus + "</p>";
html += "<h3>Cast:</h3><p><ul>";
for ( var i = 0; i < movie.abridged_cast.length; i ++ ) {
var actor = movie.abridged_cast[i];
html += "<li><strong>" + actor.name + ":</strong> ";
if ( actor.characters ) {
for ( var j = 0; j < actor.characters.length; j ++ )
{
if ( j > 0 ) { html += ", " };
html += actor.characters[j];
}
}
html += "</li>";
}
html += "</ul></p></div>";
var viewDescriptor = { title: movie.title,
view: $(html),
backLabel: "Back"
};
window.viewNavigator.pushView( viewDescriptor );
}
You may notice that in this case, the view descriptor has a backLabel attribute that specifies the label text that displays on the Back button, which ViewNavigator automatically creates. If you click the Back button, the current view is popped or removed from the ViewNavigator instance, and it displays the last view.
If you run this example now, you will see that clicking a list item displays that movie's details within the view navigator, as shown in Figure 6.
At this point, we have logic to create a ViewNavigator instance, request data from the server, and display that data inside of the ViewNavigator . The ViewNavigator has default styles and handles transitions between content, but overall the application doesn't look very polished. Let's change that.
Next we add CSS styles that will improve the look of the application.
- Add a
<style>element to your HTML, and add the following styles.
<style>
* {
font-family: Arial, sans-serif;
}
.listSelected {
background-color:#555;
background-color:rgba(0,0,0,0.75);
color: #FFF;
font-weight:bold;
}
ul,li {
padding:0;
margin:0;
border:0;
}
.viewNavigator_contentHolder li {
padding:0 10px;
border-bottom:1px solid #ccc;
height:40px; line-height:40px;
font-weight:normal;
cursor:pointer;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
-o-text-overflow: ellipsis;
-moz-binding: url('assets/xml/ellipsis.xml#ellipsis');
}
</style>
The style applied to the "*" sets the font for the entire experience. The application will now use Arial font instead of the default Times New Roman font. The listSelected CSS style changes the background color of the list item that a user clicked. This gives the visual representation of a selected item in the list. The ul , li , and viewNavigator_contentHolder li styles format the HTML list so that it looks much more like an actual list that you would expect within an application.
Now that we have the list formatted, let's add some formatting to the selected movie's details view.
- Add the following CSS styles.
#detail {
padding:10px;
}
.moviePoster {
float:right;
width:120px;
height:178px;
overflow:hidden;
margin:10px;
padding:2px;
border:1px solid #999999;
}
#detail li {
white-space: normal;
overflow: visible;
height:auto;
}
The #detail CSS style applies to the <div> containing the movie details. It simply adds padding around the HTML content to have an aesthetically pleasing visual border. The moviePoster style adds a padding and a border around the movie poster image, and floats it to the right of the descriptive content. The #detail li CSS style applies formatting rules to the list that contains the cast members.
Now we have nicely formatted content within the application experience, however, it is still using the default styles of the app-UI framework—the blue header and plain white background. Let's add some CSS styles to change this.
The first app-UI styling that we'll do is change the header background. I created an image that has a textured red gradient background, with a lower border and shadow, as shown in Figure 9.
- To change the header style in app-UI, you just need to change the
viewNavigator_headerstyle and specify a URL to the background image.
.viewNavigator_header {
background:url(assets/header_background.png);
}
- We'll add a subtle background. First, set the background color of the
viewNavigator_contentandviewNavigator_contentHolderCSS styles, and then add a background image to the#detailand#rootViewCSS styles. I added a subtle light-gray image of a tomato to add visual dimension without cluttering the user interface.
.viewNavigator_content,
.viewNavigator_contentHolder {
background:white;
}
#detail,
#rootView {
background-image:url(assets/tomato.png);
background-position:center 50px;
background-repeat:no-repeat;
}
- By default, app-UI's back button has rounded corners. To make the back button's corners square and make the color darker, use the following CSS style:
.viewNavigator_backButton {
-webkit-border-radius: 0px;
-moz-border-radius: 0px;
border-radius: 0px;
background:#555;
color:white;
border:1px solid black;
}
If you preview the application now, you will see the new header styles and subtle background formatting as shown in Figure 10.
PhoneGap Build
Now that we have the application complte, it is time to install it on devices.
- Create an account on PhoneGap Build. With PhoneGap build, you can upload your content directly to the PhoneGap Build site, point PhoneGap Build to a Git repository, or push your code to PhoneGap build from Dreamweaver. Regardless of the option you choose to get your code into PhoneGap Build, PhoneGap Build will perform a cloud-based compilation of application binaries that you can simply download to your device to install.
Since I've been working with Dreamweaver in this example, I'll use the PhoneGap Build integration in Dreamweaver CS6.
- Open PhoneGap Build and go to the Site menu. Select the PhoneGap Build Service > PhoneGap Build Service menu option.
The PhoneGap Build Service window displays.
- Log into your PhoneGap Build account. Once you have logged in, PhoneGap Build displays the project settings screen (Figure 12).
- Select the Create as new project option to create a new project on PhoneGap Build and click Continue. This creates a new file called config.xml that contains metadata about your PhoneGap application. To customize the metadata for your application, including its displayed name and unique identifies, simply edit the config.xml file. You can read more about the config.xml file from the PhoneGap Build documentation.
- Dreamweaver uploads your code to PhoneGap build and automatically starts compiling your applications. Once PhoneGap has compiled your applications, the PhoneGap Build Service window displays a message: "Build Complete" and presents you with options to download the code to your devices (Figure 13).
Note: To successfully build for iOS devices, you will need a valid Apple Developer Account, and you must upload your provisioning certificates to the PhoneGap Build service.
- Click the QR code button (the button with the fuzzy-looking barcode), to display a QR code within the PhoneGap Build Service window as shown in Figure 14. You can use a QR code reader on your mobile device to take a picture of the QR code, which will automatically trigger your mobile device to download the application binary file and install it.
Conclusion
PhoneGap Build takes the pain out of compiling for multiple platforms, and compiles the platform-specific application binary files for you (IPA, APK, XAP, and so forth). PhoneGap Build provides you with quick links to download those files and install them onto your devices with ease. You won't have to set up individual development environments for the various platforms.
You can use PhoneGap to easily create natively installed mobile applications using HTML, CSS, and JavaScript. App-UI is an open source collection of application containers that bring familiar app-like paradigms to HTML-based experiences. PhoneGap Build is a service for simplifying your multi-platform development with PhoneGap.
Where to go from here
To learn more about PhoneGap, check out the Adobe Developer Connection collection of PhoneGap articles, or the PhoneGap Getting Started guides.
To learn more about app-UI, be sure to check out the open source project.
To learn more about PhoneGap Build, be sure to check out build.phonegap.com.
+
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.
More Like This
- Real-time data exchange in HTML5 with WebSockets
- Introducing the HTML5 storage APIs
- Introducing theexpressiveweb.com beta
- Adobe, standards, and HTML5
- Developing HTML5 games with Impact JavaScript game engine and Dreamweaver CS5.5
- Using the Geolocation API
- CSS3 basics
- Backbone.js Wine Cellar tutorial – Part 2: CRUD
- JavaScript object creation: Learning to live without "new"
- Object types in JavaScript
