Porting the HTML5 Samples to Windows 8* Store

Table of Contents

  1. Introduction
  2. Steps on Porting
  3. Creating a HTML5 App with Visual Studio 2012*
  4. Required Files
  5. Specifying Device Features Needed by the HTML5 Sample
  6. Directory Structure and Testing HTML5 Samples with Visual Studio 2012
  7. Issues Encountered

Introduction

This article is intended for beginner HTML5 developers to port the HTML5 samples provided by the Intel(R) HTML5 Development Environment. You can get started here: http://software.intel.com/en-us/html5.
We have ported HTML5 samples to Windows 8* Store:

At the time of the writting PhoneGap Build* does not support Windows 8 Store yet.

Steps for Porting

Porting a HTML5 app to Windows 8* store app is not difficult if the app has been ported to Internet Explorer* 10 (IE10) already. It could be a time consuming task for getting the app working on all browsers. The steps for porting the HTML5 samples we used are:

  1. Porting the sample to IE10 first
    Check what features are supported by IE10 by browsing to "http://html5test.com/" in IE10 and understand where your app might be facing issues.
    Please see the Tips section on what we have encountered.
  2. Creating a Blank JavaScript App with Visual Studio 2012*
    We used Visual Studio 2012 express edition on a Windows 8 machine. Please refer to Microsoft MSDN Get the tools (Windows Store apps) for detailed information about the tools.
  3. Adding the files to the Blank JavaScript Project
  4. Setting the correct device features
  5. Testing

Creating a HTML5 App with Visual Studio 2012

Here are the steps for creating a HTML5 sample app on Windows 8:

  1. Create an new JavaScript "BlankApp" project
    It creates a JavaScript project with empty content and lots of default files.
  2. Rename "default.html" to "index.html"
    "default.html" is the entry page created by default. Changing the name with right click on the file and select "rename".
  3. Set "start page" to "index.html" for the package
    Double click on file "package.appxmanifest" and it opens with manifest editor; change the "Start page" from "default.html" to "index.hmtl":
    start page name
  4. Rename folder "images" to "win8-images" and update the following images with the HTML5 sample's images
    • logo.png
    • smalllogo.png
    • storelogo.png
    • splashscreen.png
  5. Remove the files not needed: default.css & default.js
  6. Copy the files from HTML5 sample to the project root directory
  7. Add the files from HTML5 sample:
    This takes time because all the folders and files have to be added in order to be packaged.
  8. Click on run on "Local Machine" or "Simulator" to test

This MSDN page Create your first Windows Store app using JavaScript might be useful to you.

 

Required Files

Building the Windows 8 store app has certain requirements. The full checklist for submitting an app is located on this msdn page.

During developing and testing time the must-have files are the 4 logo image files:

image file name

required image size

logo.png 150 x 150px
smalllogo.png 30 x 30px
storelogo.png 50 x 50px
splashscreen.png 620 x 300px

But if you start from the project types provided by Visual Studio 2012, it creates those image files with the required size by default.

Specifying Device Features Needed by the HTML5 Sample

Device features for the Windows 8 Store app are declared in "package.appxmanifest". This file is created by default with Visual Studio 2012. The device feature categories of the Windows 8 store app are different comparing to PhoneGap's feature categories. So you need to carefully map them from PhoneGap's "config.xml" to "package.appxmanifest".
The following screen shot shows the device feature list in Visual Studio 2012:
start page name
The following is all the device features used in PhoneGap's "config.xml":

<!-- If you do not want any permissions to be added to your app, add the
    following tag to your config.xml; you will still have the INTERNET
    permission on your app, which PhoneGap requires. -->
<preference name="permissions" value="none"/>

<!-- to enable individual permissions use the following examples -->
<feature name="http://api.phonegap.com/1.0/battery"/>
<feature name="http://api.phonegap.com/1.0/camera"/>
<feature name="http://api.phonegap.com/1.0/contacts"/>
<feature name="http://api.phonegap.com/1.0/file"/>
<feature name="http://api.phonegap.com/1.0/geolocation"/>
<feature name="http://api.phonegap.com/1.0/media"/>
<feature name="http://api.phonegap.com/1.0/network"/>
<feature name="http://api.phonegap.com/1.0/notification"/>

For example, the HTML5 audio sample that records and plays back, the "package.appxmanifest" should contain:

  • Microphone
  • Music Library

For PhoneGap "config.xml" only following is needed:

  • <feature name="http://api.phonegap.com/1.0/media"/>

Directory Structure and Testing HTML5 Samples with Visual Studio 2012

Because it takes time to add all the folders and files to the projects. So we have included the Visual Studio 2012* project files for your convinience in those HTML5 Samples that are ported to Windows 8 Store. The directory structure is like below:
start page name

To build it with Visual Studio 2012 for Windows 8 Store:

  1. Copy the project files under win8-proj to the root folder
  2. Load *.jsproj with Visual Studio 2012, and run from the IDE

Issues Encountered

  1. During our porting to IE10, most issues we encountered are css gradient related. i.e. adding "-ms-linear-gradient" in following case:
    		    background: -moz-linear-gradient(top,#7A987E 0%,#000000);
        background: -webkit-gradient(linear, left top, left bottom, from(#7A987E),to(#000000));
        background: -ms-linear-gradient(top, #7A987E, #000000);  /* IE10 */
    
    		
  2. The next issue is specific to jQuery-1.8.x.js. If using the normal jQuery from "http://jquery.com/download/", you will see the error below from Visual Studio 2012:
    HTML1701: Unable to add dynamic content .... A script attempted to inject dynamic content, or elements previously modified dynamically, that might be unsafe. For example, using the innerHTML property to add script or malformed HTML will generate this exception. Use the toStaticHTML method to filter dynamic content, or explicitly create elements and attributes with a method such as createElement. For more information, see "http://go.microsoft.com/fwlink/?LinkID=247104".
    start page name
    We encountered this issue with "jqm-springboard-nav" sample. The version of jQuery to use for Windows 8 Store app can be downloaded from "https://github.com/appendto/jquery-win8". In "jqm-springboard-nav" sample we used the following code:
    		    <script>
        function includeJavaScript( url ){
            var tag = document.createElement( 'script' );
            tag.type = "text/javascript";
            tag.src = url;
    
            // Insert it to the <head>
            document.getElementsByTagName("head")[0].appendChild( tag );
        }
        </script>
    
        <!-- note: use jquery-1.8.0.min.js & jquery.mobile-1.1.1.min.js for production -->
        <script>
    	if (deviceCheck.windows8) {
    	    includeJavaScript("vendor/jquery/jquery-1.8.2-win8-1.0.js");
    	}
    	else {
    	    includeJavaScript("vendor/jquery/jquery-1.8.0.js");
    	}
        setTimeout(function(){
        	includeJavaScript("vendor/jquery.mobile/jquery.mobile-1.1.1.js");
    		includeJavaScript("app/springboard.js");
            }, 100);
        </script>
    
    		

But when porting the Counting Beads HTML5 sample, there are more issues because the app originally only works on Chrome. You can see all the porting details of Counting Beads sample on this article.

For more complete information about compiler optimizations, see our Optimization Notice.