This tutorial is for Dojo 1.6 and may be out of date.

Up to date tutorials are available.

Getting Started with dojox.mobile

Content on the web is evolving at a rapid pace, and the path is quickly moving towards mobile devices. As with many other problems on the web, the Dojo Toolkit has the solution: dojox.mobile. dojox.mobile is a framework of controllers, CSS3-based themes, and device-like widgets that will allow you to effortlessly create intelligent, flexible, and cross-device-compatible mobile web applications. This is the introductory post in a series of posts exploring dojox.mobile. Throughout the series, we will create a powerful Twitter-based web application called TweetView. Before we can get to that, we'll need to learn about why and how to use dojox.mobile.

Introduction to dojox.mobile

dojox.mobile is the Dojo Toolkit's answer to your mobile web application needs. This collection of classes has been architected to be lightweight, flexible, and extendable. dojox.mobile has also been created to mimic the interface of iOS and Android devices so that your web application is seamless to your user. Key features of dojox.mobile include:

  • Lightweight, minimal dependencies
  • Provides CSS themes for both iOS and Android-based devices
  • Provides iOS and Android-style controls and widgets
  • Uses CSS3-based animation where possible
  • Provides a small compat resource for using JavaScript animation (with dojo.animateProperty) for clients with don't support CSS3 animations
  • Responds to both orientations as well orientation changes
  • dojox.mobile is a complete mobile widget framework -- no need to collect widgets from multiple sources

Check out a few quick examples of dojox.mobile in action:

Armed with dojox.mobile, we will now create a sample mobile web application: TweetView.

These mobile interfaces also perform well in desktop browser clients, but take the time to use your iOS and Android-powered devices to browse each test. You'll be impressed by dojox.mobile's widgets and CSS themes!

Structuring Your Mobile Page

Like any web application, it's important that the structure of the page is intelligently designed. Luckily dojox.mobile requires very little in the way of special structure. It is important, however, to include a few key pieces within the page. These pieces include:

  • The proper DOCTYPE
  • Mobile-specific META tags
  • A BODY element which will contain the views

Visit the Mobile Safari Supported Meta Tags page to learn more about what these META tags mean and the other META tags available for mobile applications.

Consider the following a template to start your mobile application with:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
	<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,minimum-scale=1,user-scalable=no"/>
	<meta name="apple-mobile-web-app-capable" content="yes" />
	<title>Your Application Name</title>
	<link href="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojox/mobile/themes/iphone/iphone.css" rel="stylesheet"></link>

	<!-- stylesheet will go here -->

	<!-- dojo/javascript will go here -->

	</head>
	<body>

	<!-- application will go here -->

	</body>
</html>

With our HTML template defined, we can now add Dojo and dojox.mobile to the page!

Adding dojox.mobile to Your Mobile Page

dojox.mobile almost seems like a simplified, specialized version of Dijit. Adding dojox.mobile to your page requires:

  • A theme: There are currently two themes: iPhone and Android
  • Dojo JS with dojox.mobile: The base classes and JavaScript to use them
  • One or more views: Views will act as "pages" of your application.

Let's set up each one of these pieces separately, discussing details about each piece as we go along.

The Theme

As previously mentioned, dojox.mobile provides two themes: iPhone and Android. The iPhone theme provides stylesheets for both the iPhone/iPod and iPad devices. A compatibility layer is included for the two iOS devices to provide maximum compatibility between the two. A special stylesheet is also available for compat when the user isn't using a WebKit-powered device. For the sake of our sample page, let's use the iPhone theme:

<link href="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojox/mobile/themes/iphone/iphone.css" rel="stylesheet" type="text/css"></link>

dojox.mobile does not do device detection to import the device's corresponding theme. It is best practice to detect the device on the server side and then write the required stylesheet to the page. The HTML used to create widgets and such is not affected by the device type.

Implementing Dojo and dojox.mobile

Including Dojo happens per the traditional SCRIPT tag:

<script src="//ajax.googleapis.com/ajax/libs/dojo/1.6.3/dojo/dojo.xd.js"
	djConfig="isDebug:true, parseOnLoad:true"></script>

dojox.mobile and the dojox.mobile parser are included via the traditional dojo.require method:

// Load the widget parser
dojo.require("dojox.mobile.parser");
// Load the base lib
dojo.require("dojox.mobile");

Remember when I mentioned that dojox.mobile is similar to Dijit? Another similarity is that dojox.mobile has its own parser to find nodes which should be widgetized. Widgets will use the same dojoType (and other custom) attributes within the markup, just like Dijit widgets do.

The last step in implementing dojox.mobile is adding a requireIf statement to ensure functional compatibility when the client is not WebKit-based (i.e. the user is looking at the site with Firefox, etc.):

// If not a WebKit-based client, load compat
dojo.requireIf(!dojo.isWebKit, "dojox.mobile.compat");

dojox.mobile will not respond to data-dojo-type and data-dojo-props attributes that are new to widget declaration in Dojo 1.6. Look forward to support for those attributes in a future release. Use dojoType and other inline attributes for the time being.

The dojox.mobile.compat resource loads additional stylesheets and JavaScript to allow dojox.mobile to use Dojo's JavaScript-based animation methods instead of relying on WebKit's advanced CSS3 animations to make widgets work.

Requiring dojox.mobile.compat is not necessary but is certainly best practice. Its functionality is not baked into dojox.mobile's base to keep dojox.mobile as compact as possible.

Now that we have our iPhone theme and dojox.mobile resources loaded, let's add some sample widgets to the page.

Creating Views and Widgets

As you've seen, there are minimal requirements to create a dojox.mobile-ready page; adding widgets to the page is no different. Before we start creating widgets, let's review a few of the widgets dojox.mobile provides:

  • View - A view is a virtual "page" within a mobile app. It scrolls to the left and right and the page can be any number of views deep.
  • ScrollingView - Allows for a header and/or footer to be anchored to the top or bottom allowing the middle content portion to be scrolled
  • Button - A simple button
  • Switch - An on/off toggling switch
  • Heading - A simple heading
  • ListItem - A basic list item
  • TabBar & TabBarButton - Tabbed content management, templated in one of two methods: Segmented Control (blue, usually on the top) or TabBar (black, usually on the bottom)
  • ...and more!

Remember that all widgets are styled to look like the device's OS (as specified by the stylesheet you provide). Also remember that you will likely want to make your icons and widgets work and look like each device you intend to support.

Now that you're acquainted with some of the widgets baked into dojox.mobile, let's create a basic view with a heading, a few list items, and a switch:

<!-- the view or "page"; select it as the "home" screen -->
<div id="settings" dojoType="dojox.mobile.View" selected="true">

	<!-- a sample heading -->
	<h1 dojoType="dojox.mobile.Heading">"Homepage" View</h1>

	<!-- a rounded rectangle list container -->
	<ul dojoType="dojox.mobile.RoundRectList">

		<!-- list item with an icon containing a switch -->
		<li dojoType="dojox.mobile.ListItem" icon="images/icon-1.png">
			Airplane Mode
			<!-- the switch -->
			<div class="mblItemSwitch" dojoType="dojox.mobile.Switch"></div>
		</li>

		<!-- list item with an icon that slides this view away and then loads another page -->
		<li dojoType="dojox.mobile.ListItem" icon="images/icon-2.png" rightText="mac">
			Wi-Fi
		</li>

		<!-- list item with an icon that slides to a view called "general" -->
		<li dojoType="dojox.mobile.ListItem" icon="images/icon-3.png" rightText="AcmePhone" moveTo="general">
			Carrier
		</li>
	</ul>
</div>

When the user taps the "Carrier" item and is shifted to the "General" view (or anywhere except the home view), an iPhone-style "back" button displays in the upper left corner by setting the "back" attribute on the subsequent view's Heading widget, so there's no need to add a "Back" button within your view.

Above we created one simple view. Of course most mobile applications will want more than one view so let's create the "general" view we reference in the sample above, as well as an "about" view:

<!-- The "General" sub-page -->
<div id="general" dojoType="dojox.mobile.View">
	<!-- a sample heading -->
	<h1 dojoType="dojox.mobile.Heading" back="Settings" moveTo="settings">General View</h1>
	<!-- a rounded rectangle list container -->
	<ul dojoType="dojox.mobile.RoundRectList">
		<li dojoType="dojox.mobile.ListItem" moveTo="about">
		About
		</li>
		<li dojoType="dojox.mobile.ListItem" rightText="2h 40m" moveTo="about">
		Usage
		</li>
	</ul>
</div>

<!-- And let's add another view "About" -->
<div id="about" dojoType="dojox.mobile.View">
	<!-- Main view heading -->
	<h1 dojoType="dojox.mobile.Heading" back="General" moveTo="general">About</h1>
	<!-- subheading -->
	<h2 dojoType="dojox.mobile.RoundRectCategory">Generic Mobile Device</h2>
	<!-- a rounded rectangle list container -->
	<ul dojoType="dojox.mobile.RoundRectList">
		<li dojoType="dojox.mobile.ListItem" rightText="AcmePhone">
		Network											   
		</li>												   
		<li dojoType="dojox.mobile.ListItem" rightText="AcmePhone">
		Line
		</li>
		<li dojoType="dojox.mobile.ListItem" rightText="1024">
		Songs
		</li>
		<li dojoType="dojox.mobile.ListItem" rightText="10">
		Videos
		</li>
	</ul>
</div>

View Demo

Note the custom attributes used within the widgets. A complete listing of custom options/attributes is available within the dojox.mobile API docs for each widget. Also note that the markup provides for search engine friendly content strategies!

Congratulations, you've just created your first dojox.mobile web application! dojox.mobile makes creating the basic elements of a mobile web application a breeze! While your mobile web application will be more complex than our sample above, it's important to note that dojox.mobile provides the basic themes, widgets, methodology for creating multi-view web applications.

dojox.mobile Resources

Here are a few more resources about dojox.mobile:

Keep Going!

Now that we've covered the basics of the using dojox.mobile, the next series of posts will focus on creating a dynamic, data-driven mobile web application called TweetView. TweetView will feature numerous dojox.mobile widgets and work with both Android and iOS-based devices. The web application will pull tweets from Twitter and format them into elegant, usable web applications.