What's new in Dojo Mobile 1.8, Part 1: New widgets

Enhance your mobile applications with these new widgets

Dojo Mobile (dojox.mobile) is a Dojo Toolkit package for creating lightweight mobile web applications. Dojo 1.8, released in August 2012, includes many new Dojo Mobile widgets, widget enhancements, and other new capabilities. This article is the first in a three-part series that explores many of those new features, with ample code examples. In Part 1, learn about the new widgets, widget-related utility classes, and modules introduced in Dojo Mobile 1.8.

Share:

Yoshiroh Kamiyama (kami@jp.ibm.com), Software Engineer, IBM

Photo of Yoshiroh KamiyamaYoshiroh Kamiyama is an Advisory Software Engineer at Yamato Software Lab (YSL), IBM Japan. He works on WebSphere Feature Pack for Web 2.0 and Mobile, and previously worked on several development projects including Mobile Mashup, Lotus iNotes, and Rational Portfolio Manager, many of which used the Dojo Toolkit. He is an original contributor of dojox.mobile and a committer to the Dojo Toolkit.



19 November 2012

Also available in Chinese Portuguese

Introduction

This series introduces the new functional features in Dojo Mobile 1.8. To get the most out of this series, you should be familiar with the Dojo Toolkit and its Asynchronous Module Definition (AMD) support.

This series doesn't cover Dojo Mobile features that are not new to version 1.8. Nor does it cover the non-functional enhancements, such as new device and OS version support; improvements to performance, accessibility, testability, and usability; and theme renewal. For details on all Dojo Mobile features, see the Resources later in this article.

Dojo Mobile 1.8 introduced many new widgets and modules that you can use for your mobile web applications. Although you might find similar widgets in the dijit or dojox packages that would work for mobile apps, the Dojo Mobile widgets are designed with limited features to make their footprint as small as possible — and they provide mobile-specific themes.

Jammed-up back-end backlog?

Sign up for a free Bluemix cloud trial and fork this sample code to quickly add authentication, push notifications, and persistent mobile data to your app.

Now you can focus on the part of the app your parents actually understand. Learn more.

This article describes the new widgets, widget-related utility classes, and modules in Dojo Mobile 1.8 and shows how to use them. Part 2 looks at new enhancements to existing features, and Part 3 shows how to use Dojo Mobile data handlers to customize external content views.


Accordion

Accordion is a container widget that can display a group of child panes in a stacked format.

Typically, dojox.mobile.Pane, dojox.mobile.Container, or dojox.mobile.ContentPane are used as child widgets, but Accordion requires no specific child widget. Accordion supports three modes for opening child panes: multiselect, fixed-height, and single-select. Accordion can have rounded corners, and it can lazy-load the content modules. Figure 1 shows the Accordion widget in action:

Figure 1. Accordion widget
Screenshot of an Accordion widget

Multiselect mode

By default, multiple panes in Accordion can be opened simultaneously. Listing 1 instantiates Accordion in multiselect mode:

Listing 1. Accordion in multiselect mode
<div data-dojo-type="dojox.mobile.Accordion">
  ...
</div>

In multiselect mode, the height of the Accordion grows as you open the child panes, as shown in Figure 2:

Figure 2. Accordion widget (multiselect mode)
Screenshot of an Accordion widget in multiselect mode

Fixed-height mode

If you specify fixedHeight:true, as in Listing 2, the height of the Accordion remains the same regardless of which pane is open:

Listing 2. Accordion in fixed-height mode
<div data-dojo-type="dojox.mobile.Accordion"
     data-dojo-props='fixedHeight:true' style="height:300px;">
  ...
</div>

Figure 3 shows Accordion in fixed-height mode:

Figure 3. Accordion widget (fixed-height)
Screenshot of An Accordion widget in fixed-height mode

Single-select mode

If you specify singleOpen:true, as in Listing 3, only one pane can be opened at a time:

Listing 3. Accordion in single-select mode
<div data-dojo-type="dojox.mobile.Accordion"
     data-dojo-props='singleOpen:true'>
  ...
</div>

In single-select mode, the height of the Accordion varies depending on the height of the open pane, as shown in Figure 4:

Figure 4. Accordion widget (single-select)
Screenshot of an Accordion widget in single-select mode

Rounded corners

If you specify roundRect:true, as in Listing 4, the Accordion is displayed with rounded corners:

Listing 4. Accordion with rounded corners
<div data-dojo-type="dojox.mobile.Accordion"
     data-dojo-props='roundRect:true'>
  ...
</div>

Figure 5 shows a rounded Accordion widget:

Figure 5. Accordion widget with rounded corners
Screenshot of an Accordion widget with rounded corners

Lazy loading

If you specify lazy:true in a child pane widget, as shown in Listing 5, all the widgets in that pane will not be loaded until it is opened for the first time:

Listing 5. Loading content widgets lazily
<div data-dojo-type="dojox.mobile.Accordion">
  ...
  <div data-dojo-type="dojox.mobile.Pane"
       data-dojo-props='label:"Calendar (Lazy)", lazy:true'>
    <div style="padding:10px">
      <div data-dojo-type="dijit.CalendarLite"></div>
    </div>
  </div>
  ...
</div>

It is the Accordion widget — not pane widgets — that checks for the lazy:true flag and performs lazy loading.

Note that the widget modules (and their dependent modules) in a pane are lazy-loaded automatically. In the case of Listing 5, for example, you don't need to require dijit.CalendarLite explicitly in your application.

Figure 6 shows the result of the code in Listing 5:

Figure 6. CalendarLite in Accordion
CalendarLite lazily loaded into an Accordion widget

Audio

Audio is a very thin wrapper around the HTML5 <audio> element, which plays audio. For desktop browsers that do not support <audio>, this widget automatically replaces <audio> with <embed>. You could simply use <audio> directly without using this widget if you don't need to use a Dojo widget.

Listing 6 shows example code that uses the Audio widget:

Listing 6. Example usage of the Audio widget
<audio data-dojo-type="dojox.mobile.Audio" controls>
  <source src="sample.mp3" type="audio/mpeg">
  <source src="sample.ogg" type="audio/ogg">
  <source src="sample.wav" type="audio/wav">
  <p>Cannot play on this browser.</p>
</audio>

Figure 7 shows the Audio widget:

Figure 7. Audio widget
Screenshot of the Audio widget

Video

Video is a very thin wrapper around the HTML5 <video> element, which plays video. For desktop browsers that do not support <video>, this widget automatically replaces <video> with <embed>. You could simply use <video> directly without using this widget if you don't need to use a Dojo widget.

Listing 7 shows example code that uses the Video widget:

Listing 7. Example usage of the Video widget
<video data-dojo-type="dojox.mobile.Video" controls>
  <source src="sample.mp4" type="video/mp4">
  <source src="sample.ogv" type="video/ogg">
  <source src="sample.webm" type="video/webm">
  <p>Cannot play on this browser.</p>
</video>

Figure 8 shows an example of (paused) video content playing in the Video widget:

Figure 8. Video widget
Screenshot of paused video content playing in the Video widget

Badge

Badge is not a widget that inherits from dijit._WidgetBase but a simple utility class for creating and updating a badge node. A badge, like the ones shown in Figure 9, consists of a simple DOM button:

Figure 9. Badges
Screenshot of three badges

Badge is intended to be used from other widgets such as IconItem or TabBarButton.


Icon

Like Badge, Icon is not a widget that inherits from dijit._WidgetBase but a simple utility class — in this case for creating icons, such as those shown in Figure 10:

Figure 10. Icons
Screenshots of three icons

The code example in Listing 8 encapsulates the creation of an image icon, a CSS sprite icon, and a DOM button:

Listing 8. Example usage of Icon
Image icon:
<div data-dojo-type="dojox.mobile.Icon"
     data-dojo-props='icon:"tab-icon-12h.png"'></div>

CSS sprite icon:
<div data-dojo-type="dojox.mobile.Icon"
     data-dojo-props='icon:"tab-icons.png",iconPos:"29,116,29,29"'></div>

DOM Button:
<div data-dojo-type="dojox.mobile.Icon"
     data-dojo-props='icon:"mblDomButtonBlueCircleArrow"'></div>

DataCarousel, StoreCarousel

Carousel is a widget that shows a list of contents — typically, images — to allow the user to choose from them quickly. Figure 11 shows the Carousel widget in action:

Screenshot of a Carousel showing three images of seashells

In Dojo Mobile 1.7, Carousel was an experimental widget. In 1.8, it was refactored and separated into DataCarousel, which supports the old dojo.data datastore, and StoreCarousel, which supports the new dojo.store datastore. The class-hierarchy diagram in Figure 12 illustrates this new structure:

Carousel class-hierachy diagram

The typical approach is to use either DataCarousel or StoreCarousel and feed data through a datastore, as shown in Listing 9:

<div data-dojo-type="dojox.mobile.StoreCarousel"
     data-dojo-props='store:store1, title:"Category"'></div>

The common base class Carousel has no datastore support. It might not be practical to use the Carousel widget directly, but it is possible if you arrange child widgets for the Carousel as shown in Listing 10:

<div data-dojo-type="dojox.mobile.Carousel">
  <div data-dojo-type="dojox.mobile.SwapView">
    <div data-dojo-type="dojox.mobile.CarouselItem"
      data-dojo-props='src:"images/dish1.jpg"'></div>
    <div data-dojo-type="dojox.mobile.CarouselItem"
      data-dojo-props='src:"images/dish2.jpg"'></div>
  </div>

  <div data-dojo-type="dojox.mobile.SwapView">
    <div data-dojo-type="dojox.mobile.CarouselItem"
      data-dojo-props='src:"images/dish3.jpg"'></div>
    <div data-dojo-type="dojox.mobile.CarouselItem"
      data-dojo-props='src:"images/dish4.jpg"'></div>
  </div>
</div>

The SwapView and CarouselItem child widgets are automatically generated if you use DataCarousel or StoreCarousel.


Pane, Container

Pane and Container are simple <div>-wrapper pane widgets. Container inherits from dijit._Container, whereas Pane doesn't, as shown in the class hierarchy in Figure 13:

Figure 13. Pane and Container class hierarchy
Class-hierarchy diagram for Pane and Container

Unlike View, Pane and Container have no special functionality. They can be used for any purpose — for example, as panes for Accordion, FixedSplitter, GridLayout, and so on, or for creating a partial area in a view.


EdgeToEdgeStoreList, RoundRectStoreList

EdgeToEdgeDataList and RoundRectDataList, which are list widgets that support dojo.data, have been available since Dojo Mobile 1.7. EdgeToEdgeStoreList and RoundRectStoreList, new in 1.8, support the new dojo.store datastore. The usage is basically the same, with the exception of query parameters, which differ between dojo.data and dojo.store.

Figure 14 shows an example of the EdgeToEdgeStoreList widget:

Figure 14. EdgeToEdgeStoreList widget
Screenshot of an EdgeToEdgeStoreList widget

GridLayout

GridLayout is a container widget that places its child widgets in a grid layout, as shown in Figure 15. Each child must be a container widget such as dojox.mobile.Pane.

Figure 15. GridLayout widget
Screenshot of a GridLayout widget

Listing 11 shows an example of using the GridLayout widget:

Listing 11. Example usage of the GridLayout widget
<div data-dojo-type="dojox.mobile.GridLayout" data-dojo-props='cols:2'>
  <div data-dojo-type="dojox.mobile.Pane">...</div>
  <div data-dojo-type="dojox.mobile.Pane">...</div>
  <div data-dojo-type="dojox.mobile.Pane">...</div>
  <div data-dojo-type="dojox.mobile.Pane">...</div>
  <div data-dojo-type="dojox.mobile.Pane">...</div>

  <div data-dojo-type="dojox.mobile.Pane">...</div>
</div>

Note that the root node of each child must be a <div> element. If you want to place something whose root node is not a <div>, you must wrap it in another widget whose root node is a <div>.

You can specify the number of columns in each row with the cols property, as shown in Figure 16:

Figure 16. GridLayout with the cols property
Screenshot of two GridLayout widgets, one with two columns and one with three columns

If you don't specify the number of columns (equivalent to cols:0), GridLayout wraps as many columns of child widgets per row as the GridLayout's width will accommodate.


IconMenu

IconMenu, shown in Figure 17, is a pop-up menu:

Figure 17. IconMenu widget
Screenshot of an IconMEnu widget

Each menu item must be dojox.mobile.IconMenuItem. IconMenuItem inherits from the same base class, dojox.mobile._ItemBase, as ListItem. Therefore, the properties for performing a view transition, such as moveTo, are available. Listing 12 shows an example of using of the IconMenu widget:

Listing 12. Example usage of the IconMenu widget
<ul data-dojo-type="dojox.mobile.IconMenu" data-dojo-props='cols:3'>
  <li data-dojo-type="dojox.mobile.IconMenuItem"
      data-dojo-props='label:"Tour", icon:"images/tab-icon-19w.png",
            moveTo:"view2", transition:"slide", closeOnAction:true'></li>
  ...
</ul>

ProgressBar

The ProgressBar widget shows the progress of a task. The value it displays can be a number (0 to maximum) or percentage (0% to 100%). Figure 18 shows some examples:

Figure 18. ProgressBar widgets
Screenshots of three ProgressBar examples, for (top to bottom) iPhone, Android, and BlackBerry

Listing 13 shows an example of using the ProgressBar widget:

Listing 13. Example usage of the ProgressBar widget
<div data-dojo-type="dojox.mobile.ProgressBar"
     data-dojo-props='maximum:200, onChange:onChange'
     style="width:275px"></div>

Rating

Rating is a widget that displays a rating, usually with stars. Figure 19 shows several examples:

Figure 19. Rating widgets
Screenshot showing nine Rating widget examples

Listing 14 shows an example of using the Rating widget:

Listing 14. Example usage of the Rating widget
<span data-dojo-type="dojox.mobile.Rating"
      data-dojo-props='image:"star-orange.png",numStars:3,value:1.5'></span>

You can create and specify your own Rating image. As shown in the example in Figure 20, it must include three equal-width stars (or equivalents) — full star, empty star, and half star, from left to right:

Figure 20. Example of a star image
Image of full-star, empty-star, and half-star used for a Rating

ScreenSizeAware

ScreenSizeAware is an experimental module that helps you create applications that transform their UI layout according to the screen size. In a phone-sized screen, the application shows a list widget that fills the screen. The user can move to another view by selecting a list item, as shown in Figure 21:

Figure 21. Screen size-aware application in a phone
Screenshot of a screen size-aware application in a phone

In a tablet-sized screen, the application shows a horizontally split view whose left pane is a list widget, as shown in Figure 22:

Figure 22. Screen size-aware application in a tablet
Screenshot fo a screen size-aware application in a tablet

ScreenSizeAware assumes that the application consists of two horizontally split panes, and that the left pane has a list widget, as shown in the example in Listing 15:

Listing 15. Required UI structure for ScreenSizeAware
<div data-dojo-type="dojox.mobile.FixedSplitter"
     data-dojo-props='orientation:"H"'>
  <div data-dojo-type="dojox.mobile.Container" style="width:300px;">
    <div id="leftView" data-dojo-type="dojox.mobile.ScrollableView">
      <h1 data-dojo-type="dojox.mobile.Heading"
          data-dojo-props='fixed:"top"'>Left Pane</h1>
      <ul data-dojo-type="dojox.mobile.EdgeToEdgeList" data-dojo-props='stateful:true'>
        <li data-dojo-type="dojox.mobile.ListItem"
 data-dojo-props='label:"View1", moveTo:"view1"'></li>
        ....
      </ul>
    </div>
  </div>
  <div data-dojo-type="dojox.mobile.Container">
    <div id="view1" data-dojo-type="dojox.mobile.ScrollableView">
      <h1 data-dojo-type="dojox.mobile.Heading"
          data-dojo-props='fixed:"top", back:"Home", moveTo:"leftView"'>Right Pane</h1>
      ....
    </div>
  </div>
</div>

To make your application screen size-aware, all you need to do is to require ScreenSizeAware and place a <span data-dojo-type="dojox.mobile.ScreenSizeAware"></span> tag somewhere in your application. Then the ScreenSizeAware widget transforms the UI layout according to the current screen size. No inline JavaScript code is necessary in your application HTML file.

There's also an alternative way of applying ScreenSizeAware to your application. Instead of including the <span> tag, you can use the screenSizeAware property of FixedSplitter, as shown in Listing 16. In this case, you do not need to explicitly require ScreenSizeAware, because it is dynamically loaded by FixedSplitter.

Listing 16. Usage of ScreenSizeAware property
<div data-dojo-type="dojox.mobile.FixedSplitter"
     data-dojo-props='orientation:"H", screenSizeAware:true'>

Note that the ScreenSizeAware module is still experimental and that its APIs are subject to change.


ScrollablePane

ScrollablePane is a pane that has touch-scrolling capability. Unlike ScrollableView, it is not a view, so you can place it in a view to create a partial scrolling area. On WebKit-based browsers, if the roundCornerMask property is true, the widget has rounded corners, as shown in Figure 23:

Figure 23. ScrollablePane widget
Screenshot of a ScrollablePane widget

Listing 17 shows an example of using the ScrollablePane widget:

Listing 17. Example usage of the ScrollablePane widget
<div data-dojo-type="dojox.mobile.ScrollablePane"
      data-dojo-props='height:"200px",roundCornerMask:true'>
  <ul data-dojo-type="dojox.mobile.RoundRectList">
    ...
<div>

SearchBox

SearchBox is a new form widget. It is a non-templated base class for INPUT type="search". Figure 24 shows an empty SearchBox and a SearchBox into which search text has been input:

Screenshot of a SearchBox widget

Listing 18 shows an example of using the SearchBox widget:

<input data-dojo-type="dojox.mobile.SearchBox"
       type="search" placeHolder="Search">

SimpleDialog

SimpleDialog is a dialog box for mobile applications. Compared to dijit.Dialog, its code size is much smaller and its functionality is more limited. Figure 25 shows three SimpleDialog examples:

Figure 25. SimpleDialog widget
Screenshots of three SimpleDialog examples

When SimpleDialog is created, it is initially hidden (display="none"). To show it, you must get a reference to the widget and call the show() method, as demonstrated in Listing 19:

Listing 19. Example usage of the SimpleDialog widget
  <script type="text/javascript">
    require([
      "dijit/registry",
      "dojox/mobile/parser",
      "dojox/mobile",
      "dojox/mobile/compat",
      "dojox/mobile/SimpleDialog",
      "dojox/mobile/Button"
    ], function(registry){
      show = function(dlg){
        registry.byId(dlg).show();
      }
      hide = function(dlg){
        registry.byId(dlg).hide();
      }
    });

  </script>
</head>
<body style="visibility:hidden;">
  <div id="dlg1" data-dojo-type="dojox.mobile.SimpleDialog">
    <div class="mblSimpleDialogTitle">Rain Alert</div>
    <div class="mblSimpleDialogText">Do you have an umbrella?</div>
    <button data-dojo-type="dojox.mobile.Button" onclick="hide('dlg1')">No</button>
    <button data-dojo-type="dojox.mobile.Button" onclick="hide('dlg1')">Yes</button>
  </div>

  <div id="view" data-dojo-type="dojox.mobile.View">
    <button onclick="show('dlg1')">Show Dialog</button>
  </div>
</body>
</html>

As you can see in Listing 19, you can place arbitrary HTML, text, or widgets directly into a SimpleDialog.

Another interesting way to use this widget is to load external dialog content, such as the example content in Listing 20:

Listing 20. Dialog content (dialog-data.html)
<div class="mblSimpleDialogTitle">Rain Alert</div>
<div class="mblSimpleDialogText">Do you have an umbrella?</div>
<button data-dojo-type="dojox.mobile.Button" onclick="hide('dlg1')">No</button>
<button data-dojo-type="dojox.mobile.Button" onclick="hide('dlg1')">Yes</button>

You load the dialog content by using _ContentPaneMixin, as shown in Listing 21:

Listing 21. Loading external dialog content
<div id="dlg1" data-dojo-type="dojox.mobile.SimpleDialog"
  data-dojo-mixins="dojox.mobile._ContentPaneMixin"
  data-dojo-props='href:"dialog-data.html"'></div>

The example in Listing 21 dynamically adds dojox.mobile.ContentPane's capability to SimpleDialog using the data-dojo-mixins property, which is also a new feature in Dojo 1.8.


TreeView

TreeView is a scrollable view with tree-style navigation. This widget can be connected to a dojox.data.FileStore to be, for example, a quick directory browser, as demonstrated in Figure 26:

Figure 26. TreeView widget
Screenshots showing the TreeView widget in action

The code Listing 22 implements the TreeView example shown in Figure 26:

Listing 22. Example usage of the TreeView widget
  <script type="text/javascript">
    require([
      "dojox/data/FileStore",
      "dijit/tree/ForestStoreModel",
      "dojox/mobile/parser",
      "dojox/mobile",
      "dojox/mobile/compat",
      "dojox/mobile/TreeView"
    ], function(FileStore, ForestStoreModel){
      var store = new FileStore({
        url: "dojox/data/demos/stores/filestore_dojotree.php",
        id: "theStore",
        label: "name",
        pathAsQueryParam: true
      });
      treeModel = new ForestStoreModel({
        store: store,
        rootLabel: "Files",
        childrenAttrs: ["children"],
        newItemIdAttr: "path"
      });
    });
  </script>
</head>
<body style="visibility:hidden;">
  <div data-dojo-type="dojox.mobile.TreeView"
   data-dojo-props='model: treeModel'></div>
</body>
</html>

ValuePicker

Like SpinWheel, ValuePicker is a widget for selecting values. Its UI is different from SpinWheel's, but the API is the same. Figure 27 shows an example:

Figure 27. ValuePicker widget
Screenshot of a ValuePicker widget

The user selects a value by clicking the plus button or the minus button, or by entering the value directly into the input field. This type of value picker is typically seen on Android devices.

The code in Listing 23 implements the ValuePicker shown in Figure 27:

Listing 23. Example usage of the ValuePicker widget
<div data-dojo-type="dojox.mobile.ValuePicker">
  <div data-dojo-type="dojox.mobile.ValuePickerSlot"
    data-dojo-props="labels:['A','B','C','D',...,'Z']"
    style="text-align:center;width:40px;"></div>
  <div data-dojo-type="dojox.mobile.ValuePickerSlot"
    data-dojo-props='labelFrom:3000, labelTo:3100'
    style="width:70px;"></div>
  <div data-dojo-type="dojox.mobile.ValuePickerSlot"
    data-dojo-props='labelFrom:0, labelTo:9'
    style="width:50px;"></div>
  <div data-dojo-type="dojox.mobile.ValuePickerSlot"
    data-dojo-props="labels:['pt','px','cm']"
    style="width:50px;"></div>
</div>

ValuePickerDatePicker

ValuePickerDatePicker, shown in Figure 28, is a date-picker widget based on ValuePicker:

Figure 28. ValuePickerDatePicker widget
Screenshot of a ValuePickerDatePicker widget

You instantiate this widget in markup with:

<div data-dojo-type="dojox.mobile.ValuePickerDatePicker"></div>

ValuePickerTimePicker

ValuePickerTimePicker, shown in Figure 29, is a time-picker widget based on ValuePicker:

Figure 29. ValuePickerTimePicker widget
Screenshot of a ValuePickerTimePicker widget

You instantiate this widget in markup with:

<div data-dojo-type="dojox.mobile.ValuePickerTimePicker"></div>

DatePicker, TimePicker

DataPicker is a wrapper widget around SpinWheelDatePicker or ValuePickerDatePicker. TimePicker is a wrapper widget around SpinWheelTimePicker or ValuePickerTimePicker. They should be used with the automatic theme loader, deviceTheme. If the android theme is currently in use, they instantiate a ValuePicker-based picker; otherwise, they instantiate a SpinWheel-based picker.

Figure 30 shows the DatePicker widget:

Figure 30. DatePicker widget
Screenshot of two DatePicker widget; the one on the left is for Android; the one on the right is for other platforms

Figure 31 shows the TimePicker widget:

Figure 31. TimePicker widget
Screenshot of two DatePicker widget; the one on the left is for Android; the one on the right is for other platforms

migrationAssist

The migrationAssist module helps you migrate your Dojo Mobile 1.6/1.7 applications to 1.8. To enable migrationAssist, all you need to do is require this module, as shown in Listing 24:

Listing 24. Enabling migrationAssist
// old API case
<script>
  dojo.require("dojox.mobile.migrationAssist");
  dojo.require("dojox.mobile");
  ....
</script>

// AMD case
<script>
  require([
    "dojox/mobile/migrationAssist",
    "dojox/mobile",
    ....
  ]);
</script>

If your application uses deprecated or no-longer-available functions, this module detects them and displays messages in the browser console. Also, it tries to fix them dynamically to the extent possible so that the target application can work. Note, however, that the purpose of migrationAssist is not to run older applications as they are, but to assist in migration.


pageTurningUtils

pageTurningUtils is an experimental utility module that provides page-turning effects that closely mimic the turning of real book pages. It enables you to create page-turning animations as in an ebook reader or slide-show application. The page contents can be arbitrary HTML, text, images, or widgets. Figure 32 shows an example of pageTurningUtils used in single-page mode:

Figure 32. Page-turning utility (single-page mode)
Screen of an example of pageTurningUtils used in single-page mode

Figure 33 shows an example of pageTurningUtils used in double-page mode:

Figure 33. Page-turning utility (double-page mode)
Screen of an example of pageTurningUtils used in double-page mode

The sample code in Listing 25 demonstrates how to use pageTurningUtils:

Listing 25. Example usage of pageTurningUtils
<!DOCTYPE html>
<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>Page Turning</title>
  <link href="../themes/common/PageTurning.css" rel="stylesheet">
  <script src="../../../dojo/dojo.js" data-dojo-config="async: true"></script>

  <script type="text/javascript">
    require([
      "dojo/_base/connect",
      "dojo/dom",
      "dojo/ready",
      "dojox/mobile/pageTurningUtils"
    ], function(connect, dom, ready, pageTurningUtils){
      var w = 285; // width of the page
      var h = 388; // height of the page
      var turnfrom = "top"; // "top", "bottom" or "left"
      var page = 1; // 1:single-page, 2:double-page
      var dogear = 1.0; // dogear width between 0 and 1
      var duration = 2.0; // duration of animation in seconds
      var alwaysDogeared = false; // all the pages are dogeared or not

      ready(function(){
        var utils = new pageTurningUtils();
        utils.init(w, h, turnfrom, page, dogear, duration, alwaysDogeared);
        utils.initCatalog(dom.byId("catalog"));

        connect.connect(dom.byId("catalog"), "onclick", function(e){
          if(e.offsetX < w / 2){
            // clicked on the left half of the image
            utils.turnToPrev();
          }else{
            // clicked on the right half of the image
            utils.turnToNext();
          }
        });
      });
    });
  </script>
  
  <style type="text/css">
    img{
      width: 100%;
      height: 100%;
    }
  </style>
</head>
<body>
  <div id="catalog" style="margin:10px;">
    <div id="page1">
      <div id="front1"><img alt="" src="images/pic1.jpg"></div>
      <div id="back1"></div>
    </div>
    <div id="page2">
      <div id="front2"><img alt="" src="images/pic2.jpg"></div>
      <div id="back2"><img alt="" src="images/pic3.jpg"></div>
    </div>
    <div id="page3">
      <div id="front3"><img alt="" src="images/pic4.jpg"></div>
      <div id="back3"></div>
    </div>
  </div>
</body>
</html>

This example listens to the user's click events. If you click on the right half of the image, the next page opens; if you click on the left half of the image, the preceding page opens. You might want to experiment with changing the various parameters in Listing 25.

You can use pageTurningUtils for both mobile and desktop applications. Notice that Listing 25 doesn't require dojox/mobile. Even though pageTurningUtils is located under the dojox.mobile namespace, it has no dependency on dojox.mobile. Also note that this module is still experimental and that its APIs are subject to change.


Conclusion

In this article, you've seen many of the widgets, utility classes, and modules that are new in Dojo Mobile 1.8. Take advantage of the code examples here and start using these new features to build more powerful, attractive mobile web applications. Also, don't forget that Dojo Mobile has a rich set of existing widgets in addition to the new widgets introduced in this article (see Resources for a link to the full Dojo Mobile documentation). And be sure to check out Part 2, which explores new enhancements to existing Dojo Mobile features.

Resources

Learn

Get products and technologies

  • Dojo 1.8.x: Download the latest Dojo Toolkit version.

Comments

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 Mobile development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development
ArticleID=845331
ArticleTitle=What's new in Dojo Mobile 1.8, Part 1: New widgets
publish-date=11192012