In a series of blogs you will learn about how to use PhoneGap with the new cutting edge Microsoft platforms – Windows 8 and Windows Phone 8. We will talk how to start and how to use PhoneGap with popular web client frameworks like jQuery Mobile and Infragistics Ignite UI.

What is PhoneGap?

PhoneGap (previously called Apache Callback, now Apache Cordova) is an open-source mobile development framework produced by Nitobi, purchased by Adobe Systems. It enables developers to build applications for mobile devices using JavaScript, HTML5 and CSS3, instead of device specific languages such as C# or Objective-C. The resulting applications are hybrid, meaning that they are neither truly native (layout rendering is done via web views instead of the platform's native UI framework) nor purely web-based (because they are not just web apps, but are packaged as apps for distribution and have access to native device APIs).

There are many topics about PhoneGap in iOS and Anrdoid applications and only few related to Windows 8 and Windows Phone 8. Hope that it will be interesting for developers to know why and how to use this framework with Microsoft platforms.

PhoneGap for Windows 8 Store Applications.

Windows 8 apps can be designed and coded using HTML, CSS and JavaScript just like PhoneGap apps can. And with very little effort you can use your skill and existing resources to have a modern looking Windows 8 app in no time.

PhoneGap and Windows 8 development are more similar than you realize

What you can take as an advantage when you create PhoneGap applications for Windows 8

• Your skills, assets, and probably a lot of your existing pure HTML/CSS and JavaScript code will just work in a Windows 8 application.
• You can update the look of your applications with very little effort by using the intrinsic styles for the basic HTML elements like

  and , as well as the advanced Windows 8 controls like the  app bar, date picker, flip view, and more.

  Your code that interacts with the PhoneGap API (to handle things like file access, sensors and application lifecycle events) can be updated to use the WinJS library to accomplish the same things you were doing in PhoneGap.

  Scenarios where you had to write PhoneGap plugins can be addressed by either finding the functionality in the expansive WinJS library, or by incorporating native code in a Windows 8 JavaScript app.

In this article we will talk about different ways to create Windows 8 Store applications with PhoneGap and will make a simple comparison between Windows 8 Applications with PhoneGap and those that use only WinJS

How to Create PhoneGap applications for Windows 8

There are three different ways to start with Windows 8 and PhoneGap

• To create a new Windows 8 JavaScript project and add PhoneGap references manually
• To start with PhoneGap startup project included in the distribution
• To build a PhoneGap Windows 8 template and use it in Visual Studio 2012

Create a new Windows 8 JavaScript project and add PhoneGap references manually

What you need to start:

• Windows 8
• Visual Studio 2012 Professional or better, or Visual Studio 2012 Express for Windows 8

Create a PhoneGap Windows 8 application

• Download latest PhoneGap 2.x - http://phonegap.com/download or PhoneGap project from the Github : https://github.com/phonegap/phonegap/tree/master/lib/windows8 
• Create Blank JavaScript project.
• Add “cordova-2.x.js” JavaScript file to your js folder. (Located in \lib\windows8)
• Change default.html to index.html(optional).
  Microsoft continues to use default.html as the default page for use in websites, whereas most "open web" developers use index.html. (Plus it's likely that in the other platform variants of your project you are using index.html as the name of your default page.) To fix this, in Solution Explorer rename the default.html file to index.html. Then double-click the package.appxmanifest file and change the Start page value to index.html.
• Add reference to cordova-2.x.js file from default.html/index.html page
• Adding a ’deviceready’  handler... (optional)

You can read more details here.

You could start your Windows 8 PhoneGap application from JavaScript Windows Store Blank App template

If you want to change default.html to index.html you need also change the name of the start page in the package.appxmanifest file.

It is a good practice to add a ‘deviceready’ handler to be possible let your application to know when PhoGap libraries are fully loaded.

The Cordova deviceready event fires once Cordova has fully loaded. After the device has fired, you can safely make calls to Cordova function.

Start with PhoneGap startup project included in the distribution

The official PhoneGap distribution and most of Apache Cordova source branches in the GtiHub have for each supported platform a template folder where is located a startup project. For some reasons most of distributions don’t include a ready for use Visual Studio project template but you could start your applications from a copy of this project.

Open the /lib/windows8/template folder from your distribution.

Check the settings in your package.appxmanifest  and you can continue with the development of applications with PhoneGap.

Create a PhoneGap Windows 8 template

It is more convenient if you have Visual Studio project template for Windows Store PhoneGap applications. As it was mentioned before for each supported platform there is a template folder where is located a startup project, but for Windows 8 there is not a ready for use project template. You could create a Visual Studio 2012 project template from this startup project. For Windows 8 it is located in /lib/windows8/template folder from your distribution.

Most of Cordova implementations provide CordovaBuilder project that could generate a Visual Studio 2012 project templates. Unfortunately CordovaBuilder project for Windows 8 is not updated from several months. It works correct for some implementations like this https://github.com/01org/cordova-win8  but raise exceptions in the newest versions of PhoneGap because of project structure changes. More details how to build a Visual Studio Windows Store project template with CordovaBuilder you could find here. If you are using the latest version you need to update a CordovaBuilder.cs file.

Another approach is to create your template manually.

Custom project templates require the following items

• A metadata (.vstemplate) file that Visual Studio uses to define how to display the project in the IDE and, if you have specified the appropriate properties, to customize how the project is created in the IDE.

• A project file.

• Code files such as Web forms, class files, and resource files.

In Cordova distribution you need add only a metadata file named MyTemplate.vstemplate and add a correct template settings.

A sample metadata (.vstemplate) file.

   1: <VSTemplate Version="3.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" Type="Project">

   2:   <TemplateData>

   3:     <Name>Template-Cordova2Name>

   4:     <Description><No description available>Description>

   5:     <ProjectType>JavaScriptProjectType>

   6:     <ProjectSubType>

   7:     ProjectSubType>

   8:     <SortOrder>1000SortOrder>

   9:     <CreateNewFolder>trueCreateNewFolder>

  10:     <DefaultName>Template-Cordova2DefaultName>

  11:     <ProvideDefaultName>trueProvideDefaultName>

  12:     <LocationField>EnabledLocationField>

  13:     <EnableLocationBrowseButton>trueEnableLocationBrowseButton>

  14:     <Icon>__TemplateIcon.icoIcon>

  15:   TemplateData>

  16:   <TemplateContent>

  17:     <Project TargetFileName="CordovaApp.jsproj" File="CordovaApp.jsproj" ReplaceParameters="true">

  18:         <Folder Name="www" TargetFolderName="www">

  19:           <Folder Name="css" TargetFolderName="css">

  20:             <ProjectItem ReplaceParameters="true" TargetFileName="index.css">index.cssProjectItem>

  21:           Folder>

  22:           <Folder Name="img" TargetFolderName="img">

  23:             <ProjectItem ReplaceParameters="false" TargetFileName="logo.png">logo.pngProjectItem>

  24:             <ProjectItem ReplaceParameters="false" TargetFileName="smalllogo.png">smalllogo.pngProjectItem>

  25:             <ProjectItem ReplaceParameters="false" TargetFileName="splashscreen.png">splashscreen.pngProjectItem>

  26:             <ProjectItem ReplaceParameters="false" TargetFileName="storelogo.png">storelogo.pngProjectItem>

  27:           Folder>

  28:           <Folder Name="js" TargetFolderName="js">            

  29:             <ProjectItem ReplaceParameters="true" TargetFileName="index.js">index.jsProjectItem>

  30:           Folder>

  31:           <ProjectItem ReplaceParameters="true" TargetFileName="cordova-2.3.0.js">cordova-2.3.0.jsProjectItem>

  32:           <ProjectItem ReplaceParameters="true" TargetFileName="index.html">index.htmlProjectItem>

  33:         Folder >

  34:       <ProjectItem ReplaceParameters="false" TargetFileName="package.appxmanifest">package.appxmanifestProjectItem>

  35:       <ProjectItem ReplaceParameters="false" TargetFileName="CordovaApp_TemporaryKey.pfx">CordovaApp_TemporaryKey.pfxProjectItem>

  36:     Project>

  37:   TemplateContent>

  38: VSTemplate>

More details about Visual Studio project templates you could find here.

When you are ready just zip the all content of your /lib/windows8/template folder .

Copy your zip file in your  \My Documents\Visual Studio 2012\Templates\ProjectTemplates\Language\ folder. In this case language is JavaScript.

Then open a new instance of Visual Studio 2012 and select File->New->Project you will see your project template.

When you select Template-Cordova2 item from the list you will have a Windows 8 with PhoneGap startup project.

PhoneGap vs. WinJS 

The main difference between PhoneGap and WinJS is in the API. When you need to access some device resources you need to use different APIs . For example for geolocation in Cordova you need to use navigator.geolocation.getCurrentPosition(…) function. In WinJS library you need to create an instance of Geolocator: var geolocator = Windows.Devices.Geolocation.Geolocator(); and then to call  geolocator.getGeopositionAsync().

A showLocation  function using PhoneGap

   1: function showLocation() {

   2:      navigator.geolocation.getCurrentPosition(function (location) {

   3:          $("#locationResult").innerHTML = "Latitude: " + location.coords.latitude + "
Longitude: " + location.coords.longitude + "";

   4:      }, function (err) {

   5:          $("#locationResult").textContent = "Error getting location";

   6:      }, { timeout: 30000, enableHighAccuracy: true });

   7:  }

The same showLocation  function  using WinJS

   1: function showLocation() {

   2:  

   3:      var geolocator = Windows.Devices.Geolocation.Geolocator();

   4:      geolocator.desiredAccuracy = Windows.Devices.Geolocation.PositionAccuracy.high;

   5:      geolocator.getGeopositionAsync().then(getCurPosHandler, errHandler);

   6:  

   7:  

   8:  }

Windows Store JavaScript Applications with PhoneGap

index.html code

   1: DOCTYPE html>

   2: <html>

   3: <head>

   4:     <meta charset="utf-8" />

   5:     <title>PhoneGap Demo Apptitle>

   6:    

   7:  

   8:     

   9:     <link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />

  10:     <script src="//Microsoft.WinJS.1.0/js/base.js">script>
   1:  
   2:     
   2:  
   3:      
   4:     
   2:  
   3:     
   4:     "/css/default.css" rel="stylesheet" />
   5:     
   2: 
   3:      
   4:     
Content goes here
   5:     
PhoneGap for Windows 8 - Demo
   6:      
   2:  
   3:     
   4:     "/css/default.css" rel="stylesheet" />
   5: