Gears on Mobile Devices

Gears is now available for a number of mobile browsers and devices.

Mobile devices are, by their nature, often disconnected from the network. Even when connected, the latencies in data connections in mobile networks can make web applications sluggish. Gears gives developers the tools to overcome these obstacles.

Gears works in exactly the same way on a mobile device as it does on a desktop PC. If you've already written an application that uses Gears, your application will also work on a mobile device. Except, of course, only within the limitations of that device. This means you need to consider things such as small screen and limited ability to input text. Furthermore, on some mobile browsers, the implementation of the Document Object Model and CSS is limited. Limitations of the IE Mobile browser shipped with Windows Mobile 5 and 6 are discussed later in this document.

Contents

  1. Audience
  2. Getting Started
  3. IE Mobile Limitations
  4. Setting up a Windows Mobile Emulator

Audience

This document is intended for experienced AJAX programmers who want to develop Gears-enabled web applications for mobile devices. It also provides specific recommendations and help for developers working with Windows Mobile 5 or 6. It provides instructions on setting up a development environment and discusses known limitatations and workarounds for the IE Mobile browser.

Getting Started

If you're developing for IE Mobile, we also recommend the following steps.

That's it!

IE Mobile Limitations

The IE Mobile browser shipped with Windows Mobile 5 and 6 devices has limitations which are important to note when writing AJAX applications. Information on these limitations, and some workarounds, are provided below:

CSS

Neither IE Mobile on Windows Mobile 5 nor 6 support the CSS position: style attribute. This means text is not positioned in any way, it simply appears within the normal flow of an HTML document.

Document Object Model

Document Object Model (DOM) limitations, and example workarounds, are provided below:

Accessing a Document Element

IE Mobile for Windows Mobile 5 does not support document.getElementById(), though IE Mobile for Windows Mobile 6 does. The following code snippet provides a workaround using the document.all DOM property.

/**
 * Tests if an element is defined.
 * @param type - The type of the element to be tested.
 */
function isDefined(type) {
  return type != 'undefined' && type != 'unknown';
}

/**
 * Retrieve a DOM element by its ID.
 * @param id - The ID of the element to locate.
 */
function getDOMElementById(id) {
  if (isDefined(typeof document.getElementById)) {
     return document.getElementById(id);
  } else if (isDefined(typeof document.all)) {
     return document.all[id];
  } else {
    throw new Error("Can not find a method to locate DOM element.");
    return null;
  }
}

Creating a Document Element

IE Mobile for Windows Mobile 5 does not support createElement, though IE Mobile for Windows Mobile 6 does. For Windows Mobile 5 devices, create elements using the innerHTML property. This method also works for all modern desktop browsers.

node.innerHTML = "<p id='myElement'></p>";

Setting Element Text

IE Mobile for Windows Mobile 5 does not support the createTextNode method. To set the text content of an element use the innerText property instead:

function setElementText(node, text) {
 if (isDefined(typeof node.innerText)) {
   node.innerText = text;
 } else {
   while (node.firstChild) {
     node.removeChild(node.firstChild);
   }
   node.appendChild(document.createTextNode(text));
 }
}

Modifying a Document Element

Use the innerHTML and innerText properties to modify an element on IE Mobile for both Windows Mobile 5 and 6.

ActiveX : Problems with setting some objects

On IE Mobile for Windows Mobile 5 and 6 some objects that you may expect to be JavaScript objects are instead ActiveX controls. Notably the window object is an ActiveX control, and so does not support expando properties. This means that you cannot add methods or properties to a window as follows:

window.myObject = new Array(); // Does not work!

A workaround is to declare myObject as a top-level object in the global scope. It is then accessible with the notation window.myObject, for example:

myObject = new Array();
alert(window.myObject);       // OK!

Checking whether a method exists before calling it does not work if myObject is an ActiveX object. For example, the following will silently crash:

if (myObject.askQuestion) {
  myObject.askQuestion(42);
}

Instead, a safe way to do the same check is:

if (isDefined(typeof myObject.askQuestion)) {
  myObject.askQuestion(42);
}

where the isDefined function is

function isDefined(type) {
 return type != 'undefined' && type != 'unknown';
}

Recursion

Avoid recursion. IE Mobile for both Windows Mobile 5 and 6 have an extremely limited call stack of about 16 javascript function calls. Violate it and your JavaScript will no longer execute.

Layout Refresh

IE Mobile for Windows Mobile does not always correctly update the page layout when a new element is inserted dynamically into the DOM. For example, modifications to an existing table element will not be reflected in the layout. To avoid this, you must replace the entire table element whenever it is modified.

MSDN Resources

MSDN contains a lot of useful information on Windows Mobile development. See, for example:

Setting up a Windows Mobile Emulator

There are four types of Windows Mobile device:

Due to greater support of HTML elements, CSS, the Document Object Model, and the presence of a touchscreen, we recommend you use a Windows Mobile 6 Classic/Professional device or emulator when developing a web app. Instructions are provided below.

The Windows Mobile 6 emulator runs only on a Windows PC. It can be used either through Visual Studio or as a stand-alone application. The latter is recommended unless you are also contributing to the Gears open source project.

Note: The Windows Mobile 6 emulator requires ActiveSync (for XP systems) or Windows Mobile Device Center (for Vista). Instructions for installing both are included below.

1. Install ActiveSync (for XP systems) or Windows Mobile Device Center (for Vista):

2. Install the Windows Mobile 6 Emulator:

3. If you are working on an XP system configure ActiveSync:

4. If you are working on a Vista system configure Windows Mobile Device Center:

5. Run the Windows Mobile 6 Emulator: