Packaging Your Enyo 2 Application for Windows Phone 7.5

edited May 2012 in Packaging Apps
Getting Started
Packaging your Enyo application for Windows Phone (WP7) is a fairly straight-forward process, thanks to PhoneGap's support for the platform. For developers who are just getting started with PhoneGap/WP7, you will need to take the following steps:

1) Download the Windows Phone SDK - http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=27570
2) Download the latest PhoneGap build - http://phonegap.com/download

The next step is optional for development, however it will be necessary for installing applications on your device & submitting your application to the Marketplace

3) Register as a developer on Microsoft's App Hub - http://create.msdn.com/en-US/home/membership

Head to PhoneGap's “Getting Started” page for WP7, for instructions and links to the most current SDK & PhoneGap builds. http://phonegap.com/start#wp


Important Note: It is worth noting that the PhoneGap project is a distribution of Apache Cordova. Starting with PhoneGap version 1.5.0, the references to the name “PhoneGap” in the PhoneGap project have been changed to “Cordova”. When referencing the PhoneGap website for instructions on setting up a new application project, they may tell you to look for a reference to the name PhoneGap, when you should really be looking for the name Cordova. With that in mind, I will reference the name Cordova for the remainder of this article.
Reference: http://phonegap.com/2012/03/19/phonegap-cordova-and-what%E2%80%99s-in-a-name/


Starting a New Project
After installing the WP7 SDK and Cordova, you are ready to create your first project.

- Open Visual Studio Express for Windows Phone and select File > New Project
- Select CordovaStarter
- In the bottom area of the screen, you are able to name your project. For this article, we'll accept the default name CordovaStarter.

image



The Project Structure
When your project has been created, look at the “Solution Explorer” window on the right to view your project structure. If it is not visible by default, you can open it by selecting View > Other Windows > Solution Explorer.

The “www” folder is the folder that will contain your Cordova resource and all of your application content (Enyo, CSS, images, etc).

image



Adding Your Enyo Application to the Project
Copy your application files to the “www” folder of your project. Any required files or resources added here must be “included” into your project. Files not included in the project are not visible by default. You will have to click the Show All Files option in your Solution Explorer window.

image

If your files/folders aren't included, you will see a white icon next to its name. Right-click and select Include In Project.

image


An important thing to understand is that all of your application content must be specified as “content” in Visual Studio. When importing your application into the project, most of your files will default to “content”, however images will not. If you tried to launch your application now, you would notice that your images would not be displayed. Take the following steps to make your images viewable.


1) Select your image in the Solution Explorer window
2) Make sure the image has been included in the project (as described above)
3) In your Properties window (View > Other Windows > Properties Window), go to the Build Action drop-down list and select Content

image




Enyo & Cordova
Now that your project is set up and your application has been included, it's important to understand the relationship between Enyo and Cordova.

When your application is first launched, Codova will send a “deviceready” event to the document body. This event tells us that the application has been launched and Cordova has been loaded. It is at this point, where we can use Enyo to render our application. Fortunately, Enyo 2 has added native support for listening to this event.

If you are using the latest Enyo 2 build in github ( https://github.com/enyojs/enyo ), you already have the needed file for this ability (enyo/source/dom/phonegap.js).

If you are using the recent public release (Enyo 2.0 beta 4), you will need to download the support package, found in the enyojs/extra repo ( https://github.com/enyojs/extra ). Then you will need to be sure to include that package in your application:
Enyo 2 uses its “enyo.Signals” kind, in order to listen for when Cordova is ready to render our application. To do this, we need to add an Enyo listener to our document body.

    
        // tell enyo to listen for deviceready event
        enyo.dispatcher.listen(document, "deviceready");
        
        new App().renderInto(document.body);
    

* Note that we must use App().renderInto(document.body) instead of App.write().


In order to respond to the event we have a listener for, we must add a “enyo.Signals” kind to our application.
enyo.kind({
	name: "App",
	components: [
		{kind: "Signals", ondeviceready: "deviceReady"},
		{content: "Hello world!"}
	]
});



Building and Deploying to the Emulator
Now that we have made the changes needed in our application, we are ready to build and deploy it to the emulator, for testing and debugging.

1) In Visual Studio, make sure the Windows Phone Emulator option is selected in the drop-down menu at the top of your screen.
2) Click the green play button (or press F5), found directly to the left of the drop-down menu mentioned in step 1.

image


Your application should now successfully launch in the Windows Phone Emulator. Congrats!

image


Quirks
When developing javascript applications for Windows Phone 7.5, there are certain pain-points that you will need work through. I address some of these issues on another forum thread: http://forums.enyojs.com/discussion/454/windows-phone-7-5-quirks

Comments

  • Great guide, I'll definitely try this out later.

    Also I came to this via WindowsPhoneGeek who have already posted an article about it: http://www.windowsphonegeek.com/news/Packaging-Your-Enyo-2-Application-for-Windows-Phone

    Nice work!
  • I just went through this process a few weeks ago..

    Nice guide. Pretty much covered everything.
  • I wonder what happened to the "deviceReady" function? It's connected to the event but where is it defined? Could someone put an example project for WP7 somewhere with complete file structure?

    thx
    Henk
  • edited June 2012
    Ok, if you do it right, it works :)

    Here comes my index.html which works for me.
    <!DOCTYPE html>




    Math This! // provide our own console if it does not exist, huge dev aid! if (typeof window.console == "undefined") { window.console = {log:function(str){window.external.Notify(str);}}; } // output any errors to console log, created above. window.onerror = function(e) { console.log("window.onerror ::" + JSON.stringify(e)); }; console.log("Installed console ! "); function onDeviceReady(e) { console.log(device.platform); console.log("deviceready event fired!"); // our kind is reusable console.log("new MathThis().write()"); new MathThis().renderInto(document.body); } PhoneGap.addConstructor(function() { console.log("PhoneGap.addConstructor is working"); }); document.addEventListener("deviceready", onDeviceReady, false);
  • (fixed your code to use the pre/code tags properly)
  • @MetaView Your example works, as it is standard PhoneGap/Cordova code (which will then negate your "lib/extra/phonegap.package.js" reference). However, the suggested method for handling PhoneGap events in Enyo is via "enyo.Signals", as the guide states. This way, all event handling is contained within Enyo and also keeps your code cleaner.

    Q:"I wonder what happened to the "deviceReady" function?"
    The short answer is: you don't need to define it.

    Enyo's "Signals" automatically handles the generation of your application's content when it receives the "deviceready" event sent by PhoneGap. You listen for this with:
    enyo.dispatcher.listen(document, "deviceready");

    You are still able to access the deviceReady function if/when you need to do something specific - like listening for the device hardware's "back" button.

    Here is an example of a full, basic application.
    <!DOCTYPE html>



    App // Application enyo.kind({ name: "App", components: [ { kind: "Signals", ondeviceready: "deviceReady", onbackbutton: "backButtonPressed" }, { kind: "enyo.Button", style: "width:240px; height:70px; background-color:lightblue;", content: "Button", ontap: "showOutput" }, {name: "output"} ], deviceReady: function() { enyo.dispatcher.listen(document, "backbutton"); }, backButtonPressed: function(inSender, inEvent) { this.showOutput(inSender, inEvent); }, showOutput: function(inSender, inEvent) { this.$.output.setContent("Event triggered by: " + inSender.name); } }); // tell enyo to listen for deviceready event enyo.dispatcher.listen(document, "deviceready"); new App().renderInto(document.body);
  • Thank you for the clarification, will try it out next time. BTW: the app I'm porting right now ("Math This", a simple canvas based pairs-finding game) is quite slow on my Lumia 800. On webOs is much faster.
  • No problem. Coincidentally, I previously worked on some canvas demos and found a canvas-related WP7 bug that you may want to look out for. This issue seems to affect builds earlier than 7.10.8107 - so most consumer/branded devices are affected.

    Pressing the power button to turn off the screen (when your app is active and canvas elements are drawn) can cause certain canvas elements to completely disappear. When turning the screen back on, you may see things missing. I couldn't reproduce it 100%, but it was often.

    I was able to "fix" it by listening for PhoneGap's "onresume" event, then re-drawing my elements.
  • What do I do if I want to run my deviceReady code but am testing the application on Chrome? The deviceReady signal doesn't appear to be triggered.
  • For testing you can simply fire the deviceReady event manually:
    setTimeout(function() {
    	var evt = document.createEvent('HTMLEvents');
    	evt.initEvent('deviceready', true, true);
    	document.dispatchEvent(evt);
    }, 1000);
Sign In or Register to comment.