Phone Gap Tutorial #2–Looking Around

This is a   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 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 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 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 :  or if you just want to use the current plugins you can go here :

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">


        // 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.");


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.

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


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" 
                   VerticalAlignment="Stretch" />

If you wanted to see what this control is made of, you could look at it in the 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" 
                          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)  Smile

Other Posts in this Series

(This list will automatically grow as I write them)

[catlist name=phone-gap-tutorial]