Packaging a Wakanda application with PhoneGap

Hello everyone,

While moving in the web world, the mobile environment is more and more present. Wakanda already provides several hints and methods to handle the mobile devices. But actually there is no built-in mechanism to package an application with phonegap.

I decided to work my way out and try to package a simple application to see how hard it is to do so. I’ll use Phonegap build website.

Disclaimer : This is not the official Wakanda answer to the mobile application packaging. I worked on this solution on my side to help the community to have a first solution before Wakanda provides a native solution or an official tool to package a mobile application.

Prerequesites

  • A Wakanda application with Smartphone pages already built
  • A bit of patience

Until now we won’t work anymore in the Wakanda studio, so please just close it and use an editor like notepad if you’re comfortable with, or anything else you’re use to.

Step One : prepare the WAF files

You’ll need to edit some files within the WAF.

So get to your Wakanda server installation folder.
Copy the “waLib” folder to a backup folder “walib” (please be aware of the character case), as we’ll edit some files in this folder to make this work.
Once copied, open the file at “walib/WAF/Core/Native/Rest.js” in your best text editor file.

add

WAF.core.restConnect.baseURL = "";

after the definition of WAF.core.restConnect.

Now find the definition of the go method and edit the declaration of the url variable. Change it to

var url = WAF.core.restConnect.baseURL + "";

Open Google Chrome and navigate to your application. Once loaded, open the Chrome developer tools (cmd+alt+I on mac, ctrl+shift+I on windows). Click on the settings icon at the bottom-right of the window and go to the “Overrides” panel. Once there check the “User Agent” properties and choose any smartphone in the list (e.g. iPhone – iOS5). Now refresh the page if it wasn’t automatically done.

When the page will be loaded again, close the settings window and open the network tab of the Developer tools find the “/Waf-optimize” requests and open both in a new browser tab. Copy the content of each files and paste them in “wafi-optimize.js” for the javascript content and “wafi-optimize.css” for the stylesheets. (note you can use whatever name you want, just make sure to always use the same name for the rest of the process. I’ll refer to these file later using wafi-optimize.js and wafi-optimize.css).

Now download the Loader.js file i customized to make all this work. Basically i didn’t make lot of changes in the file, all my changes have been reported to the Wakanda development team, they’ll work to integrate my recommendation to the core product after some analysis.

Step Two : Add support to CORS to your application

Now that you have all the files from the WAF needed to be able to package your application, you’ll need to add the CORS support to your application. Actually Wakanda Server doesn’t provide a native support for cross origin resource sharing. Don’t worry it’s quite easy i built what is needed to support it, even if there is some performance loss.

Navigate to my Github account and get the content of the “CORS” folder. (Should have written the readme file to explain how they work). If you already have a bootstrap file in your application, copy the content of the “bootStraps/handlers.js” file. This will handle every request made to “/cors” and redirect them to “/rest” BUT it’ll add the headers needed for browsers to allow a domain to hit yours. Place the “utils” folder in your application root folder.
If you didn’t already have a bootstrap file, just copy/paste the “bootStraps” folder inside of your application root folder, then navigate inside and right-clic on the “handlers.js” file and set it as the active bootstrap.

Please note that the “cors.js” file actually allow any domain to query your server. You may want to tune it to only allow the domains you want.

Now your application is ready to handle cross origin request to query the datastore.

Performance loss explanation : I just said you’ll face a performance loss with this CORS support because this handler will handle your request and forward them by AJAX to the “rest” location to perform what you need, and then send back the response with the headers needed to allow the cross origin request. So the performance loss is only due to a subsequent server call.

Also note that this CORS library is only for every request to the datastore REST API. It doesn’t apply to RPC services exposed by the server.

Step Three : Copy your application files to the final package location

Now copy your “Webfolder” content to the final package location, we’ll edit some files inside the final package without keeping the changes to the original files. Basically you need to copy the “waPage” folder which contains the mobile page you want to transform as an application, the application.css file, any assets folder hosting images for example and any shared scripts you use inside the page.

You may then have plenty files, but not every files will be packaged. Extract the files needed for your mobile application. (Something suffixed with -smartphone inside your .waPage folder)

You may now copy the “wafi-optimize.js” and “wafi-optimize.css” files to this final package under “scripts” and “styles” folder. Also copy my custom “Loader.js” file to the “scripts” folder.

Also copy the folder “walib” folder inside of your Wakanda server installation location to this final package. Delete any other folder than “WAF” inside this “walib” folder. Now open the “WAF” folder and delete everything except “Loader.js” (if you copied my custom Loader.js here), “widget” folder, “lib” folder and “fonts” folder.

Quite easy and fast huh? (When I’ll have some time I’ll just create some scripts to easily extract what is really needed in this walib folder)

Step Four : Make sure your application connect to the CORS enabled service

In your javascript file for your mobile application, add the two following lines at the top of the file.


WAF.core.restConnect.defaultService = "cors";
WAF.core.restConnect.baseURL = "http://wakanda_server_url:application_port";

If you have a good mind you’ll remember that we edited the “Rest.js” file to add this “WAF.core.restConnect.baseURL” property, this is meant to be able to query a remote server.

That’s all for this file (note that you can leave this in the original files, but your queries will be done to the cors location which is less performing than the rest location)

Step Five : Adapt your application to use PhoneGap and the edited WAF files

Ok we’re close to the end, but please be careful and don’t forget anything, debugging a PhoneGap isn’t as easy as debugging a desktop application.

Now rename your main html file. It should be named “index-smartphone.html”, name it “index.html”

Open the HTML file (the one we just renamed).

For now we’ll work in the “head” section of your HTML file

  1. Add the meta tag
    <meta name="WAF.config.loadJS" id="waf-optimize" content="scripts/wafi-optimize.js"/>

    before ANY other meta with the attribute name “WAF.config.loadJS”. Please make sure the content is linked to the location of the “wafi-optimize.js” file we created at Step One.

  2. Add the meta tag 
    <meta name="WAF.config.loadCSS" id="waf-optimize" content="styles/wafi-optimize.css"/>

    before ANY other meta with the attribute name “WAF.config.loadCSS”. Please make sure the content is linked to the location of the “wafi-optimize.css” file we created at Step One.

Now for all the file content, edit every urls using a relative path starting with “/” and remove this “/”.

Edit the script tag at the end of the file which source is “waLib/WAF/Loader.js” (if you did the previous step correctly there shouldn’t be a / at the beginning of the url of this file). Rename this source path to the path you placed my “Loader.js” file to.

Now add this

<script type="text/javascript" src="phonegap.js"></script>

Right after the script tag for the “Loader.js” file. Don’t worry you don’t have this “phonegap.js” file, but phonegap build will automatically push it in your application.

Step Six : Create the PhoneGap config file for your application

Create a file “config.xml” at the root folder of your final package. I’m not a phonegap expert, thus, i won’t explain this file and i’ll just paste here what i used for my test.

</pre>
<?xml version="1.0" encoding="UTF-8"?>
xmlns = "http://www.w3.org/ns/widgets"
 xmlns:gap = "http://phonegap.com/ns/1.0"
 id = "com.choisel.wakanda.phonegap.firstTest"
 version = "0.0.6">
 <name>Phonegap Test</name>

<description>
 First attempt to package a wakanda application with PhoneGap
 </description>

<author href="http://github.com/choisel" email="choisel.fogang@gmail.com">
 Choisel Fogang
 </author>

<feature name="http://api.phonegap.com/1.0/device" />

<preference name="phonegap-version" value="2.2.0" />
 <preference name="orientation" value="default" />
 <preference name="target-device" value="universal" />
 <preference name="fullscreen" value="false" />

<icon src="icon.png" />

<gap:splash src="splash.png"/>
</widget>
<pre>

Step Seven : Let’s go package

Ok seems like we’re almost at the end of this. So jump to http://build.phonegap.com. Sight it was so fun to have you with me. Create an archive of your final package folder (i think only .zip file are allowed by build.phonegap.com)

Create or use your existing Adobe ID. (You can login with your Github account too but i didn’t test this feature). You may now create a new application and upload your application package.

Note to package for iOS you’ll need to have an apple developer account and create a provisioning profile and a certificate to make the iOS packaging work.

The blackberry build will surely fail because we didn’t clean the “walib” folder and blackberry doesn’t allow more than 250 ~ 300 files. (To make this work, we should delete any file other than an image file in the “walib” folder)

Now you just have to wait for PhoneGap build to package your application for different platform and you can download it, install and test it.

Conclusion

Please don’t be hard, this is my first ever blog post, it may then doesn’t follow the common rules in blog post writing which i may not be aware of. Also my english is perfectible, I’m still working on it.

I packaged a simple application like this. With a grid to show some datas, a navigation view to be able to update, add or delete an entity. I didn’t do more tests as I’m lacking ideas to build more complex applications to test this mechanism. If you have any problem with this, please drop a comment on this page and I’ll try to help you as fast as I can.

Advertisements

Tagged: , , ,

3 thoughts on “Packaging a Wakanda application with PhoneGap

  1. CK January 29, 2013 at 7:39 am Reply

    Well done, Choisel 🙂

    • choisel January 29, 2013 at 3:04 pm Reply

      Thanks Christophe 🙂
      Hope this helps out several people until Wakanda provide a built in mechanism. I’ll soon start writing an extension to do all this work. But i’m quite busy atm so if someone’s willing to start the job, I can help. Just ask.

  2. […] If not already done, please go back and read the theoric part. […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: