Introduction

Mobile web usage is growing exponentially. As more people become comfortable with smartphones, or other mobile devices, to browse the web, there's an increasing need for mobile-optimized websites and web applications. With the growing number of platforms (iOS, Android, Blackberry OS, webOS, Windows Phone, Symbian, Bada, and so on), it's difficult to develop native applications that target more than one mobile operating system.

There has been a surge in demand for mobile web application development toolkits. A few of the major JavaScript frameworks—Dojo, jQuery, and Sencha—have been quick to provide fully touch-aware frameworks. When coupled with native compilation toolkits like PhoneGap, these frameworks offer an excellent alternative to native development. Web developers can build native applications using the languages and frameworks they already know, and can deploy to numerous platforms with relative ease.

In this article, you will learn about Dojo Mobile, which is an extension of the Dojo Toolkit. After exploring the differences between mobile web and native applications, you'll follow an example that shows you how to include and use Dojo Mobile widgets in your applications. You'll also learn about building native applications with PhoneGap. You can download the source code used in this article.

Back to top

Mobile web versus native applications

The debate about developing a mobile application using native versus web platforms will likely continue for a good while. Each approach has advantages and disadvantages. In many cases, application requirements and personal preferences determine the approach you should choose.

Why would you write a native application instead of using the mobile web? Table 1 outlines some advantages and disadvantages of writing native applications.

Table 2 outlines the advantages and disadvantages of mobile web applications.

Fortunately, there's a middle-ground if you want to take the best of both the mobile web and native approaches. Using a platform such as PhoneGap will take your mobile web application and surround it with a native wrapper, providing JavaScript APIs that let you access the native device APIs. You can also deploy your web application as a native application to the various application stores. This is covered in more detail in Native deployment with PhoneGap.

Back to top

Dojo Mobile at a glance

Dojo Mobile, an extension for the Dojo Toolkit, provides a series of widgets, or components, optimized for use on a mobile device, such as a smartphone or tablet. The components are modeled on their native counterparts, and will look and feel native to those familiar with smartphone applications. The components are completely customizable using themes which, for example, let you push a different set of styles to iOS users than to Android users.

Dojo Mobile works similarly to the Dijit library of components. To use a particular type of widget in your application, you first load the relevant class using dojo.require in your application's main JavaScript block. You can then add the widget to your application either declaratively using regular HTML tags with the dojoType attribute, or programmatically using JavaScript code.

As you might expect, Dojo Mobile works great on iOS, Android, and BlackBerry OS 6 devices, largely due to the WebKit browsers available on these platforms. The advantage also carries over to other platforms that offer a decent WebKit browser, such as HP webOS and various others. Dojo Mobile applications degrade gracefully on non-WebKit browsers, and can even be run in older desktop browsers (including Microsoft® Internet Explorer). By default, only CSS3 styling is included, but a compatibility module can be added for non-WebKit browsers using a single line of code:

dojo.requireIf(!dojo.isWebKit, "dojox.mobile.compat");

Some key features of Dojo Mobile include:

• Lightweight loading of widgets due to the Dojo Mobile parser
• CSS3 animations and transitions for native-like application experience on high-end iOS and Android devices
• Themes included for iOS, Android, and BlackBerry look-and-feels.
• Compatibility with non-CSS3-compatible devices and browsers
• Full declarative syntax allows for easy learning curve
• A large suite of UI widgets and components, providing a wide variety of options for mobile-friendly interfaces

The next section explains how to get started with Dojo Mobile by building a "Hello, World" application.

Back to top

Getting started with Dojo Mobile 1.7

At the time of this writing, the latest stable version of Dojo available is 1.6.1. To start using Dojo Mobile 1.7 at this time, you'll need to download the latest nightly release of the Dojo Toolkit from a Subversion repository. The svn command-line tools are usually pre-installed on the Mac OS X and Linux® operating systems. If you're using Windows®, you'll likely need to download and install these first. For more information, visit the Subversion site.

Assuming you have Subversion installed, and are using the command-line-based tools, you can checkout the latest nightly version of Dojo using the following command. The command downloads the entire Dojo Toolkit source code, so you can expect it to take some time.

$ svn checkout http://svn.dojotoolkit.org/src/view/anon/all/trunk dojo-toolkit-readonly

When the checkout is complete, you'll have the entire source code of the Dojo Toolkit in a new directory named dojo-toolkit-readonly. Copy or move this directory into a location on your web server where you'll be able to use it in your HTML documents. Rename it to something shorter, such as dojo-toolkit, and you're ready to start working with Dojo.

If you prefer, you can download only the parts of the Dojo Toolkit you want. Some find it easier to download the entire thing first and then discard what you don't need. The source code for Dojo is uncompressed and not minified, so it's not recommended for use in production applications. See Resources for information on creating your own custom Dojo builds to boost the performance of your Dojo applications.

The basic structure of a Dojo application is outlined in Listing 1. New in Dojo Mobile 1.7 is the deviceTheme class, which will automatically determine the correct theme to load for the device you are using. You do not have to detect the user's browser and serve the relevant CSS file.

<!doctype html>
<html>
    <head>
        <meta name="viewport" content="width=device-width,initial-scale=1
,maximum-scale=1,minimum-scale=1,user-scalable=no">
        <meta name="apple-mobie-web-app-capable" content="yes">
        <title>My Dojo Mobile App</title>
        <script src="dojo-toolkit/dojo/dojo.js" djConfig="parseOnLoad:
true"></script>
        <script>
            dojo.require("dojox.mobile.parser");
            dojo.require("dojox.mobile");
            dojo.require("dojox.mobile.compat");
                dojo.require("dojox.mobile.deviceTheme");
        </script>
    </head>
    <body>
        <!-- Dojo Widgets Go Here -->
    </body>
</html>

If you save the code in Listing 1 in a file and open that file in your web browser, you should see a grey background with no content. This is hardly useful, so let's go ahead and add some content to the application. The example in this article uses non-standard Dojo Mobile classes, so you need to load them manually using dojo.require. After the line dojo.require("dojox.mobile");, add the lines shown in Listing 2.

dojo.require("dojox.mobile.ScrollableView");
dojo.require("dojox.mobile.SwapView");
dojo.require("dojox.mobile.IconContainer");
dojo.require("dojox.mobile.Button");
dojo.require("dojox.mobile.SpinWheelDatePicker");
dojo.require("dojox.mobile.SpinWheelTimePicker");

Now you can add the main code for the "Hello World" application. The examples in this article use the declarative syntax for Dojo Mobile, which means using regular HTML tags with special Dojo Mobile attributes that will be parsed at runtime. In the <body> section of your code, add the code from Listing 3.

<div dojoType="dojox.mobile.ScrollableView" selected="true">
    <h1 dojoType="dojox.mobile.Heading" fixed="top">Hello, World!</h1>
    <h2 dojoType="dojox.mobile.RoundRectCategory">First Section</h2>
    <div dojoType="dojox.mobile.RoundRect">
        This is a nice standard rounded rectangular label.
    </div>
    <h2 dojoType="dojox.mobile.RoundRectCategory">Second Section</h2>
    <ul dojoType="dojox.mobile.RoundRectList">
        <li dojoType="dojox.mobile.ListItem">List Item 1</li>
        <li dojoType="dojox.mobile.ListItem">List Item 2</li>
        <li dojoType="dojox.mobile.ListItem">List Item 3</li>
        <li dojoType="dojox.mobile.ListItem">List Item 4</li>
        <li dojoType="dojox.mobile.ListItem">List Item 5</li>
    </ul>
</div>

The code above defines a ScrollableView that will comprise the main application interface. The difference between a standard View class and the ScrollableView class is that the standard View will use standard browser chrome to scroll the page. The ScrollableView class has its own scrolling mechanism, which lets you fix a header and footer in your application, and scroll the content between them, like you might expect from a native application.

Inside the ScrollableView is a Heading, which is the title bar containing the text "Hello, World." By setting the attributed fixed="top" on this object, Dojo Mobile will keep the heading in place at the top of the screen and scroll the other content beneath it. The RoundRectCategory object defines a group heading for a rounded list or single item. The first of these categories is followed by a single RoundRect box with some static text in it. This is followed by another category heading and a RoundRectList object, which in turn contains a series of ListItem objects. The end result should look something like Figure 1.

The next section explores the various widgets and components available in Dojo Mobile 1.7.

Back to top

Widgets

Dojo Mobile comes with a wide variety of widgets that are specifically designed and optimized for mobile devices. The widgets range from layout components (views) to lists, navigation bars, tab bars, buttons, and form widgets. This section shows many of the widgets in action, and includes basic code examples. Figures of screens in this section were taken on an iOS device using the iPhone theme; they will vary if you're using the Android theme.

View

View is a container widget that takes up all of the available space on the device's screen. Your application's pages may contain more than one View object, but only one of these will ever be active at any given time. The user can typically navigate between different views using toolbar buttons and tab bar buttons, with various transitions available for moving between each view. Figure 2 shows an example of an empty View.

To create a View object, use the dojox.mobile.View class that's included in the Dojo base SDK. It does not need to be explicitly loaded using dojo.require. When using a View object you use the selected attribute to define whether the view should be displayed when the application is launched (the startup view). The following code is required to create the above View declaratively.

<div dojoType="dojox.mobile.View" selected="true"></div>

Alternatively, you could create the View programmatically using JavaScript. Listing 4 shows the code for creating the View in Figure 2 using this method.

var myView = new dojox.mobile.View({
    selected: true
}, "myView");
myView.startup();

Listing 4 assumes you have a block element somewhere in your HTML with the id attribute value myView. It then binds a View object to this element in the DOM.

The rest of the widget descriptions include how to use them only declaratively. Consult the Dojo API for more information on how to use Dojo Mobile widgets with the programmatic syntax.

ScrollableView

The ScrollableView widget works similarly to the View widget: it acts as a container in which you can place other widgets. The primary difference is that with ScrollableView, if your content overflows the height of the screen the user can scroll the content by touching the screen and moving their finger up or down (or left or right if you use horizontal scrolling), while keeping any header or footer objects in place. If you were to use a standard View object, the entire screen would scroll, so the header and footer would not stay in a fixed position. Figure 3 shows an example.

Creating the empty ScrollableView object above is very similar to how you created the empty View object in Figure 2. The code for the empty ScrollableView is:

<div dojoType="dojox.mobile.ScrollableView" selected="true"></div>

It is recommended that you use ScrollableView only if you intend to add a fixed header or footer to your view. Otherwise, you should use the regular View class.

Unlike the regular View class, ScrollableView is not included in the base classes so it needs to be explicitly loaded using dojo.require.

SwapView (previously FlippableView)

The SwapView widget is the previously-named FlippableView, which is deprecated in Dojo Mobile 1.7. SwapView lets you create a container object that can be swapped with other SwapView objects by swiping the screen left or right. The order of the views will depend on the order in which they are located in the code. Figure 4 shows a SwapView widget.

If you wanted to create a sample FlippableView with two views, you could use the code in Listing 5. Change FlippableView to SwapView if you are using Dojo 1.7.

<div dojoType="dojox.mobile.SwapView" selected="true">View 1</div>
<div dojoType="dojox.mobile.SwapView">View 2</div>

SwapView is not included in the base classes, so it needs to be loaded manually using dojo.require.

Heading

The Heading widget lets you create a navigation bar that will appear at the very top of your application. Heading objects usually have a title. You can also add navigational elements to them, such as Back buttons or toolbar buttons, to provide an easy means of navigating around your application.

If you use a Heading in conjunction with a ScrollableView container, the Heading widget will stay fixed at the top of the application while the rest of the application will scroll. You can keep your navigation available to users at all times. Figure 5 shows an example of a Heading object complete with a title, Back button, and toolbar button.

Listing 6 shows the code to create the Heading widget in Figure 5.

<h1 dojoType="dojox.mobile.Heading" label="My App" back="Back"   
  moveTo="back">
    <div dojoType="dojox.mobile.ToolBarButton" label="Edit"
      class="mblColorBlue" style="width:25px;float:right">
    </div>
</h1>

You might have noticed that the Back button is actually defined in the Heading element itself. The back attribute defines the text that should be displayed in the button. The moveTo attribute should contain the ID of the View object that should become active when the user taps the Back button. You could also use a transition attribute to define the transition effect that should be used when navigating to another view in this way. The default is slide, but other options include fade, flip, and none.

You can define additional navigation buttons using ToolBarButton widgets. If you wanted a button that was not styled like a Back button on the left, or if you wanted to display a button on the right, you simply add a ToolBarButton object inside the Heading element.

RoundRect

The RoundRect class lets you create a simple rounded-corner container in which you can place static HTML or other Dojo Mobile widgets. An example of the RoundRect widget is shown in Figure 6.

To create the RoundRect object in Figure 6 you can use the syntax shown in Listing 7.

<div dojoType="dojox.mobile.RoundRect" shadow="true">
    This is a simple RoundRect object with some content in it.
</div>

The RoundRect class is very straightforward. It accepts a single property, shadow, which is set to false by default. This property simply defines whether the container should have a drop shadow.

RoundRectCategory and RoundRectList

When presenting data on a mobile device, lists are very important. The vertical tabular structures let you present a series of different list items. The items can be used to display information, for navigation purposes, or various other uses. Dojo Mobile lets you create two types of lists, both of which have an associated category widget. The RoundRectList creates a list that has a gap on either side of it, with rounded corners on the first and last list item. Figure 7 shows a RoundRectCategory and RoundRectList as viewed on an iPhone.

The example defined a RoundRectCategory with the label "List Heading", and a RoundRectList object with three ListItem objects within it. Listing 8 shows the code required to create this set of widgets.

<h2 dojoType="dojox.mobile.RoundRectCategory">List Heading</h2>
<ul dojoType="dojox.mobile.RoundRectList">
    <li dojoType="dojox.mobile.ListItem">List Item 1</li>
    <li dojoType="dojox.mobile.ListItem">List Item 2</li>
    <li dojoType="dojox.mobile.ListItem">List Item 3</li>
</ul>

EdgeToEdgeCategory and EdgeToEdgeList

EdgeToEdgeList is RoundRectList's close sibling. EdgeToEdgeList can be used in virtually the exact same manner, but instead it creates lists that run the entire width of the View. Figure 8 shows an example.

The code for EdgeToEdgeList is almost identical to the previous example, except references to RoundRect are replaced with EdgeToEdge, as shown in Listing 9.

<h2 dojoType="dojox.mobile.EdgeToEdgeCategory">List Heading</h2>
<ul dojoType="dojox.mobile.EdgeToEdgeList">
    <li dojoType="dojox.mobile.ListItem">List Item 1</li>
    <li dojoType="dojox.mobile.ListItem">List Item 2</li>
    <li dojoType="dojox.mobile.ListItem">List Item 3</li>
</ul>

The lists above are typically used when displaying lists of people, and the people would generally be grouped by the first letter of their surname.

IconContainer

The IconContainer widget lets you define a series of icons that can each open a separate container when tapped. IconItem objects can either slide out a container that is nested inside of the IconItem itself (on the same view), or it can actually move the active View to the one with a given ID. Figure 9 shows an IconContainer with three icons.

To create the IconContainer above, use the code in Listing 10.

<ul dojoType="dojox.mobile.IconContainer">
    <li dojoType="dojox.mobile.IconItem" label="Icon 1" 
      icon="appicon.png" moveTo="view1"></li>
    <li dojoType="dojox.mobile.IconItem" label="Icon 2" 
      icon="appicon.png" moveTo="view2"></li>
    <li dojoType="dojox.mobile.IconItem" label="Icon 3"     
      icon="appicon.png" moveTo="view3"></li>
</ul>

The IconContainer class itself is not included in _base.js, so you must explicitly load it with dojo.require. The same does not hold true for IconItem, however, so do not try to load it manually or you'll get errors when you try to run your application.

There are many more details to these particular widgets, but they are outside the scope of this article. See Resources for links to more extensive coverage in the Dojo Mobile Showcase and API.

Button

The Button class lets you create a simple button object. You can then create code to handle events such as "click" on this widget using dojo.connect. Figure 10 shows an example of a Button.

The code to create this button is as straightforward as the button itself, as shown in Listing 11.

<button dojoType="dojox.mobile.Button" class="mblBlueButton" 
style="width: 100px">Click me!</button>

You can create new button styles of your own using CSS and assigning a class name to the button using the class attribute. If you have used Dojo Mobile 1.6, note the following changes to the Button class in version 1.7.

• It is no longer included in _base.js, so you need to explicitly load the Button class using dojo.require (as the example did earlier in this article).
• You give the button a class name using the class attribute, not the btnClass attribute, as was used previously. If you try to use btnClass in version 1.7, you may find that your buttons don't look as you expect them to.

Switch

The Switch object is a toggle control that lets you switch the value of the object between two properties. By default, these are ON or OFF. To change the value of the switch, you either tap on the value you wish to change to, or slide the switch across to the target value. Figure 11 shows an example of a Switch widget with two switches: one in the OFF position and another in the ON position.

The following code creates a Switch object.

<div dojoType="dojox.mobile.Switch" value="off"></div>

The Switch widget accepts two additional properties, leftLabel and rightLabel, which let you define the values that should be displayed in the on and off states, respectively. The labels are ON and OFF by default. When the value of the Switch has been changed, the onStateChanged event will be fired. You can bind to this event using dojo.connect.

TabBar

The TabBar widget is used to swap View objects in and out in your application by making views active or inactive when a TabBarButton is tapped. A TabBar widget can use an iconBase attribute to define an image sprite, allowing different icons to be displayed in each TabBarButton. This works well when using a TabBar as a navigation component at the bottom of your application, as shown in Figure 12.

Or, you can use the TabBar component and a barType attribute of segmentedControl. It creates a tab bar that usually works best when placed near the top of the application, beneath the main Heading widget. Figure 13 shows an example of this type of TabBar in action.

Listing 12 shows the code to create the TabBar in Figure 13.

<ul dojoType="dojox.mobile.TabBar" barType="segmentedControl">
    <li dojoType="dojox.mobile.TabBarButton" moveTo="view1" 
      selected="true">Albums</li>
    <li dojoType="dojox.mobile.TabBarButton" 
      moveTo="view2">Events</li>
</ul>

You must explicitly load the TabBar class using dojo.require or you will get some obscure error messages. You do not need to load the TabBarButton class explicitly, however.

The TabBarButton class has a variety of configuration options that let you customize the appearance of your buttons. You can specify: the position of icons, what icons should be used, transitions to use when changing views, callback functions to be fired when the transition has completed, and much more. See the Dojo API for more information.

Carousel

The Carousel widget, new in Dojo 1.7, lets you create a carousel of images that you can move through by swiping with your fingers or by using navigation control widgets. Figure 14 shows an example of the Carousel widget.

To use the Carousel component, you must define an ItemFileReadStore object with a series of image items as the store. For example, Listing 13 shows a JSON object defined in your JavaScript code block.

var json = {
    items: [
        {src:"images/pic1.jpg"},
        {src:"images/pic2.jpg"},
        {src:"images/pic3.jpg"},
        {src:"images/pic4.jpg"},
        {src:"images/pic5.jpg"},
        {src:"images/pic6.jpg"},
        {src:"images/pic7.jpg"},
        {src:"images/pic8.jpg"},
        {src:"images/pic9.jpg"},
        {src:"images/pic10.jpg"}
    ]
};

You can then define an ItemFileReadStore object, and the carousel itself, as shown in Listing 14.

<span jsId="store1" dojoType="dojo.data.ItemFileReadStore" data=
"json"></span> <div dojoType="dojox.mobile.Carousel" height="280px" 
store="store1" numVisible="1" title="Photo Gallery"></div>

The code in Listing 14 can be used to create a photo gallery Carousel, similar to the one shown in Figure 14. The numVisible attribute defines how many images are shown at any one time.

SpinWheel

The SpinWheel component is a widget that lets you select values from a wheel interface. iPhone users will be familiar with using the spinning date picker component and similar controls. The SpinWheel component can be used to create custom wheels. Or, you can use the SpinWheelDatePicker or SpinWheelTimePicker to create date and time pickers, respectively. Figure 15 shows both of the widgets.

Creating SpinWheelDatePicker and SpinWheelTimePicker is straightforward. Neither are included by default in the base framework, so you must explicitly load the relevant classes, dojox.mobile.SpinWheelDatePicker and dojox.mobile.SpinWheelTimePicker. It couldn't be simpler to actually create the pickers. The code in Listing 15 will create a date picker and a time picker with the IDs spin1 and spin2, respectively.

<div id="spin1" dojoType="dojox.mobile.SpinWheelDatePicker"></div>
<div id="spin2" dojoType="dojox.mobile.SpinWheelTimePicker"></div>

Of course, the SpinWheels aren't of much use unless you can read the value from each wheel. To get the current value of the first wheel in the date picker, simply use the slots attribute and the getValue function, as follows.

dijit.byId("spin1").slots[0].getValue()

You can use the SpinWheel and SpinWheel slot classes to create a custom theme. Wheel slots can contain text and images so they are highly customizable. For more information, see the Dojo Mobile developer tests.

Back to top

Native deployment with PhoneGap

Deploying applications over the mobile web is increasingly popular. As mobile browsers improve and HTML5 evolves, the mobile web is becoming a stronger distribution option for mobile applications. However, there are many cases where you'll want to deploy your application natively to the relevant platform application stores. Rather than develop several different applications using each platform's native SDK, you can wrap your mobile web application up in a native package using PhoneGap.

PhoneGap is an open source project that's free to use in any application, whether it is distributed under a free, commercial, open source, or hybrid license. PhoneGap itself is distributed under the MIT and BSD open source licenses. You can choose whichever best suits your situation.

PhoneGap includes SDKs for building native applications for six platforms: iOS, Android, Blackberry, webOS, Windows Mobile, and Symbian. The instructions on getting started with PhoneGap vary from platform to platform. This section shows how easy it is to deploy to iOS. See Resources to find out how to use another platform.

Let's create a really basic Dojo application that runs natively on an iOS device using PhoneGap. To build native iOS applications you need a Mac with OS X 10.6 Snow Leopard and Xcode. You can download Xcode from Apple's Developer Center or from the Mac App Store. Be sure to download the iOS SDK or you won't be able to build iOS applications.

Assuming you have Xcode and the iOS SDK installed:

1. Download the latest version of PhoneGap, which is distributed as a zip file.
2. Extract and open the iOS directory inside the file. You should see a single package named PhoneGapLibInstaller.pkg.
3. Launch the PhoneGapLibInstaller.pkg to install PhoneGap into Xcode.
4. When the installer has finished, launch Xcode and create a new project.
5. From the project type groups on the left, select PhoneGap under the User Templates group, as shown in Figure 16, then select PhoneGap-based Application on the right.
6. Click Choose, and give your project a name (the example is called "HelloNative").

In the Groups & Files section of Xcode, usually on the left side of the window, expand the "www" folder. In the folder you'll need to place the dojo-toolkit directory that was created at the beginning of this article when you checked out Dojo 1.7 from Subversion. In a production application, you would usually build a custom Dojo package and only include the required files. See Resources for more information.

You cannot remove the dijit subdirectory in Dojo 1.7 (as you could in Dojo 1.6), as there are Dijit class dependencies in the latest version. If you want to cut down the size of your application, you should create a custom Dojo build, which will ensure you do not remove any dependencies.

If you try to drag and drop the dojo-toolkit folder into the www folder, you'll find that it doesn't work. Instead, you need to open the www folder in Finder by double-clicking it and then copy the dojo-toolkit folder into the www folder. It may not show up right away in Xcode, so collapse and expand the www folder to refresh the view. With Dojo 1.7 included in PhoneGap, you can go ahead and build the application itself.

Open the index.html file. The code in the file should look like the code in Listing 16.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width; initial-scale=1.0, 
maximum-scale=1.0, user-scalable=no" />

    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    
    <!-- iPad/iPhone specific css below, add after your main css >
    <link rel="stylesheet" media="only screen and (max-device-width: 1024px)" 
href="ipad.css" type="text/css" />        
    <link rel="stylesheet" media="only screen and (max-device-width: 480px)" 
href="iphone.css" type="text/css" />        
    -->
    <!-- If you application is targeting iOS BEFORE 4.0 you MUST put json2.js 
from http://www.JSON.org/json2.js into your www directory and include it here -->
    <script type="text/javascript" charset="utf-8" src="phonegap.0.9.6.min.js">
</script>
    <script type="text/javascript" charset="utf-8">


    // If you want to prevent dragging, uncomment this section
    /*
    function preventBehavior(e) 
    { 
      e.preventDefault(); 
    };
    document.addEventListener("touchmove", preventBehavior, false);
    */
    
	/* If you are supporting your own protocol, the var invokeString will contain 
any arguments to the app launch. See http://iphonedevelopertips.com/cocoa/launching-your
-own-application-via-a-custom-url-scheme.html for more details -jm */
	/*
	function handleOpenURL(url)
	{
		// TODO: do something with the url passed in.
	}
	*/

    function onBodyLoad()
    {
        document.addEventListener("deviceready",onDeviceReady,false);
    }
    
    /* When this function is called, PhoneGap has been initialized and is ready 
to roll */
    /* If you are supporting your own protocol, the var invokeString will contain any
arguments to the app launch. See http://iphonedevelopertips.com/cocoa/launching-your-
own-application-via-a-custom-url-scheme.html for more details -jm */

    function onDeviceReady()
    {
        // do your thing!
        navigator.notification.alert("PhoneGap is working")
    }
    
    </script>
  </head>
  <body onload="onBodyLoad()">
  <h1>Hey, it's PhoneGap!</h1>
	  <p>Don't know how to get started? Check out <em><a
     href="http://github.com/phonegap/phonegap-start">PhoneGap Start</a>
     </em>  	

  </body>
</html>

At this point, you're going to build into this native application the same functions that the "Hello, World" application provided. The first step is to actually include Dojo itself. Find the following line in index.html:

<script type="text/javascript" charset="utf-8"  src="phonegap.0.9.6.js"></script>

Beneath this line, add the following lines from Listing 17.

<link rel="stylesheet"  href="dojo-toolkit/dojox/mobile/themes/iphone/iphone.css">
<script src="dojo-toolkit/dojo/dojo.js" djConfig="parseOnLoad: true"></script>

The code in Listing 17 loads Dojo's CSS and JavaScript files as required. Below this code, there should be an inline <script> block. In there, add the code in Listing 18 to load the relevant Dojo classes.

dojo.require("dojox.mobile.parser");
dojo.require("dojox.mobile");
dojo.require("dojox.mobile.ScrollableView");

The code in Listing 18 loads the Dojo mobile parser and base class, as well as the ScrollableView container widget. You don't need the compatibility layer in this case, as the target device is iOS, which definitely uses WebKit.

Find the JavaScript function onDeviceReady. Beneath the comment "do your thing!", delete the following line to ensure that you don't get an alert dialog every time you run the application:

navigator.notification.alert("PhoneGap is working")

The final code you need to add, in Listing 19, is the widgets themselves. Add the following code between the opening and closing <body> elements in index.html, removing the default code added by PhoneGap.

<div dojoType="dojox.mobile.ScrollableView" selected="true">
    <h1 dojoType="dojox.mobile.Heading" fixed="top">Hello, World!</h1>
    <h2 dojoType="dojox.mobile.RoundRectCategory">First Section</h2>
    <div dojoType="dojox.mobile.RoundRect">
        This is a nice standard rounded rectangular label.
    </div>
    <h2 dojoType="dojox.mobile.RoundRectCategory">Second Section</h2>
    <ul dojoType="dojox.mobile.RoundRectList">
        <li dojoType="dojox.mobile.ListItem">List Item 1</li>
        <li dojoType="dojox.mobile.ListItem">List Item 2</li>
        <li dojoType="dojox.mobile.ListItem">List Item 3</li>
        <li dojoType="dojox.mobile.ListItem">List Item 4</li>
        <li dojoType="dojox.mobile.ListItem">List Item 5</li>
    </ul>
</div>

Save the index.html file (File -> Save), and ensure that the Overview toolbar option in the top left of Xcode is set to a Simulator target. You can now launch the application using Build and Run (Build -> Build and Run). Xcode will do its thing for a moment before launching the iOS Simulator application. After a few moments, your first native Dojo application should start. You might notice the lack of a Safari toolbar at the bottom of the screen, and that your application is taking up the entire device screen, as shown in Figure 17.

If you exit the application by selecting Home on the simulated iPhone, your application is sitting on the device's home screen, with the default PhoneGap application icon and the name HelloNative, as shown in Figure 18.

If you open another application (such as Safari or Contacts) in the simulator, and double-tap the Home button, the iOS Multi-tasking menu will open. Once again, you'll see your application's icon displayed, allowing you to quickly and easily switch between other applications and your own.

The process for deploying to other platforms is typically as simple as outlined here, although there might be some tweaking required to get your application working on Android. All the information you need is available on the PhoneGap website. Remember to create a custom Dojo build if you plan on distributing the application, or your application binary will be much larger than it needs to be.

Back to top

Conclusion

Web applications are fast becoming a reasonable and powerful alternative to native mobile application development. In this article, you learned how mobile HTML5 frameworks such as Dojo Mobile can add value to the process, abstracting the tedious work of designing UI components and widgets specifically for mobile devices. Dojo Mobile even provides different themes for different types of devices.

After you've built your mobile web application, you can then take advantage of the fantastic PhoneGap SDKs to deploy your application natively to multiple target platforms. You can even leverage the native device features, such as the camera and microphone. The future of the mobile web is not only bright—it's already here.

Back to top

Download

Information about download methods

Resources

Learn

• Learn more about the Dojo Toolkit.
  
  
• Read about the features of Dojo Mobile.
  
  
• Access the official dojox.mobile documentation.
  
  
• Check out some Dojo Toolkit Demos.
  
  
• See the Dojo Mobile 1.7 nightly build tests.
  
  
• Go through the Dojo Mobile Showcase for loads of sample widgets.
  
  
• View a series of videos on Dojo Mobile from TNW: Developers: build mobile and web apps quicker with Dojo Mobile.
  
  
• "Comment lines: Going mobile with the Dojo Toolkit" (developerWorks, Mar 2011): Learn about using the Dojo Toolkit to target mobile platforms.
  
  
• Read the developerWorks blog entry Building mobile apps with the Dojo framework.
  
  
• "Comment lines: Mobile apps and the web" (developerWorks, Mar 2011) discusses the quickly emerging space of mobile computing, and how you can leverage emerging web standards to address your enterprise Mobile needs.
  
  
• Introducing The Dojo Toolkit is an excellent introduction to the Dojo Toolkit.
  
  
• Introduction to the Dojo toolkit, part 1: Setup, core, and widgets is another fine introduction to the Dojo toolkit.
  
  
• Dojo 1.5: Ready to power your web app explores some of the new features in Dojo 1.5.
  
  
• Introduction to the Dojo Toolkit: Tutorial is an introductory tutorial from Ajax Matters.
  
  
• "Internationalizing Web applications using Dojo" (developerWorks, Aug 2008) discusses a way to perform native language support in the context of web sites and web applications using the i18n feature of the Dojo toolkit.
  
  
• "Consuming web services with the Dojo Toolkit" (developerWorks, Sep 2010) shows you how to consume services using the Dojo Toolkit to enable Ajax on a web page.
  
  
• Dojo: Using the Dojo JavaScript Library to Build Ajax Applications, by James E. Harmon, is a complete, example-rich developer's guide to Dojo and its growing library of prepackaged widgets.
  
  
• Getting StartED with Dojo, by Kyle Hayes and Peter Higgins, gets you started with JavaScript and then right into Dojo and its toolset for building Web interfaces, effects, Widgets and more.
  
  
• "Writing a custom Dojo application" (developerWorks, Dec 2008) provides a lot more information about Dojo.
  
  
• "Develop HTML widgets with Dojo" (developerWorks, Oct 2006) explores Dojo's extensibility.
  
  
• "Using the Dojo Toolkit with WebSphere Portal" (developerWorks, Nov 2007) covers how to install, configure, use, and leverage the Dojo Toolkit in WebSphere Portal applications.
  
  
• Use the PhoneGap Get Started Guide.
  
  
• The developerWorks Web Development zone specializes in articles covering various web-based solutions.
  
  

Get products and technologies

• Download the Dojo Toolkit. Version 1.6.1 was used in this article.
  
  
• Download the latest version of PhoneGap.
  
  
• Check out the Developer Tests for Dojo Mobile.
  
  
• Access the Dojo Toolkit API documentation.
  
  
• Download the WebSphere Application Server Feature Pack for Web 2.0 and Mobile V1.1.0.
  
  
• IBM - Dojo Extension sample: The Dojo Extension Feature Set can be used to enable a IBM WebSphere Portlet Factory model to leverage functionality provided by the Dojo JavaScript Toolkit.
  
  
• Get Subversion from the project Web site.
  
  
• Try out IBM software for free. Download a trial version, log into an online trial, work with a product in a sandbox environment, or access it through the cloud. Choose from over 100 IBM product trials.
  
  

Discuss

• Create your developerWorks profile today and set up a watchlist on Dojo and mobile application development. Get connected and stay connected with developerWorks community.
  
  
• Find other developerWorks members interested in web development.
  
  
• Share what you know: Join one of our developerWorks groups focused on web topics.
  
  
• Roland Barcia talks about Web 2.0 and middleware in his blog.
  
  
• Follow developerWorks' members' shared bookmarks on web topics.
  
  
• Get answers quickly: Visit the Web 2.0 Apps forum.
  
  
• Get answers quickly: Visit the Ajax forum.
  
  

About the author

Joe Lennon is a 26-year-old software developer from Cork, Ireland. Joe is author of the forthcoming Apress book Beginning CouchDB, and has contributed several technical articles and tutorials to IBM developerWorks. In his spare time, Joe likes to play football (soccer), tinker with gadgets, and work on his Xbox 360 gamerscore. He can be contacted via his Web site at www.joelennon.ie.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Mobile web versus native applications
• Dojo Mobile at a glance
• Getting started with Dojo Mobile 1.7
• Widgets
• Native deployment with PhoneGap
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Easily build dynamic Web page capabilities with the powerful Open Source Dojo programming and WebSphere Portal.

---

• Try: Save valuable time with easily tailored WebSphere Portal out-of-the-box Internet and intranet example sites.
• Article: Use these advanced Ajax techniques to create dynamic, cooperative portlets with the Dojo toolkit and WebSphere Portal.
• Tutorial: This tutorial takes you through the steps to enable drag-and-drop functionality using WebSphere Portal.
• Buy: WebSphere Portal express

Dig deeper into Web development on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers