Learn about Dojo Mobile 1.7, the latest version of the mobile web development framework that's an extension of the Dojo toolkit. See how to download Dojo 1.7 from trunk and how to use Dojo Mobile in your applications. Explore the various widgets and components it offers, and learn how to wrap your web application up in a native application using PhoneGap.


Joe Lennon, Lead Mobile Applications Developer, Core International

Joe Lennon photoJoe 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.

developerWorks Contributing author

23 August 2011

Also available in Chinese Japanese


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.

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 1. Native applications
  • Code is faster and runs directly on the device operating system without needing an intermediary browser application.
  • Can be deployed to an application store, offering a simple and cost-effective distribution model.
  • Native SDKs have tons of features specific to the device, usually complete with detailed documentation and examples.
  • Targeting different devices requires completely separate versions of the same application due to differences in the programming languages and APIs in the various platform SDKs.
  • Deploying native applications through an application store usually requires approval from a third party, which can considerably slow down the time to market (especially if your application is rejected).
  • Pushing updates, even small incremental ones, requires that you go through an approval process, making it more difficult to deliver critical updates to users.

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

Table 2. Mobile web applications
  • Write one application to target multiple platforms. No separate applications required for different devices.
  • Applications can be deployed over the web without a third-party application store for distribution.
  • You keep all the income from your application (if you charge for it).
  • Applications distributed over the web for consumption by browsers do not have access to many device features that native applications do (camera, microphone, and so on), though this may change in the future.
  • You need to provide the infrastructure for distributing your application, which can be more difficult and expensive than using an application store.
  • Applications will never run as fast as their native counterparts, as they are rendered in a browser rather than executed by the operating system itself.

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.

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.

Getting started with Dojo Mobile 1.7

WebSphere Application Server Feature Pack for Web 2.0 and Mobile V1.1.0

The WebSphere® Application Server Feature Pack for Web 2.0 and Mobile includes: the IBM Dojo 1.7 Toolkit; new mobile and rich Internet application (RIA) building blocks; and a Dojo-based diagram component. With accompanying Rational tools, the Feature Pack greatly facilitates the creation of rich web and mobile applications. In a straightforward manner, you can take WebSphere applications developed originally for desktop browsers and easily adapt and deploy them to mobile devices.

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.

Listing 1. Basic structure of a Dojo Mobile HTML document
<!doctype html>
        <meta name="viewport" content="width=device-width,initial-scale=1
        <meta name="apple-mobie-web-app-capable" content="yes">
        <title>My Dojo Mobile App</title>
        <script src="dojo-toolkit/dojo/dojo.js" djConfig="parseOnLoad:
        <!-- Dojo Widgets Go Here -->

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.

Listing 2. Loading the Dojo Mobile classes manually

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.

Listing 3. Using Dojo Mobile widgets
<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.
    <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>

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.

Figure 1. Hello World application
Screen of an iphone with a first section with some text and a second section with a list.

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


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 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.

Figure 2. An empty View object
A gray rectangle

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.

Listing 4. Creating the View programmatically
var myView = new dojox.mobile.View({
    selected: true
}, "myView");

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.


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.

Figure 3. An empty ScrollableView object
An empty gray box with a scroll bar to the right.

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.

Figure 4. SwapView widget
A box with text and a green arrow on top of it pointing to the right.

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.

Listing 5. Creating a sample FlippableView with two views
<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.


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.

Figure 5. Sample Heading widget
Header bar with the words My App as well as back and edit buttons.

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

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

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.


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.

Figure 6. Using the RoundRect container
A frame with the text this is a simple roundrect object with some content in it.

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

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

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.

Figure 7. RoundRectList
A list heading and three list items.

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.

Listing 8. Create the RoundRectCategory and RoundRectList 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>

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.

Figure 8. EdgeToEdgeList
A list heading and three list items running the entire width of the screen.

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

Listing 9. Creating the EdgeToEdge widget
<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>

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.


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.

Figure 9. Sample IconContainer
Screen showing three boxes, each containing the 'core' logo.

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

Listing 10. Creating the IconContainer widget
<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>

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.


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.

Figure 10. Button widget
A button with the words 'click me'.

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

Listing11. Creating the Button widget
<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.


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.

Figure 11. Switch example
A Switch object example

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.


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.

Figure 12. TabBar with icons
TabBar with album and calendar icons

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.

Figure 13. TabBar with barType of segmentedControl
TabBar with Album and Events text instead of icons

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

Listing 12. Creating the TabBar widget
<ul dojoType="dojox.mobile.TabBar" barType="segmentedControl">
    <li dojoType="dojox.mobile.TabBarButton" moveTo="view1" 
    <li dojoType="dojox.mobile.TabBarButton" 

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.


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.

Figure 14. Carousel widget
An image of a fish with photo gallery written above it

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.

Listing 13. Defining a JSON object
var json = {
    items: [

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

Listing 14. Defining an ItemFileReadStore object
<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.


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.

Figure 15. SpinWheelDatePicker and SpinWheelTimePicker
Carousel widget in action -- the iphone calendar function

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.

Listing 15. Creating a date and a time picker
<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.


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.

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").
Figure 16. Creating a PhoneGap project in Xcode
Screen with three sections: 1 on the left and 2 horizontal on the right along with cancel and choose buttons.

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.

Listing 16. Default PhoneGap iOS index.html File
<!DOCTYPE html>
    <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 type="text/javascript" charset="utf-8">

    // If you want to prevent dragging, uncomment this section
    function preventBehavior(e) 
    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()
    /* 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")
  <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>


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.

Listing 17. Loading Dojo's CSS and JavaScript files
<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.

Listing 18. Loading the Dojo mobile parser

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.

Listing 19. Adding the widgets
<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.
    <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>

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.

Figure 17. Native Dojo Hello World Application
The hello world title with first section text, and list items in the second section.

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.

Figure 18. Native application icon on iPhone home screen
Native app icon on iPhone home screen

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.


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.


Article source codedojo17.source.zip37KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Web development on developerWorks

Zone=Web development
ArticleTitle=Get started with Dojo Mobile 1.7