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

Up to date tutorials are available.

Getting Started with

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

Introduction to 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. 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 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
  • is a complete mobile widget framework -- no need to collect widgets from multiple sources

Check out a few quick examples of in action:

Armed with, 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'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 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:

	<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="" rel="stylesheet"></link>

	<!-- stylesheet will go here -->

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


	<!-- application will go here -->


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

Adding to Your Mobile Page almost seems like a simplified, specialized version of Dijit. Adding to your page requires:

  • A theme: There are currently two themes: iPhone and Android
  • Dojo JS with 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, 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="" rel="stylesheet" type="text/css"></link> 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

Including Dojo happens per the traditional SCRIPT tag:

<script src="//"
	djConfig="isDebug:true, parseOnLoad:true"></script> and the parser are included via the traditional dojo.require method:

// Load the widget parser
// Load the base lib

Remember when I mentioned that is similar to Dijit? Another similarity is that 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 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, ""); 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 resource loads additional stylesheets and JavaScript to allow to use Dojo's JavaScript-based animation methods instead of relying on WebKit's advanced CSS3 animations to make widgets work.

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

Now that we have our iPhone theme and 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 page; adding widgets to the page is no different. Before we start creating widgets, let's review a few of the widgets 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, 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="" selected="true">

	<!-- a sample heading -->
	<h1 dojoType="">"Homepage" View</h1>

	<!-- a rounded rectangle list container -->
	<ul dojoType="">

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

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

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

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="">
	<!-- a sample heading -->
	<h1 dojoType="" back="Settings" moveTo="settings">General View</h1>
	<!-- a rounded rectangle list container -->
	<ul dojoType="">
		<li dojoType="" moveTo="about">
		<li dojoType="" rightText="2h 40m" moveTo="about">

<!-- And let's add another view "About" -->
<div id="about" dojoType="">
	<!-- Main view heading -->
	<h1 dojoType="" back="General" moveTo="general">About</h1>
	<!-- subheading -->
	<h2 dojoType="">Generic Mobile Device</h2>
	<!-- a rounded rectangle list container -->
	<ul dojoType="">
		<li dojoType="" rightText="AcmePhone">
		<li dojoType="" rightText="AcmePhone">
		<li dojoType="" rightText="1024">
		<li dojoType="" rightText="10">

View Demo

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

Congratulations, you've just created your first web application! 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 provides the basic themes, widgets, methodology for creating multi-view web applications. Resources

Here are a few more resources about

Keep Going!

Now that we've covered the basics of the using, the next series of posts will focus on creating a dynamic, data-driven mobile web application called TweetView. TweetView will feature numerous 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.