Phone Gap Tutorial #3 – Reducing the load


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 #2 we looked at everything that was created for us when you start a project for Windows Phone from scratch. As I said in that post :

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.

In this post, we will discuss those issues and show you want you need to do to get around them.

If we look at the Solution Explorer we can see that there is a folder with the WP7GapClassLib.dll which is all the code of . We can also see that there is a reference to it as well.

image

Normally, this would be fine but with Windows Phone and the Windows Phone marketplace, the source code from phone camp contains information on ALL the capabilities.  (Since this is what does, it connects your HTML to the native capabilities). Normally this would be great, but since during the Marketplace verification process it will detect capabilities and list them to the users who will download your application, we don’t want that.

Why don’t you want that?   Well, its simple, if you are writing an app that DOES NOT use contacts, or the phone dialer, or the camera, etc… you don’t want the marketplace to say you do because some users may stay away from your application because you pull to much of their data.

So how do you fix this?  Its easy.   First we remove the reference to WP7GapClassLib (Right click –> Remove), and delete the GabLib Folder

 

image

Next we want to add another project to this solutions.  (Right click on Solution in Solution Explorer –> Add Existing Project) and navigate to where you downloaded in the \lib\windows\framework folder.

image

You will notice that there are 2 projects in here

  • WP7GapClassLib.csproj (This is the one with the FULL Source- we DON’T want this (see above))
  • WP7GapClassLibBare.csproj (This contains the bare minimum for ))  SELECT THIS ONE

 

Then add a reference to this project from your project (Right click on references –> Add Reference –> Projects Tab)

image

If you build and run the project, everything should run fine. BUT at this point you don’t have access to any of the capabilities of the native phone from you HTML.

To show you this simply, we will try to use the camera from our HTML 5 (Example borrowed from )

First add a call to getPicture to the onDeviceReady() method.

 

navigator.camera.getPicture(onSuccess, onFail, { quality: 50 }); 
 

Next, add the onSuccess and onFail methods we pointed to in the getPicture method.

function onSuccess(imageData) {
            var image = document.getElementById('myImage');
            image.src = "data:image/jpeg;base64," + imageData;
        }
        function onFail(message) {
            navigator.notification.alert('Failed because: ' + message); 
         }

 

Next, in the same document (in the body section), we will add a link that will call the showAlert() function.  

If you try to run this project now, it wont work. And if you look in your Output window, it will show the following.

image

And you should also get an alert in the emulator (from the onFail function)

image

That is because since we are only using the WP7ClassLibBare project, we need to add this functionality in if we want to use it. (This is what we want, add ONLY the capabilities that we need)

Right click on the Plugins Folder and select Add Existing Item.

Navigate to where you donwloaded phonegap and go to the \lib\windows\framework\PhoneGap\Commands folder.

 

image

Select camera and choose Add As Link.

Now run the code and you will see you have access to the camera. 

Now since we are not using the camera in this application right now, we are not doing anything special with this code. This was just to show you what you will need to do going forward to add functionality to your phonegap application as you build it.

In the next tutorial, we will begin to build the pages in our application and talk about making it METRO.

Other Posts in this Series

(This list will automatically grow as I write them)

[catlist name=phone-gap-tutorial]


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.

image

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 : 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 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)  Smile

Other Posts in this Series

(This list will automatically grow as I write them)

[catlist name=phone-gap-tutorial]


Phone Gap Tutorial #1- Getting Started


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 this post, we will look at what you need to do to get started using using Windows Phone.  The first thing you need to do is download the tools.

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

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 (at a hackathon… cool), was acquired by  Adobe who then jointly with Nitobi donated the 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 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 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

image

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)

[catlist name=phone-gap-tutorial]