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 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
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
- 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
- Responds to both orientations as well orientation changes
dojox.mobileis a complete mobile widget framework -- no need to collect widgets from multiple sources
Check out a few quick examples of
dojox.mobile in action:
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:
With our HTML template defined, we can now add Dojo and
dojox.mobile to the page!
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
- 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.
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 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
// 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-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.
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
- 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>
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.
Here are a few more resources about
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.