How to use PhoneGap to port quickly your web app to a native iOS and Android device

This blog post will show how to take a web site written only in HTML5, CSS3 and JavaScript and quickly develop an iOS and Android mobile application. In order to do this, I will use Adobe PhoneGap, a mobile web frame to build cross-platform mobile applications. As mentioned in my previous blog post, PhoneGap is an HTML5 app platform that allows you to author native applications with web technologies. Even though my blog post will only show how to develop an iOS and Android application, PhoneGap also supports developing BlackBerry, webOS, Windows Phone 7, Palm devices, etc. In a nutshell, you’ll be using a PhoneGap wrapper that contains your web-based HTML, CSS and JavaScript code. Also, you will gain access to many of the device’s native features such as the compass, camera, the contacts list, accelerometer, etc.

PhoneGap introduced last year PhoneGap Build which offers a cloud-based service that takes your app written in HTML5, CSSe and Javascript and sends you back app-store ready apps for iOS, Android, Palm, Symbian and the other mobile platforms. Check out pricing and other details on their web site.

Below is a general process involved in getting setup using PhoneGap and developing an application:

1. PhoneGap has a great Getting Started tutorial for all the mobile platforms. Download the PhoneGap tools and the specific set of tools for the platforms you’re working with. For example, download Xcode and iOS SDK if you plan on porting your web site to an iOS application. Download the Android SDK and Eclipse if you plan on making an Android application.

2. Install all the platform tools and PhoneGap to your existing environment.

3. Start developing your web application and test with a web browser of your choice. I normally use Visual Studio to write my web application and test it using Safari, Chrome or any webkit supported browser. Since these are the types of browsers on smartphones. I would take advantage of Visual Studio’s IDE in debugging my javascript code or Web Inspector in Safari or the dev tools found in FireFox or Chrome.

4. Once you’re ready to port it to a mobile application, you will put all your web files within the www folder. For Xcode, all you need to do is create a new project using the PhoneGap template. Once the project is created, immediately compile the project. Once the project is done building, a www folder will be created in your project folder. Add the www folder into the project navigator. This is where you will house all your web files (HTML5, CSS3 and Javascript files). Run your project and you should see your web page displayed in the iPhone or iPad simulator.

5. For Android, install Android SDK, Eclipse and then the Android plug-in for Eclipse. Create an Android project in Eclipse and follow these steps to modify the project to support PhoneGap. Then run the project and select an Android Virtual Device (AVD) to use as the emulator to display your application.

6. Steps 4 and 5 can be done for you using PhoneGap Build. Just upload your web application files using their Cloud service and they will send you back app-store ready packaged files for the mobile platforms they support.

7. A noteworthy caveat is you will have to tweak some of your web language code depending on which mobile platform you choose. Not all mobile devices are similar in hardware but PhoneGap does an excellent job in pointing out issues through their API Docs section on their web site.

For step 5, here are some links to great tutorials on how to Get Started in developing for Android:
1. Getting Started With Android Development Using Eclipse
2. Getting Started with Android on a Mac
3. Running Android SDK Examples Using Eclipse

So below is a web page example written only in HTML5, CSS3 and Javascript. The HTML consists of an input element and a button. Using JavaScript, it dynamically shows in an unordered list the input values you submit. If you click any of the list items in the unordered list, it will make a call using the Twitter Search API and return the latest tweet with that keyword as an input parameter.

HTML elements:

- (void) prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    <body>
	<div id="main">
        <h1>Search Twitter</h1>
        <form id="foodForm">
            <input type="text" id="foodName" placeholder="keyword" />
            <button id="submitFood">Tell Us!</button><br>
        </form>
        <ul id="foodList">
        </ul>
        </div>
   </body>
}

JavaScript code event handler when DOM is loaded:

- (void) prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    document.addEventListener("DOMContentLoaded", function () {
            //navigator.notification.alert("I think today will be a great day.", function() {}, "Great Day");
            // uncomment below code to clear items in LocalStorage
            //window.localStorage.clear();
            // <ul> instance variable
            var foodList = document.getElementById('foodList');
            // textbox instance variable
            var foodField = document.getElementById('foodName');

            // length of food items in localStorage
            var l = window.localStorage.length;
            var i = 0;
            var storedFoodName;


            // add food item to <li> child
            function addNewFoodItem(foodName) {
                var newFoodItem = document.createElement('li');
                newFoodItem.innerHTML = foodName;
                foodList.appendChild(newFoodItem);
            }

            // loops through localStorage for food items and calls addNewFoodItem function
            for (i; i < l; i++) {
                storedFoodName = window.localStorage.key(i);
                if (storedFoodName.match(/^food[.]/))
                    addNewFoodItem(window.localStorage.getItem(storedFoodName));
            }
}

Javascript code that gets handled when the button is clicked:

document.getElementById('foodForm').addEventListener('submit', function (evt) {
                evt.preventDefault();
                var newFood = foodField.value;

                // creates a foodKey value with food.[length]
                var foodKey = "food." + (window.localStorage.length + 1);
                // calls addNewFoodItem function
                addNewFoodItem(newFood);
                // saves foodKey and input food to localStorage
                window.localStorage.setItem(foodKey, newFood);

                // clears foodFied variable
                foodField.value = "";
                return false;

            }, false);
        });

Javascript code that calls the Twitter Search API remote service using the XMLHttpRequest object and parses the JSON data returned. It displays the latest tweet in a notification alert after you click on the ListItem in the unordered list.

// callback function to get the latest tweet
        function getLatestResult(JSONstring) {
            var twitterPayload = JSON.parse(JSONstring);
            var latestResult = twitterPayload.results[0];

            return latestResult;
        }

        // performs a get request for url
        // passes the response text to callback
        function getXHR(url, callback) {
            var req = new XMLHttpRequest();
            req.onreadystatechange = function () {
                if (this.readyState == 4) {
                    if (this.status == 200 || this.status == 0) {
                        callback(this.responseText);
                    } else {
                        console.log('something went wrong');
                    }
                }
            }
            req.open('GET', url, true);
            req.send();
        }

        // event handler for the clicks on <li> elements using event delegation to catch all of these events.
        // We listen on the document element, and then, if the target of the event matches one of our list items, 
        // fires the event handler
        document.addEventListener("click", function (evt) {
            if (evt.target.tagName == 'LI') {
                // gets the selected <li> element
                var foodSubject = evt.target.innerHTML;
                var foodSearch = encodeURIComponent(foodSubject);
                // generates twitterURL for Twitter Search API
                var twitterUrl = 'http://search.twitter.com/search.json?q=' + foodSearch;

                // calls getXHR function to get latest tweet of selected <li> element 
                // then calls callback function to pop-up an alert msg with latest tweet
                getXHR(twitterUrl, function (response) {
                    var latestTweet = getLatestResult(response);
                    var msg = 'Latest Tweet about ' + foodSubject + ' from ' + latestTweet.from_user + ': ' + latestTweet.text;
                    //navigator.notification.alert("PhoneGap is working")
                    alert(msg);
                })
            }

        }, false);

Project Navigator in Xcode

Project Navigator in Xcode for PhoneGap project

iPhone Simulator of Search Twitter

iPhone emulator of PhoneGap application

Project Explorer in Eclipse

Project Explorer of Android project in Eclipse. Notice the /assets/www folder and /libs folder with PhoneGap related web files

Android Virtual Device

Android Virtual Device running the web page

PhoneGap is good at helping developers leverage their experience at building web applications using web standards, HTML, CSS and JavaScript. If you know web standards, you’ll experience few problems while working with PhoneGap. All you need to learn is how to use the PhoneGap API. Once you become familiar with the PhoneGap API, you can quickly take advantage of accessing the device’s camera, pull up the contacts or work with the accelerometer or compass.

As the web site example above shows, if you need to connect your application with a remote web service, you can easily bring in tools like jQuery to create powerful Ajax handlers. Or as I demonstrate in how to use XmlHttpRequest objects.

As I pointed out in step 7 above, just because you code a web application using PhoneGap and it works on an iPhone device, it doesn’t automatically mean that it will work on other devices. You will have to test and tweak for the other devices that are supported.

If you want to port to multiple devices, you will need separate environments for each wrapper. For example, you won’t be able to maintain your Android PhoneGap wrapper with Xcode. I used my Mac and have installed Xcode and Eclipse but I make sure I keep them in separate environments.

PhoneGap, Appcelerator and mobile web frameworks

What are mobile web frameworks

What are web based application frameworks? First, there are many out there including PhoneGap, Appcelerator, etc. For developers struggling to learn Objective-C, Java, etc these frameworks allow you to still build mobile applications. Essentially, these frameworks exist to help developers that come from a web development background with a set of tools to use with their current skillset (HTML, CSS and Javascript) to build native or native-like mobile applications. PhoneGap and Appcelerator Titanium are the most popular amongst all the frameworks out there on the interweb. For this blog post, I want to compare and contrast the two along with other mobile frameworks. Hopefully this will help you if you’re deciding on which framework to architect your next project.

PhoneGap is developed by Nitobi Software which was recently acquired by Adobe. On their website, it says “Build apps in HTML and Javascript and still take advantage of core features in iPhone/iPod touch, iPad, Google Android, Palm, Symbian and Blackberry SDKs.” Currently, PhoneGap v1.3 supports 7 different platforms including iOS, Android, Palm, WebOS, WP7, Symbian and Bada. The framework is open source which means developers and companies can use PhoneGap for mobile applications that are free, commercial, open source, or any combination of these.

What is required to use PhoneGap

PhoneGap projects require the underlying SDKs (e.g. iOS 5 SDK) to be installed and building the project happens from an IDE, such as Xcode 4. Once you have Xcode and iOS 5 SDK installed, download PhoneGap and install it. Open up Xcode and under the New Project dialog, there should be a PhoneGap-based Application project template as shown in Figure 1.

New Project Dialog

Figure 1

After installing the PhoneGap project template, make sure to build and launch the iPhone simulator. You should see an error in your simulator informing your “index.html” was not found as shown in Figure 2.

iPhone Simulator Error

Figure 2

In order to fix this, go ahead and copy the ‘www’ directory to the Project Navigator in Xcode. The ‘www’ folder exists in the PhoneGap project folder location. You can quickly go to that folder by right-clicking on the project root in Project Navigator and selecting “Show In Finder”. After you drag the ‘www’ folder, you should see a prompt as shown in Figure 3. Select “Create folder references for any added folders” and click Finish.

Folder Reference

Figure 3

Your Project Navigator should look similar to Figure 4.

Project Navigator

Figure 4

Now rebuilt and run the iPhone simulator again and you should see similar to Figure 5

iPhone Simulator

Figure 5

Basically, the developer puts his files (HTML, CSS or Javascript) into a ‘www’ folder in the project directory. When building, PhoneGap then renders these files inside a native WebView provided by the OS-specific language (either Objective-C or Java), it exposes access to certain native device features, like Accelerometer, Camera, Notifications, etc.

In a nutshell, a PhoneGap application is essentially still a web application, wrapped inside a WebView. It still remains a web application that is displayed through rendering of HTML, CSS and Javascript using a browser instance on a mobile device.

Appcelerator Titanium

Appcelerator Titanium is another mobile framework to help developers build mobile applications but only on iOS and Android at this time. Similar to PhoneGap, Titanium provides a binding layer that maps Javascript function calls to natively available APIs.

However, Appcelerator claims to be different than PhoneGap in translating Javascript code to native application code. The Javascript code is being interpreted during runtime and through a bridge layer, function calls to Titanium.some_function invoke native application code under the hood.

Another way Appcelerator is different is up until the latest version of Appcelerator, v1.5, you would write your application code in HTML, CSS and Javascript. Now, the application code is written in pure Javascript, using mainly functions that the Titanium API exposes. Apart from using it to access special device features (Camera, Accelerometer, etc), it also enables the developer to render native UI elements (buttons, tables, etc).

These differences give Appcelerator an edge of performance. Just want to emphasize, all the application code will be in Javascript, even the styling of elements happens through function calls. One thing to also keep in mind is to ask yourself will the Javascript API provide all the functionality needed in your application.

Unlike PhoneGap, building and packaging your application does not happen inside an IDE (Xcode, Eclipse, etc), but through their software, Titanium Developer. This is the tool to set up new projects, configure, test and package them. Any IDE of your choice can be used to write the application code.

When choosing a mobile web framework, keep in mind it depends on the requirements of the application when choosing which framework to go with. If the goal is to target many platforms as possible, then PhoneGap may be the right choice. If true native-ness and performance is important, then Titanium may be the choice.

There are many other mobile web frameworks out there that are open source and free and some that charge a developers license fee. I would like to write a follow up blog post on MonoTouch, NimbleKit, AppMobie and others. Stay tuned.

Tip: Using zoom to target images to high density displays

I found this several days ago when I was looking for a way to scale images on an iPhone inside of a fluid layout such that they would display at a 1:1 pixel ratio. If you didn’t already know, the iPhone 4 and 4S displays everything as if the screen was the same size as a normal iPhone when it measures and does the layout. The result is that all the text looks extremely crisp, and any sites already designed for the original iPhone don’t break or look weird. With images this means that a 300 x 300 pixel image displays the correct size in the layout, but is essentially scaled up to fit over 600×600 “physical pixels”. As I was poking around I found an old CSS zoom property here: http://reference.sitepoint.com/css/zoom that for some reason works on mobile safari. Add a media query for 2x density screens, and viola! Your images now display at physical pixel dimensions on the iPhone 4 and 4S.

Here’s what the CSS looks like:

@media screen and (-webkit-min-device-pixel-ratio: 2) {
     img {
          zoom: 50%;
     }
}

Awesome hacks.

Happy img scaling.

On Modern Layouts and Semi Fluid Grids

Over the last several weeks, I’ve really been digging into HTML5, CSS3, and really figuring out what modern browsers can do. Frankly browsers have grown by leaps and bounds over the last several years, and as such we need to re-evaluate how we build websites. Especially in regards to how we treat older browsers. I recently read this post by Paul Irish and he points out that ideally, each browser gets an experience that is customized to that browser’s capabilities. What this means however, is that we should expect older browsers to get an experience that isn’t exactly the same as the experience we get on a modern one. (Example, no rounded corners. No text shadows. Etc…)

Let me try to explain:

A really good analogy to this is how HD TVs have changed the TV industry. Imagine for a moment that a website site is the film, and the TV is your browser. If you had a black and white TV, you wouldn’t expect to see the film in color. If you have a standard definition TV you don’t expect to see the full wide screen movies, and if you have a widescreen 720p TV, you don’t expect to experience the full effect of 1080p Blu-ray. Filmmakers don’t shoot in standard definition and then try to ‘upgrade’ the film to HD quality. Its pointless and a LOT of extra work. No, they shoot with the best film and resolution they can afford and then cut it down to the lower denominators when or if they support older formats.

In the same way, if you use an older browser you wouldn’t expect to get the full experience a modern browser supplies, and moreover, you likely wouldn’t even know what your missing! You don’t expect it since any other site you visit also doesn’t have those features or details. Because of this, you should be designing for the ‘1080p’ of the web, and accept that users with older browsers will still get the ‘standard definition’ experience.

The Web Is Not Print

There’s also an important distinction between print and the web. The web is dynamic and fluid, highly interactive. The web is also delivered on a range of sizes and devices, from something the size of a business card up to large 30″ monitors. There comes a point where form and function have to merge in a non-trivial way to provide an experience that fits itself to the users needs, when they need it, the way they need it.

Print isn’t.

Print is extremely static, once it’s designed, it stays that way. If you design a poster, you design it to be printed at a certain size or at certain proportions. If you design a book or a magazine, you have total control over the size and layout of your spread. If you continue to think about the web this way, you’ll miss much of the dynamic nature of the web that makes it attractive as a medium.

Its only recently we’ve really gained the tools and techniques we need to REALLY break out and away from the classic printers layout due largely to the rise in mobile devices, HTML5 and CSS3. What I’m calling this “Print Format” tends to reveal itself at the extreme edge cases.

Specifically:

  • On large monitors where content will appear tiny and hard to read with lots of extra white space.
  • On small monitors or mobile devices when the content doesn’t scale down and your forced to scroll back and forth to read.

Over the years one of the only real solutions to address this, if someone addressed it at all, was just to never set a width for your content and just let it fill your entire screen. Although this almost works for some things, it’s difficult to read as paragraphs will stretch across the screen. You will constantly lose your place as your eyes track back and forth to the beginning of the next line. Also, if your designing a static site and you and your designers both have large screens, it’s easy to ‘fill up the space’ with ancillary or useless content and ads to make the site feel balanced. All in all, most so called solutions were hacks on a broken system.

Semi Fluid Layout

I’m finally starting to see some CSS frameworks and sites that are really starting to apply these principles. An excellent site that demonstrates this principle is the following:

www.goldengridsystem.com

No matter what browser you visit it on, or what size your browser is at, the content will be sized appropriately, the typography will be readable, and everything will feel right. Sans insane urges to resize your browser window.

One of the key benefits to designing a fluid theme is the instantly correct look you get when you open the site. Its not something people will or should consciously expect, it should simply BE the correct size the instant it appears, regardless of size, screen, or orientation. Its like walking into a store. A well designed building is easy to navigate, spacious, and consistent across all other stores you visit regardless of size. You don’t ever think about it, you’re not there to analyze the layout of the store. You’re there to buy groceries. Anything that gets in the way or makes it hard to find what you’re looking for will stick out, and if it’s bad enough, you’ll go somewhere else. Its the same way with a site or blog. Users are there for a reason: For information, or to read, or to consume whatever content you are serving up. They didn’t come to analyze your site and how it’s designed, but if they have any difficulty at all in getting to what they want in whatever form they want it in, they’ll be somewhere else in about 8 seconds.

It’s also important to be intentional about the decisions your making and how they will affect the final layout of a site. The more you reduce the complexity of the interactions, and the better defined the interactions are, the better the final end result will be. Use what you design. Do what your users do. You’ll know best what you do and don’t like and what feels right. Go with it, but don’t be afraid to stop, backtrack, or even completely scrap good ideas if they don’t fit with what you expect from the design.

Fluid Layout First

Something that’s going to become really important is to start out your design efforts knowing your designing for a fluid site like this. Laying out the groundwork and page structure is going to be extremely important to your long term sanity as a developer. There’s this concept in computer science called emergent behavior, essentially, the less you specify about a system, and by imposing fairly simple rules you can get easily get complex behavior. By starting with the containers, and then working your way to the content I have much less to worry about since most of the content takes care of itself without much more intervention from the developer.

If your someone who already has a well established, static width layout, its going to be difficult to establish a well behaved fluid grid system without tweaking MANY aspects of the site. Its probably why a lot of companies simply serve up an entirely different set of HTML and CSS for the site for mobile devices: Its easier to do than to rebuild their main site to scale all the way down to small screens.