how to create html5 apps on windows phone with phonegap

7/30/2019 How to Create HTML5 Apps on Windows Phone With PhoneGap

http://slidepdf.com/reader/full/how-to-create-html5-apps-on-windows-phone-with-phonegap 1/13

3/29/13 How to create HTML5 apps on Windows Phone with PhoneGap

msdn.microsoft.com/en-us/hh771462.aspx 1/13

How to create HTML5 apps on Windows

Phone with PhoneGap

By David Rousset

We will first see in this article what the added values of PhoneGap for HTML5

applications are. We’ll then discover how to create our very first project where

we will retrieve the accelerometer’s values from our JavaScript code. At last, we

will review a complete HTML5 gaming sample almost ported as-is to PhoneGap

to use the accelerometer available on the Windows Phones.

1. Introduction

2. PhoneGap: a framework filling the gap

3. Let’s create our first PhoneGap project

4. Getting the accelerometer’s values from Jav aScript

5. Re view of a complete sample with the HTML5 Platformer game

1. Forcing the landscape orientation

2. Handling various resolutions3. Loading the levels with calls to the file system instead of using XHR

4. Modification of the gameplay to use the accelerometer

5. Screenshots of the result and FPS on some phones

6. Complete Visual Studio Solution to download

6. Conclusion

Introduction

The Mango update for Windows Phone came with the support of HTML5

thanks to the embedded IE9 browser. As the desktop version, the mobile

version of IE9 delivers hardware acceleration through the GPU of your Windows

Phone. Thus, combined with JavaScript, IE9 can now serve as a base of

interesting user’s experiences usually reserved to “native code”.

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#conclusion

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#html5platformer

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#accelero

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#firstproject

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#phonegap

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#conclusion

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#html5platformer

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#accelero

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#firstproject

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#phonegap

http://blogs.msdn.com/b/davrous/archive/2011/12/23/tutorial-how-to-create-html5-applications-on-windows-phone-thanks-to-phonegap.aspx#introduction





The Pros of using HTML5 as a development platform is a relative promise to

easily re-use parts of the code on others compatibles platforms like Android or

iOS. HTML5 has then driven a lot of interests from the mobiles developers’ecosystem during the last months.

However, even if the HTML5/CSS3/SVG & JavaScript specifications have greatly

evolved during the last months, they still lack some major features to build

mobile applications. Indeed, a phone or a tablet exposes specific capabilities

like: GPS, accelerometer, camera, sending SMS, accessing contacts, etc.

To have access to these capabilities from the JavaScript code, the W3C has been

working now for a while on what we call “ Device APIs [1]” or DAP.

Unfortunately, we can consider that no implementation currently exists of

those specifications as this document seems to confirm: Standards for Web

Applications on Mobile: November 2011 current state and roadmap [2] . Mozilla

has started an interesting work by more or less forking those specifications via

what they call Web APIs [3] to support their Boot To Gecko [4] project. This is

then a good news as a form of implementation seems to start with an on-going discussions with the W3C. However, even if things start to move slowly, we will

probably have to wait for several years before having a stable official W3C

specification implemented widely on all platforms.

So the question is: what should we do in the meantime? Can HTML5 really

address those scenarios?

PhoneGap: a framework filling the gap

While waiting on real standardized specifications, we don’t have the choice: we

http://hacks.mozilla.org/2011/07/announcing-boot-to-gecko-b2g-booting-to-the-web/

http://hacks.mozilla.org/2011/08/introducing-webapi/

http://www.w3.org/2011/11/mobile-web-app-state.html

http://www.w3.org/2009/dap/





need to create some bridges between JavaScript and the native code of the

targeted platform to have access to its capabilities. The idea is then the

following one: taking the native languages of each platform (C#, Objective-C

and Java) and creating a framework with these languages that will expose

interfaces to the JavaScript developer.

This is exactly what PhoneGap [5] is doing. Let’s take the Windows Phone case

which is the main topic of this article. A Windows Phone’s PhoneGap project is

simply a Silverlight application hosting the WebBrowser control (and thus IE9)

as well as a Silverlight Assembly written in C# which does the job to access to

the accelerometer, GPS, contacts, camera and so on. In this way, as a JavaScript

developer, you will use a DLL named WP7GapClassLib.dll (the PhoneGap core

runtime) without even knowing it via the usage of the code embedded in the

phonegap-1.3.0.js file. This DLL contains some C# code which does calls to the

Silverlight runtime available on the phone. As the runtime has access to all the

capabilities of the phone, the JavaScript will do also. The JavaScript library will

then act as a gateway between both worlds. Moreover, the good point of using

this library is that your code will most of the time works as-is on the PhoneGap

versions of Android or iOS. PhoneGap offers then an interesting form of

portability.

http://phonegap.com/





Please note by the way that the PhoneGap support for Windows Phone is now

totally complete since the recent 1.3.0 version:

At last, PhoneGap offers also another interesting service. It embeds your .js,

.css, .html, .png resources inside its projects to package it as a classical

application. In summary, you can use PhoneGap to package your HTML5

application for the various applications' stores. This is for instance the case of

the SujiQ Windows Phone application [6] built using this approach.

Let’s create our first PhoneGap project

Prerequisites

Here are the very first steps you need to follow:

1. Download the Windows Phone SDK: Windows Phone SDK [7]

2. Download the last version of Phone (1.3.0 today) on their site:

http://phonegap.com/ [8]

3. Unzip the downloaded file

http://phonegap.com/

http://create.msdn.com/en-us/home/getting_started

http://www.windowsphone.com/en-US/apps/09dc9317-0f63-4a98-9042-47c7976b2d88





4. Copy the PhoneGapStarter.zip and PhoneGapCustom.zip files into

\Documents\Visual Studio 2010\Templates\ProjectTemplates

File->New project

Once the previous steps are done, you will be able to create your first PhoneGapproject. Start Visual Studio 2010, select the “Visual C#” templates and filter

them via the “Gap” keyword. You should then see a new type of project named

PhoneGapStarter:

Name your project “ MyFirstPhoneGapProject ”. Once done, you will find the files I was talking about before in the Solution Explorer:

You just now have to insert your HTML5 application into the “www” directory.

Here are several tips I’d like to share with you about this default project

template:

never ever touch thephonegap-1.3.0.js file if you’d like to keep a portable

code on other versions of PhoneGap

all files you will add inside the “www” directory must be set as “Content” in

the properties window





instead of the WP7GapClassLib.dll binary file, you

can add a reference to the WP7GapClassLib.csproj

C# project available in the “Windows

Phone\framework” directory of the downloaded

PhoneGap archive. It will help you debugging or

discovering the native code of the PhoneGap

library if needed.

Ok, let’s now start by doing something normally

impossible by default with IE9 Mango: accessing

to the accelerometer’s values from JavaScript.

Getting the accelerometer’s values from JavaScriptWe’re going to see here how to get the values sent back by the accelerometer (of

the emulator or the real device) in a very simple way.

Open the “index.html” page and change its default body by this one:

We will simply use 3 <div> tags to display the current X, Y & Z values of the

accelerometer.

Next step is to change the last default <script> block by this one:

Well the code is relatively self-explicit I think. The very first thing to note is

that you need to wait for the “deviceready ” event raised by PhoneGap to be

sure to be in a stable state. You then need to subscribe to this event. In our case,

we will be call-backed into the OnDeviceReady() function. This function is

getting the references to the 3 <div> tags and then asks to be notified by any changes done inside the accelerometer every 500ms with the startWatch()

function. The notifications will be sent to the onSuccess() function that will

have access to the acceleration object containing the x, y & z values. You’ll find

the complete documentation on the PhoneGap site: PhoneGap Documentation

- API Reference - Accelerometer

This is all you need to do on the JavaScript side. However, to make it works, you

need to specify in the project’s properties that you want to request access tothe device’s sensor. The capabilities needed for the proper execution of our

application are listed inside the WMAppManifest.xml file available in the

“ Properties” directory. By default, since 1.3.0, PhoneGap is listing the strict

http://docs.phonegap.com/en/1.2.0/phonegap_accelerometer_accelerometer.md.html#Accelerometer





minimum capabilities:

It’s then up to you to add the capabilities you need for your PhoneGap

application. In our case, we need to add this line:

To be allowed to access to the accelerometer. You’ll find the complete list of all

available capabilities here: Application Manifest File for Windows Phone

Ok, we’re logically ready to test that inside the emulator as a first phase. Press

on the magical “F5” key and let’s have a look to the result:

By moving the virtual phone in the emulator on the right, you should see the

values of the accelerometer updated. Congratulations!

You can download the complete source code of this first solution here:

http://david.blob.core.windows.net/html5/MyFirstPhoneGapProject.zip [9]

Issues with phones using French locale

If you’re testing the very same code on your phone configured to use a French

local (as mine for instance! Description: Clignement d'œil), you will have thefeeling that the application doesn’t work at all… which is indeed the case. I’ve

then spent some time debugging the code and I’ve discovered that the following

exception was raised inside phonegap-1.3.0.js:

http://david.blob.core.windows.net/html5/MyFirstPhoneGapProject.zip

http://msdn.microsoft.com/en-us/library/ff769509(v=VS.92).aspx#BKMK_Capabilities





"Error in success callback: Accelerometer = Syntax error"

After dumping the values, I’ve seen that the error was due to a tentative of de-

serialization of the following bad formatted JSON string:

"{\"x\":0,00472,\"y\":-0,19879,\"z\":-0,98115}" whereas the proper EN-US is

the following one: "{\"x\":0.00472,\"y\":-0.19879,\"z\":-0.98115}"

Yes, we’re using a coma in France as a numeric separator. Description:

Clignement d'œil

2 solutions to solve this problem:

1. The lazy one: switch your phone into EN-US (I know, this is not a solution!)

2. Fix the problem that comes from the C# code. For that, replace the following code from the Accelometer.cs file of the WP7GalClassLib library:

By this one:

And the sample will now work with all locales. I’ve filled a bug on this topic

here: https://issues.apache.org/jira/browse/CB-141 [10] suggesting the same

solution that will normally be shipped with the next version (2.0.0).

By the way, you’re maybe wondering how I’ve managed to debug the JavaScript

part of my PhoneGap project? Well, you can simply use the wonderful

jsConsole project. If you want to know more about that, please read one of my

colleague’s article: jsConsole Remote Debugging in IE9 on Windows Phone

Mango [11]

Review of a complete sample with the HTML5 Platformergame

Let’s now review a more complex sample. My idea was to start from the game

I’ve written before. It’s exposed in this article: HTML5 Platformer: the complete

port of the XNA game to <canvas> with EaselJS [12] . I wanted to see what I

should do to make it works on the phone.

First step is to simply copy/paste the different .js, .png, .css files into the “www”

directory and to mark them as “Content”. Here are the others steps to follow.

http://blogs.msdn.com/b/davrous/archive/2011/09/09/html5-platformer-the-complete-port-of-the-xna-game-to-lt-canvas-gt-with-easeljs.aspx

http://bristowe.com/blog/2011/6/8/jsconsole-remote-debugging-in-ie9-on-windows-phone-mango.html

https://issues.apache.org/jira/browse/CB-141





Forcing the landscape orientation

The game has to be played in landscape mode. I’ve then forced this orientation.

I’ve also remove the information bar on the side (the System Tray). For that,

you need to open the Main Pa ge.xa ml file and change these properties:

Handling various resolutions

As my main goal was to build a game that could run on the highest number of

devices, I need to handle a lot of different resolutions.

For that, I’ve slightly modified the initial code of the Platformer you can

download in the other article [13]. The game is now capable on running at any

resolution by applying a rescale ratio on the images and sprites to draw.Everything is being redrawn based on a specific ratio that came from the

Windows Phone (800x480) which is the 100% ratio. You can test this version in

your desktop browser here: HTML5 Platformer ReScale [14] and try to

dynamically resize the browser window. Moreover, if your screen resolution has

a 16/9 aspect ratio, press the F11 key to play in fullscreen! The experience in

this mode is really cool as you can see in this screenshot:

We’re letting the browser taking care of the anti-aliasing during this scaling

operation. Based on the browser you’ll use, you will notice also that the

performance could vary a lot related to the size of the window you’ll have. On

my machine, IE9/IE10 seems relatively indifferent to the fullscreen mode or

http://david.blob.core.windows.net/html5platformerscale/index.html

http://blogs.msdn.com/b/davrous/archive/2011/09/09/html5-platformer-the-complete-port-of-the-xna-game-to-lt-canvas-gt-with-easeljs.aspx





small resolutions by maintaining a stable 60 fps framerate.

Loading the levels with calls to the file system instead of using XHR

In the initial code, the .TXT files linked to the each level were stored on the webserver and downloaded via XmlHttpRequest calls. As we’re now running

everything client-side in offline mode, XHR local calls are not very

appropriated. I’ve then replaced the initial code of the

PlatformerGame.prototype.LoadNextLevel function by this one:

I’ve just re-used the code available in the PhoneGap documentation: FileReader

. As you can see, you have a full access to the Windows Phone file system from

JavaScript with PhoneGap.

Cool tip: to help you debugging what’s really stored in the Isolated Storage of

the phone or not, you should have a look to this awesome tool: IsoStoreSpy [15]

written by Samuel Blanchard.

Modification of the gameplay to use the accelerometerWell, last part is just to mix all parts of this article to obtain the final result. For

that, I’ve added the following code into the constructor of the Player object in

the Player.js file:

Here is the function that will be call-backed during the accelerometer

variations:

I’ve also added an handler on the “onmousedown ” event on the canvas to jump

when the user tap on the screen.

Screenshots of the result and FPS on some phones

First, let’s review the result within the Windows Phone emulator:

http://isostorespy.codeplex.com/

http://docs.phonegap.com/en/1.3.0/phonegap_file_file.md.html#FileReader





We have a framerate varying from 54 to 60 fps on my machine. On a real device,

the framerate differs logically between models. Let’s take the first game level.On the LG E900, the framerate is around 22 fps. On the HTC Radar, it’s around

31 fps. On the Nokia Lumia 800, it’s around 42 fps.

The gameplay could then be not very convincing in most cases. Indeed, I’m

using a fullscreen canvas to draw the whole game. This is not a very good idea

for the mobile limited power CPU, even if the Nokia seems powerful enough tohandle this approach. A better methodology could be to cut the screen stage

into various little canvas that will then be moved by modifying the CSS





properties on them. This is what has been done for the HTML5 version of Angry

Birds for instance. Some JS gaming frameworks start to think about handling

this complexity for you. The idea would then be to code the game once with

high level APIs and the framework could switch between a full frame canvas or

various little canvas moved via CSS based on the performance.

Well, you’ll get it: the HTML5 gaming experience on mobile is currently just at

its beginning. But its future looks very promising!

Complete Visual Studio Solution to download

You’ll find the complete source code of the HTML5 Platformer for

PhoneGap here: HTML5GapPlatformer.zip [16]

Other useful resources

Conclusion

PhoneGap offers interesting perspectives to help you writing applications on

the phone. It lets you using your existing skills in JavaScript, HTML and CSS.

PhoneGap won’t necessary cover all the scenarios currently available with the

native development stack (Silverlight or XNA). But this could be something to

have a look to if you’d like to capitalize on the HTML skills of one of your team.

You will have to pay attention to properly identify the kind of project to work

on.

You can also think about mixing both environments to create hybrid

experiences: the main branch would be written using “HTML5” and some

specific parts into native code. Using this idea, some plug-ins have been created

to push a bit further the integration into the Windows Store app UI: PhoneGap

Plug-ins for Windows Phone [17] . You’ll find for instance one of them allowing

a JavaScript code to update the Tiles.

At last, PhoneGap and HTML5 could allow a relative portability to other

platforms…

with some limitations. But this is a vast subject with passionatedebates that would need a complete dedicated article.

https://github.com/purplecabbage/phonegap-plugins/tree/master/WindowsPhone

http://david.blob.core.windows.net/html5/HTML5GapPlatformer.zip




1. http://www.w3.org/2009/dap/

2. http://www.w3.org/2011/11/mobile-web-app-state.html

3. http://hacks.mozilla.org/2011/08/introducing-webapi/

4. http://hacks.mozilla.org/2011/07/announcing-boot-to-gecko-b2g-booting-to-the-web/

5. http://phonegap.com/

6. http://www.windowsphone.com/en-US/apps/09dc9317-0f63-4a98-9042-47c7976b2d88

7. http://create.msdn.com/en-us/home/getting_started

8. http://phonegap.com/

9. http://david.blob.core.windows.net/html5/MyFirstPhoneGapProject.zip

10. https://issues.apache.org/jira/browse/CB-141

11. http://bristowe.com/blog/2011/6/8/jsconsole-remote-debugging-in-ie9-on-windows-phone-mango.html

12. http://blogs.msdn.com/b/davrous/archive/2011/09/09/html5-platformer-the-complete-

port-of-the-xna-game-to-lt-canvas-gt-with-easeljs.aspx

13. http://blogs.msdn.com/b/davrous/archive/2011/09/09/html5-platformer-the-complete-

port-of-the-xna-game-to-lt-canvas-gt-with-easeljs.aspx

14. http://david.blob.core.windows.net/html5platformerscale/index.html

15. http://isostorespy.codeplex.com/

16. http://david.blob.core.windows.net/html5/HTML5GapPlatformer.zip

17. https://github.com/purplecabbage/phonegap-plugins/tree/master/WindowsPhone

18. http://blogs.msdn.com/b/davrous/

About the Author

David Rousset is a Developer Evangelist at Microsoft, specializing in HTML5 and

web development. Read his blog [18] on MSDN or follow him @davrous on

Twitter.

http://twitter.com/#!/search/@davrous

http://blogs.msdn.com/b/davrous/