gears - Google Code

Source Path: svn/ trunk/ gears/ sdk/ mobile.html

‹ r1157 r2886

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">

<!--
Copyright 2008, Google Inc.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright notice, 
    this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.
 3. Neither the name of Google Inc. nor the names of its contributors may be
    used to endorse or promote products derived from this software without
    specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<html>
  <head>
    <title>Gears on Mobile Devices</title>
    <link rel="stylesheet" type="text/css" href="gears.css" />
</head>

<body>

<h1>Gears on Mobile Devices</h1>

<div id="pagecontent">

<p>Gears is now available on Windows Mobile 5 and 6 devices.</p>
<p>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.</p>

<p>Gears works in exactly the same way on a Windows Mobile 5 or
6 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 Windows Mobile
5 or 6 device. Except, of course, only <em>within the limitations of that
device</em>. This means you need to consider things such as small screen
and limited ability to input text as well as the limitations of the Document
Object Model and CSS APIs present on mobile devices. Limitations of Windows
Mobile 5 and 6 devices are discussed later in this document.</p>

<h1>Contents</h1>
<div>
  <ol class="toc">
  <li><a href="#aud">Audience</a></li>
  <li><a href="#mobstart">Getting Started</a></li>
  <li><a href="#limits">Windows Mobile 5 and 6 Limitations</a></li>
  <li><a href="#env_setup">Setting up a Windows Mobile Emulator</a></li>
  </ol>
</div>


<a name="aud" id="aud"></a>
<h1>Audience</h1>

<p>This document is intended for experienced AJAX programmers who want
to develop Gears-enabled web applications for Windows Mobile 5 or 6 devices.
It provides instructions on setting up a development environment and discusses
known limitatations and workarounds.</p>


<a name="mobstart" id="mobstart"></a>
<h1>Getting Started </h1>

<ul>
  <li>If you're not familiar with developing for Windows mobile devices,
    consider <a href="#limits">Windows Mobile 5 and 6 Limitations</a>.</li>
  <li>If you're not familiar with Gears, work through 
    <a href="design.html">Getting Started with Gears</a>.</li>
  <li>If you're developing a new app, we recommend that you develop using
    a desktop browser but bear in mind <a href="#limits">Windows Mobile 5 and
    6 Limitations</a>. Why <em>desktop</em>? Well, just considering screen
    size alone, it's easier.</li>
  <li>Set up a <a href="#env_setup">Windows mobile device emulator</a>. </li>
  <li><a href="install.html" target="_self">Install Gears</a> on the
    emulator.</li>
  <li>Run the <a href="sample.html">sample applications</a> to confirm 
    everything is working.</li>
  <li>Modify your app to work within the limitations of Windows Mobile 
    devices.</li>
  <li><b>If you are porting an existing Web application to Windows Mobile, 
    make sure you update the
    <a href="http://code.google.com/apis/gears/gears_init.js">gears_init.js</a>
    file included in your application.</b> The Windows Mobile version of Gears
    needs to be initialized in a slightly different way than all other versions 
    of Gears, so you need to include the latest version of 
    <a href="http://code.google.com/apis/gears/gears_init.js">gears_init.js</a>
    to guarantee that your application works correctly across all platforms.
  </li>
</ul>

<p>That's it!</p>


<a name="limits" id="limits"></a>
<h1>Windows Mobile 5 and 6 Limitations</h1>

<p>Limitations to consider when writing AJAX applications for Windows Mobile
5 and 6 devices, and some workarounds, are provided below:</p>

<ul>
<li><a href="#css_win_mo">CSS</a></li>
<li><a href="#dom_win_mo">Document Object Model</a></li>
<li><a href="#active_x_win_mo">ActiveX</a></li>
<li><a href="#recursion">Recursion</a></li>
<li><a href="#layout_refresh">Layout refresh</a></li>
<li><a href="#msdn">MSDN Resources</a></li>
</ul>


<a name="css_win_mo" id="css_win_mo"></a>
<h2>CSS</h2>

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


<a name="dom_win_mo" id="dom_win_mo"></a>
<h2>Document Object Model</h2>

<p>Document Object Model (DOM) limitations, and example workarounds, are
provided below:</p>

<ul>
<li><a href="#getelem">Accessing a Document Element</a></li>
<li><a href="#create_doc_elements_win_mo">Creating a Document Element</a></li>
<li><a href="#element_text">Setting Element Text</a></li>
<li><a href="#change_doc_elements_win_mo">Modifying a Document Element</a></li>
</ul>


<a name="getelem" id="getelem"></a>
<h3>Accessing a Document Element</h3>

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

<pre><code>/**
 * 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;
  }
}</code></pre>


<a name="create_doc_elements_win_mo" id="create_doc_elements_win_mo"></a>
<h3>Creating a Document Element</h3>

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

<pre><code>node.innerHTML = &quot;&lt;p id='myElement'&gt;&lt;/p&gt;&quot;;
</code></pre>

<a name="element_text" id="element_text"></a>
<h3>Setting Element Text</h3>

<p>Windows Mobile 5 does not support the <code>createTextNode</code> method.
To set the text content of an element use the <code>innerText</code> property
instead:

<pre><code>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));
 }
}</code></pre>



<a name="change_doc_elements_win_mo" id="change_doc_elements_win_mo"></a>
<h3>Modifying a Document Element</h3>

<p>Use the <code>innerHTML</code> and <code>innerText</code> properties
to modify an element on both Windows Mobile 5 and 6.</p>


<a name="active_x_win_mo" id="active_x_win_mo"></a>
<h2>ActiveX : Problems with setting some objects</h2>

<p>On 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 <code>expando</code> properties. This
means that you <em>cannot</em> add methods or properties to a window as
follows:</p>

<pre><code>window.myObject = new Array(); // Does not work!</code></pre>

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

<pre><code>myObject = new Array();
alert(window.myObject);       // OK!
</code></pre>

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

<pre><code>if (myObject.askQuestion) {
  myObject.askQuestion(42);
}
</code></pre>

<p> Instead, a safe way to do the same check is:</p>

<pre><code>if (isDefined(typeof myObject.askQuestion)) {
  myObject.askQuestion(42);
}
</code></pre>

<p>where the <code>isDefined</code> function is</p>

<pre><code>function isDefined(type) {
 return type != 'undefined' && type != 'unknown';
}
</code></pre>

<a name="recursion" id="recursion"></a>
<h2>Recursion</h2>

<p>Avoid recursion. 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.</p>


<a name="layout_refresh" id="layout_refresh"></a>
<h2>Layout Refresh</h2>

<p>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.</p>


<a name="msdn" id="msdn"></a>
<h2>MSDN Resources</h2>

<p>MSDN contains a lot of useful information on Windows Mobile development.
See, for example:</p>
<ul>
<li><a href="http://www.google.com/url?q=http://msdn2.microsoft.com/
en-us/library/aa454218.aspx&usg=AFrqEzcXjmzhzq-sohdSnmZf5HvhVpVfUA">
MSDN: List of HTML elements supported on Mobile 5</a></li>
<li><a href="http://www.google.com/url?q=http://msdn2.microsoft.com/
en-us/library/bb415489.aspx&usg=AFrqEzepfWZ1EzHT2iMORsLATj02bSKUAg">
MSDN: List of HTML elements supported on Mobile 6</a></li>
<li><a href="http://www.google.com/url?q=http://msdn2.microsoft.com/
en-us/library/ms879855.aspx&usg=AFrqEzf51J60jqLN8B8lIq7sXjVZy5vQcg">
MSDN: Designing Web Sites for Windows Mobile-based Devices</a></li>
<li><a href="http://www.google.com/url?q=http://msdn2.microsoft.com/
en-us/library/ms879855.aspx&usg=AFrqEzf51J60jqLN8B8lIq7sXjVZy5vQcg">
MSDN: Supported standards in Mobile 6</a></li>
<li><a href="http://www.google.com/url?q=http://blogs.msdn.com/
iemobile/archive/2007/06/20/ie-mobile-support-of-activex.aspx&usg=
AFrqEzfgFMjzal0F0B8VFpqf4Lj-JRoGmQ">
MSDN: IE Mobile support of ActiveX</a></li>
<li><a href="http://www.google.com/url?q=http://blogs.msdn.com/
iemobile/archive/2007/05/15/ie-mobile-standards-support.aspx&usg=
AFrqEzfFEBlP8G-gPeqlBb8-VSuvgLfyNg">
MSDN: IE Mobile Standards Support</a></li>
<li><a href="http://www.google.com/url?q=http://blogs.msdn.com/
iemobile/archive/2005/11/15/493200.aspx&usg=
AFrqEzc1sp97PXDpTEl6Ef5M6xUVFhZseA">
MSDN: AJAX on IE Mobile</a></li>
</ul>


<a name="env_setup" id="env_setup"></a>
<h1>Setting up a Windows Mobile Emulator</h1>

<p>There are four types of Windows Mobile device:</p>

<ul>
<li>Windows Mobile 5 Smartphone</li>
<li> Windows Mobile 5 Pocket PC</li>
<li> Windows Mobile 6 Standard </li>
<li> Windows Mobile 6 Classic/Professional</li>
</ul>

<p>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.</p>

<p> 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 
<a href="http://code.google.com/p/google-gears/" target="_top">Gears
open source project</a>. </p>

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

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

<ul>
<li>Visit <a href="http://www.google.com/url?q=http://
www.microsoft.com/windowsmobile/activesync/default.mspx&usg=
AFrqEzfYd3KVzWNioEYGA_06zJIIOX2cWg">
http://www.microsoft.com/windowsmobile/activesync/default.mspx</a> then
follow the instructions to download the installer appropriate for your
system. (You can ignore the note for the Windows Mobile Device Center: 
&quot;Your device must be connected to your PC for the Windows Mobile 
Device Center to launch after installation&quot;).</li>
<li>Run the installer. </li>
<li>Restart if prompted.</li>
</ul>

<p>2. Install the Windows Mobile 6 Emulator:</p>

<ul>
<li>Visit <a href="http://www.google.com/url?q=http://
www.microsoft.com/downloads/details.aspx?familyid=38C46AA8-1DD7-426F-
A913-4F370A65A582&usg=AFrqEzexmmJ0dZxMlfhEkIMb_8ifGGXftQ">
http://www.microsoft.com/downloads/details.aspx?familyid=38C46AA8-1DD7-
426F-A913-4F370A65A582</a> to download your required set(s) of localized 
emulator images.<br />

<strong>Note</strong>: The <code>Available locales:</code> section on the
download page lists which images correspond to which country.<br />
Download either, or both, of the following:

<ul>
<li><code>Standard</code> images for Standard devices.</li>
<li><code>Professional</code> images for Classic or Professional devices.</li>
</ul>
</li>
<li>Run the installer.</li>
</ul>

<p>3. If you are working on an XP system configure ActiveSync:</p>

<ul>
<li>Launch ActiveSync from the Start menu. </li>
<li>Select <code>File</code>, <code>Connection Settings</code> then select 
<code>Allow connections to one of the following</code> and select 
<code>DMA</code>. </li>
</ul>

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

<ul>
<li>Launch Windows Mobile Device Center from the Start menu.</li>
<li>Accept the licensing terms.</li>
<li>Select <code>Mobile Device Settings</code>, 
<code>Connection Settings</code> then select <code>Allow connections 
to one of the following</code> and select <code>DMA</code>.</li>
</ul>

<p>5. Run the Windows Mobile 6 Emulator:</p>

<ul>
<li> If not already running, launch ActiveSync <span class="note">(for
XP)</span> or Windows Mobile Device Center (for Vista).</li>
<li> Launch the Device Emulator Manager from the Start menu by selecting 
<code>Windows Mobile 6 SDK</code>, <code>Tools</code>, then 
<code>Device Emulator Manager</code>.</li>
<li> Launch the emulator from the <code>Start</code> menu by selecting 
<code>Windows Mobile 6 SDK</code>, <code>Standalone Emulator Images</code>, 
if required choose a language, then select the emulator you want to use.</li>
<li> In the Device Emulator Manager, select the running emulator (you may
need to click the Refresh button to see it), right-click then select 
<code>Cradle</code>. This will cause ActiveSync or the Windows Mobile Device 
Center to connect to the emulator: you can dismiss any pop-ups that appear. 
ActiveSync or the Windows Mobile Device Center will show a status of 
<code>Connected</code>.</li>
</ul>


</div>

</body>
</html>

Show details Hide details

Change log

r1899 by gears.daemon on Jun 06, 2008 Diff

[Author: cprince]

Change "Google Gears" -> "Gears" in the
SDK.

PRESUBMIT=passed
R=zork
CC=gears-eng@googlegroups.com
DELTA=86  (0 added, 0 deleted, 86 changed)
OCL=7374715
SCL=7375263

Go to:

Project members, sign in to write a code review

Older revisions

r1157 by gears.daemon on Mar 09, 2008 Diff

[Author: andreip]

- Adds information about gears_init.js
to http://code.google.com/apis/gears/m
obile.html
...

r1080 by gears.daemon on Feb 29, 2008 Diff

[Author: andreip]

A couple of minor changes to the
documentation.

...

r1075 by gears.daemon on Feb 29, 2008 Diff

[Author: lesleyb]

New file covering mobile specific
information.

...

All revisions of this file

File info

Size: 15846 bytes, 415 lines

View raw file