dojox/mobile/pageTurningUtils

Authors:Atsushi Ono
Developers:Richard Redpath, Atsushi Ono
since:V1.8

The dojox/mobile/pageTurningUtils is an EXPERIMENTAL module. It works only on webkit-based browsers. It does not work on other desktop browsers such as Firefox or IE.

Introduction

pageTurningUtils is an 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.

Currently, this class provides the following three types of page turning effects. We may add bottom-left turning in the future.

Top-right turning with dog ear

The top right corner of the current page is dog-eared, and you can turn the page from the dog-eared corner with page turning animations. This page turning effect can be used, for example, for English books.

../../_images/pageTurningUtils-top.gif

Bottom-right turning without dog ear

The current page is not dog-eared. You can turn the page from the bottom right corner with page turning animations. This page turning effect can be used, for example, for English books, too.

../../_images/pageTurningUtils-bottom.gif

Top-left turning with dog ear

The top left corner of the current page is dog-eared, and you can turn the page from the dog-eared corner with page turning animations. This page turning effect can be used, for example, for some Asian books.

../../_images/pageTurningUtils-left.gif

Usage

The pageTurningUtils class expects that your book application has the DOM structure as shown below. The top level container node represents a whole catalog, and it has multiple pages as child nodes. And each page node should have two child nodes; the first node represents the content shown in the front side of the page, and the second node represents the one shown in the back side of the page. Please make the front-side/back-side node empty if it is an empty page (like “back1” node in the example below).

<div id="catalog">
    <div id="page1">
        <div id="front1"><img src="images/pic1.jpg"></div>
        <div id="back1"></div>
    </div>
    <div id="page2">
        <div id="front2"><img src="images/pic2.jpg"></div>
        <div id="back2"><img src="images/pic3.jpg"></div>
    </div>
    <div id="page3">
        <div id="front3"><img src="images/pic4.jpg"></div>
        <div id="back3"></div>
    </div>
</div>

When the DOM structure is ready, you can instantiate the pageTurnigUtils class to initialize the catalog node. Note that this class is not a widget, and that it is not intended to be used declaratively in HTML markup. You need to instantiate it programmatically. The typical usage is as below:

<!-- Need to load the stylesheet for the pageTurningUtils class -->
<link href="dojox/mobile/themes/common/PageTurning.css" rel="stylesheet">
require([
    "dojo/dom",
    "dojo/ready",
    "dojox/mobile/pageTurningUtils"
], function(dom, ready, pageTurningUtils){
    utils = new pageTurningUtils();

    ready(function(){
        // Set property values to pageTurningUtils object
        utils.init(288, 385, "top", 2, 1.0, 2.0, false);

        // Initialize catalog node
        utils.initCatalog(dom.byId("catalog"));
    });

    prev = function(){
        utils.turnToPrev();
    };

    next = function(){
        utils.turnToNext();
    };
});

First, you need to call pageTurningUtils.init() function to set several property values. You can specify the following arguments:

pageTurningUtils.init(w, h, turnfrom, page, dogear, duration, alwaysDogeared)
Argument Type Default Description
w Number 0 The width of each page by pixels. You cannot specify it by percentage.
h Number 0 The height of each page by pixels. You cannot specify it by percentage.
turnfrom String? “top” Specifies from which side/corner the page turning starts. You can choose from “top”, “bottom” or “left”. Defaults to “top”. If “top”, each page is turned from top-right corner of the page. If “bottom”, each page is turned from bottom-right corner of the page. And if “left”, each page is turned from top-left corner of the page. The page is shown as dog-eared except the case of “bottom”.
page Number? 1 The number of pages shown in the screen at a time. This parameter should be either of 1 or 2. Defaults to 1. If 1, the only one side of two facing pages are shown. If 2, the two facing pages are shown at a time.
dogear Float? 1.0 The ratio of actual dogear width to the maximum dogear width which is 11 percent of the page width (= 0.11 * w). This parameter should be a float number between 0 and 1. Defaults to 1. The actual dogear width is calculated by the following formula: 0.11 * w * dogear. This parameter is ignored if “bottom” is specified to turnfrom parameter.
duration Float? 2.0 The duration of page turning animations by seconds (ex. 1.5, 3, etc). Defaults to 2.0.
alwaysDogeared Boolean false Specifies whether all pages are always dog-eared or not. If true, all pages are always dog-eared. If false, only the current page is dog-eared while the others are not. This parameter is ignored if “bottom” is specified to turnfrom parameter.

And all you need to do is to call pageTurningUtils.initCalatalog(catalogNode) function to initialize the catalog node. After initialization, you can turn page forward by calling pageTurningUtils.turnToNext() function, and turn page backward by calling pageTurningUtils.turnToPrev() function.

Examples

Various page contents

The page contents can be not only images but also other elements such as iframe and div contents. You can also use widgets as page contents such as dojox/mobile/View, dojox/mobile/ScrollableView, dojox/mobile/ContentPane, etc. See test_pageTurningUtils-pageType.html in the dojox/mobile/tests folder for a complete example.

require([
    "dojo/dom",
    "dojo/ready",
    "dojox/mobile/pageTurningUtils",
    "dojox/mobile/parser",
    "dojox/mobile",
    "dojox/mobile/ScrollableView",
    "dojox/mobile/ContentPane",
    "dojox/mobile/SpinWheel"
], function(dom, ready, pageTurningUtils){
    utils = new pageTurningUtils();

    ready(function(){
        // Set property values to pageTurningUtils object
        utils.init(320, 400, "top", 1, 1.0, 1.5);

        // Initialize catalog node
        utils.initCatalog(dom.byId("catalog"));
    });

    prev = function(){
        utils.turnToPrev();
    };

    next = function(){
        utils.turnToNext();
    };
});
<div>
    <button onclick="prev()" style="width:50px">Prev</button>
    <button onclick="next()" style="width:50px">Next</button>
</div>
<div id="catalog">
    <div id="page1"> <!-- image -->
        <div id="front1">
            <img src="images/pic2.jpg" width="100%" height="100%"/>
        </div>
        <div id="back1"></div>
    </div>
    <div id="page2"> <!-- iframe -->
        <div id="front2" class="myPane">
            <iframe src="data/fragment1.html" width="100%" height="100%"></iframe>
        </div>
        <div id="back2"></div>
    </div>
    <div id="page3"> <!-- div contents -->
        <div id="front3" class="myPane">
            <div style="padding:10px;">
                <div style="font-size: 24px">Unbeatable JavaScript Tools</div>
                <div style="border-top: 1px dashed gray;margin: 20px"></div>
                <img alt="" src="images/dojo-logo1.png" style="float:left;margin-right:5px">
                <p>Dojo saves you time, delivers powerful performance, and scales with your development process...</p>
            </div>
        </div>
        <div id="back3"></div>
    </div>
    <div id="page4"> <!-- dojox/mobile/View widget -->
        <div id="front4" data-dojo-type="dojox/mobile/View" style="height:100%;background-color:#c5ccd3;">
            <h1 data-dojo-type="dojox/mobile/Heading">View</h1>
            <div data-dojo-type="dojox/mobile/RoundRect" shadow="true">
                <p><img src="images/dojo-logo1.png" align="left" width="60" height="60">
                Dojo saves you time and scales with your development process, using web standards as its platform...</p>
            </div>
        </div>
        <div id="back4"></div>
    </div>
    <div id="page5"> <!-- dojox/mobile/ScrollableView widget -->
        <div id="front5" data-dojo-type="dojox/mobile/ScrollableView" style="height:100%;background-color:#c5ccd3;">
            <h1 data-dojo-type="dojox/mobile/Heading">ScrollableView</h1>
            <ul data-dojo-type="dojox/mobile/EdgeToEdgeList">
                <li data-dojo-type="dojox/mobile/ListItem" data-dojo-props='icon:"images/i-icon-1.png"'>
                    Item 1
                </li>
                <li data-dojo-type="dojox/mobile/ListItem" data-dojo-props='icon:"images/i-icon-2.png"'>
                    Item 2
                </li>
            </ul>
        </div>
        <div id="back5"></div>
    </div>
    <div id="page6"> <!-- dojox/mobile/ContentPane widget -->
        <div id="front6" data-dojo-type="dojox/mobile/ContentPane" data-dojo-props='href:"data/view5.html"'></div>
        <div id="back6"></div>
    </div>
</div>
../../_images/pageTurningUtils-pageType.gif

Handling the event when a page is turned

You can handle the event when a page is turned by connecting to “onPageTruned” callback function of pageTurningUtils object as shown in the example below. See test_pageTurningUtils-callback.html in the dojox/mobile/tests folder for a complete example.

require([
    "dojo/_base/connect",
    "dojo/dom",
    "dojo/ready",
    "dojox/mobile/pageTurningUtils"
], function(connect, dom, ready, pageTurningUtils){
    utils = new pageTurningUtils();

    ready(function(){
        // Set property values to pageTurningUtils object
        utils.init(288, 385, "top", 1, 1.0, 1.5);

        // Initialize catalog node
        utils.initCatalog(dom.byId("catalog"));

        // Connect to onPageTurned callback function
        connect.connect(utils, "onPageTurned", null, function(pageNode){
            console.log("onPageTurned: " + pageNode.id);
        });
    });
});

Changing the property values

If you want to change the property values of pageTurningUtils object (ex. changing the number of pages shown in a screen when the orientation changes), you can do so by calling both init() and initCatalog() functions again. See test_pageTurningUtils.html in the dojox/mobile/tests folder for a complete example.

require([
    "dojo/dom",
    "dojo/ready",
    "dojox/mobile/pageTurningUtils"
], function(dom, ready, pageTurningUtils){
    utils = new pageTurningUtils();

    ready(function(){
        // Set property values to pageTurningUtils object
        utils.init(288, 385, "top", 1, 1.0, 1.5);

        // Initialize catalog node
        utils.initCatalog(dom.byId("catalog"));
    });

    // Call this function when you would like to change property
    changeProperty = function(){
        // Change page property value from 1 to 2
        utils.init(288, 385, "top", 2);

        // Initialize catalog node again
        utils.initCatalog(dom.byId("catalog"));
    };
});

Adding/Removing pages

The following example shows how you can add/remove pages. When you add a page, you need to call initPage(pageNode) function first to initialize the new page, and then call resetCatalog() function. When you remove a page, you need to call only resetCatalog() function. See test_pageTurningUtils-add-remove.html in the dojox/mobile/tests folder for a complete example.

require([
    "dojo/dom",
    "dojo/dom-construct",
    "dojo/ready",
    "dojox/mobile/pageTurningUtils"
], function(dom, domConstruct, ready, pageTurningUtils){
    utils = new pageTurningUtils();

    ready(function(){
        // Set property values to pageTurningUtils object
        utils.init(288, 385, "top", 1, 1.0, 1.5);

        // Initialize catalog node
        utils.initCatalog(dom.byId("catalog"));
    });

    // Call this function when you would like to a new page
    addPage = function(){
        // Add a new page node to the catalog node
        var page = domConstruct.create("div", null);
        page.innerHTML = '<div class="myPane"><h1>New Page</h1></div>'
                       + '<div></div>';
        domConstruct.place(page, dom.byId("catalog"));

        // Initialize a new page
        utils.initPage(page);

        // Reset catalog
        utils.resetCatalog();
    };

    // Call this function when you would like to remove the last page
    remove = function(){
        // Remove the last page
        var pages = utils.getPages();
        domConstruct.destroy(pages[pages.length - 1]);

        // Reset catalog
        utils.resetCatalog();
    };
});
Error in the documentation? Can’t find what you are looking for? Let us know!