This is a Phone Gap  tutorial Series in which I will create a phone gap application for each of the platforms it supports. It is mostly a journey of my own that you get to follow along on.  I will start with Windows Phone and then convert it to IPhone, IPad, Android, Blackberry, Symbian. We will discuss tips and tricks along the way.

In the last post Phone Gap Tutorial #1 we looked at how to get ready to use phone gap and we created a sample project.  In this next tutorial, we are going to look at the files that were created and the differences between this and a standard windows application.

If you look at the files in the solution explorer, you will see some folders and files that are not part of the normal Windows Phone Application.We will only touch on items that differ from a normal application.

The first folder you will notice is the GapLib folder. This contains the Phone Gap dll that is specific to windows phone.  This .dll has some interesting side effects when it comes to submitting to the marketplace.  We will cover this in the next post. 

The next folder is the plugins folder. This is empty for now but you can use this to make writing phone gap applications even faster.  There are a few plugins already created for the windows phone including :

• Child Browser
• Facebook
• Live Tiles
• PGMapLauncher
• PGSocialShare

We will also discuss these further in a future post. If you want to learn more on how to create plugins you can go to the wiki here : http://wiki.phonegap.com/w/page/36752779/PhoneGap%20Plugins  or if you just want to use the current plugins you can go here : https://github.com/purplecabbage/phonegap-plugins/tree/master/WindowsPhone

The next folder (www)  is where the “Guts” of your application will go. Right now it has an index.html file, a css page and the phonegap js file.

If we peek at the index.html file we can see a simple HTML file which adds and event listener for Device ready. deviceready is an event that fires when PhoneGap is fully loaded.

The code then adds some text to the innerHTML of the welcomeMsg
(<div id=”welcomeMsg”>{It inserts it here}<div>

and then writes to the VS output window. This is useful to know for helping you debug later.

<script type="text/javascript">

        document.addEventListener("deviceready",onDeviceReady,false);

        // once the device ready event fires, you can safely do your thing! -jm
        function onDeviceReady()
        {
            document.getElementById("welcomeMsg").innerHTML += "PhoneGap is ready! version=" + window.device.phonegap;
            console.log("onDeviceReady. You should see this message in Visual Studio's output window.");

        }

      </script>

The phonegap-(insert version here).js file has some helpful comments about the order of events including the deviceready event.

/**
 * The order of events during page load and PhoneGap startup is as follows:
 *
 * onDOMContentLoaded         Internal event that is received when the web page is loaded and parsed.
 * window.onload              Body onload event.
 * onNativeReady              Internal event that indicates the PhoneGap native side is ready.
 * onPhoneGapInit             Internal event that kicks off creation of all PhoneGap JavaScript objects (runs constructors).
 * onPhoneGapReady            Internal event fired when all PhoneGap JavaScript objects have been created
 * onPhoneGapInfoReady        Internal event fired when device properties are available
 * onDeviceReady              User event fired to indicate that PhoneGap is ready
 * onResume                   User event fired to indicate a start/resume lifecycle event
 * onPause                    User event fired to indicate a pause lifecycle event
 * onDestroy                  Internal event fired when app is being destroyed (User should use window.onunload event, not this one).
 *
 * The only PhoneGap events that user code should register for are:
 *      onDeviceReady
 *      onResume
 *
 * Listeners can be registered as:
 *      document.addEventListener("deviceready", myDeviceReadyListener, false);
 *      document.addEventListener("resume", myResumeListener, false);
 *      document.addEventListener("pause", myPauseListener, false);
 */

As for the rest of the phonegap-(insert version here).js file, we will try to dip into here as we continue to build the application.

The GapSourceDictionary.xml file lists all of the HTML application resources for this project. At the application start, this XML file is read, and each file is added to isolated storage so that it can be served by the WebBrowser control. (If you have not built your project yet, you this will be blank) This is preformed by the ManifestProcessor.js file.

<GapSourceDictionary>
    <FilePath Value="www\index.html"/>
    <FilePath Value="www\master.css"/>
    <FilePath Value="www\phonegap-1.4.1.js"/>
</GapSourceDictionary>

The last piece that is PhoneGap specific is in the MainPage.xaml.  In there you will find the PGView control.  This is a control that is found in the WP7GabClassLib.dll. 

<my:PGView HorizontalAlignment="Stretch"
                   Margin="0,0,0,0"
                   Name="PGView"
                   VerticalAlignment="Stretch" />

If you wanted to see what this control is made of, you could look at it in the Phone Gap files you downloaded in this folder callback-phonegap-1.4.1-0-g0d1f305\callback-phonegap-0d1f305\lib\windows\framework

As you can see, it’s a modified WebBrowser control.

        <phone:WebBrowser x:Name="GapBrowser"
                          HorizontalAlignment="Stretch"
                          VerticalAlignment="Stretch"
                          IsScriptEnabled="True"
                          Foreground="White"
                          Navigated="GapBrowser_Navigated"
                          Loaded="GapBrowser_Loaded"
                          Unloaded="GapBrowser_Unloaded"
                          ScriptNotify="GapBrowser_ScriptNotify"
                          LoadCompleted="GapBrowser_LoadCompleted"
                          Navigating="GapBrowser_Navigating"
                          NavigationFailed="GapBrowser_NavigationFailed"
                          IsGeolocationEnabled="True" />

That’s it for this post. Now you know what is created for you when you start a new project.

In the next tutorial, we will look into how we need to modify our project to address the windows phone marketplace. (Trust me, we need to address it first) 

Other Posts in this Series

(This list will automatically grow as I write them)

• Phone Gap Tutorial #3 - Reducing the load
• Phone Gap Tutorial #2–Looking Around
• Phone Gap Tutorial #1- Getting Started

Related Posts:

• Windows Phone Database Tutorial

This is a Phone Gap  tutorial Series in which I will create a phone gap application for each of the platforms it supports. It is mostly a journey of my own that you get to follow along on.  I will start with Windows Phone and then convert it to IPhone, IPad, Android, Blackberry, Symbian. We will discuss tips and tricks along the way.

In this post, we will look at what you need to do to get started using Phone Gap using Windows Phone.  The first thing you need to do is download the Phone Gap tools.

Go to http://phonegap.com and click on the Download PhoneGap button. It is currently at version 1.41

The file will be called callback-phonegap-1.4.1-0-g0d1f305.zip (of course the number will change as new updates are applied).  It is called callback-phonegap because…. now take a breath here…. Nitobi, the company that create phone gap (at a hackathon… cool), was acquired by  Adobe who then jointly with Nitobi donated the phone gap project to the Apache Software Foundation (ASW).  This is a good thing since Adobe will continue to back the project while allowing others to continue to contribute. Now why is it called Callback you ask?  Well, the name inside ASW for phone gap is Callback….. or at least it was, it has since been changed to Apache Cordova, so I assume the file name will change soon to.

So once you have downloaded and unziped the file, you will want to navigate to \callback-phonegap-1.4.1-0-g0d1f305\callback-phonegap-0d1f305\lib\windows.  You will see many things in here, but we are only concerned with one right now. PhoneGapStarter.zip (We will talk about PhoneGapCustom.zip later).  We want to copy this to our Visual Studio Templates folder so we can create phone gap projects in Visual Studio. 

Copy the PhoneGapStarter.zip file to C:\Users\[USERNAME]\Documents\Visual Studio 2010\Templates\ProjectTemplates\Silverlight for Windows Phone

Now open up Visual Studio (This works with the full or express version) and go to File –> New Project

Select Visual C# –> Silverlight for Windows Phone

You should see a project template for PhoneGapStarter

Name Your project and hit OK.  That will create your project.

In the next tutorial, we will walk through all off the files and the set up of your New Phonegap project.

Other Posts in this Series

(This list will automatically grow as I write them)

• Phone Gap Tutorial #3 - Reducing the load
• Phone Gap Tutorial #2–Looking Around
• Phone Gap Tutorial #1- Getting Started

Related Posts:

• PhoneGap for Windows Phone
• Nokia Developer Program
• WP7 Rest … The Easy Way
• Free Windows Phone
• Live Tiles–Windows Phone Workshop