Get started with Dojo Mobile 1.7

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

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.

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

Advantages

Disadvantages

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

Getting started with Dojo Mobile
1.7

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.

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.

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.

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.

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

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

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.

Figure 2. An empty
View object

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

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.

Figure 3. An empty
ScrollableView object

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

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

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.

Figure 5. Sample
Heading widget

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

Listing 6. Creating the Heading widget

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.

Figure 6. Using the
RoundRect container

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

Figure 7.
RoundRectList

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.

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

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

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.

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.

Figure 10. Button widget

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

Listing11. Creating the Button widget

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.

Figure 11.
Switch 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.

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.

Figure 12. TabBar with
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.

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.

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

Listing 14. Defining an ItemFileReadStore object

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.

Figure 15.
SpinWheelDatePicker and
SpinWheelTimePicker

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

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.

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:

Download the latest version of PhoneGap,
which is distributed as a zip file.

Extract and open the iOS directory inside the file. You should see a
single package named PhoneGapLibInstaller.pkg.

Launch the PhoneGapLibInstaller.pkg to install PhoneGap into Xcode.

When the installer has finished, launch Xcode and create a new
project.

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.

Click Choose, and give your project a name (the example is
called "HelloNative").

Figure 16. Creating a PhoneGap
project in Xcode

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.

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:

Listing 17. Loading Dojo's CSS and JavaScript files

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.

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

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

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.

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.

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.

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.