Tuesday, June 5, 2012

Converting the jQuery Mobile Calculator to PhoneGap



PhoneGap, now known as Apache Cordova, makes it amazingly easy to turn your jQuery Mobile web application into a mobile device application. So let me show you how to turn the JQM Calculator into an Android app. I am not going to cover how to set up the Android SDK and Eclipse, that is way too much work plus there are plenty of tutorials already covering that. Instead we will start by assuming that you have the Android SDK set up, have the JQM Calculator code available, and have downloaded the latest version of PhoneGap. By the time we are finished you will have a working Android application.


(In case you missed the post about creating a jQuery Mobile calculator, here's the link:  jQuery Mobile Calculator )

Create an Android Project

We begin by a creating a normal Android project. Start up Eclipse and choose File > New > Android Project. Give your project a name. I chose PhoneGapCalculator for mine. Then choose your Android version. I chose Android 2.2. And finally set your package name. At this point you have a regular Android project nothing special here. 





PhoneGap-ize The Project

Now we start adding all of things necessary to PhoneGap-ize the project. Begin by adding a libs folder to the root of your project. Be careful not to add it to any existing folder. Then add a www folder to the existing assets folder. If for some reason the assets folder doesn't exist, create it and then add the www folder to it.

If you haven't already unzipped the PhoneGap zip file, please do so now. Find the android folder. It will be under the lib folder. You need to copy the cordova-1.7.0.jar file to your projects libs folder. Then the cordova-1.7.0.js file to the www folder. And finally we need to copy the entirety of the xml folder to the res folder. Remember to copy these files and folders and don't move them. You will need them for other projects in the future. Your project should look similar to the image.

Fix the Build
Now we need to make the build process aware of the cordova jar file. To do that right click on the libs folder then choose: Build Path > Configure Build Path. Click on the Libraries tab, the click on Add JARs.... Then you need to find the cordova jar file and choose it. After clicking OK, you project should have a new item, Referenced Libraries. If you don't see this item, don't continue, something is wrong. You may need to press F5 in order to make Eclipse refresh.




Now we need to modify the generated Android source code to make it a PhoneGap app. Expand the src folder until you reach the java file, mine is named PhoneGapCalculatorActivity.java. Near the top of the file below the import lines, add the following line:

import org.apache.cordova.*;

Change the line which reads:

public class PhoneGapCalculatorActivity extends Activity {

To read as follows:


public class PhoneGapCalculatorActivity extends DroidGap {

And finally replace the line:

setContentView();

With the following line:

super.loadUrl("file:///android_asset/www/index.html");

Now lets copy our calculator files into the project. All of your CSS, HTML, and JavaScript files go into the www folder. So we simply copy the entire contents of the JQMCalculator project to the www folder. Please note: PhoneGap works with the project structure the way that it is, no need to flatten folders.


Once the files are copied, the app will actually run, but let's be neat and fix an issue. The JQMCalculator project includes code to hide the URL bar on Android. In a PhoneGap app, that isn't necessary. So we need to delete hideAddressBar.js file. Then remove all references to it in the code. In the index.html file delete the hideAddressBar.js  script tag.

Delete the script tag
Then replace the method RocknCoder.Events which looks like:

RocknCoder.Events = function () {
$("div[data-rockncoder-jspage]").on(
'pagebeforecreate pagecreate pagebeforeload pagebeforeshow pageshow pagebeforechange pagechange pagebeforehide pagehide pageinit',
RocknCoder.Pages.Kernel).on(
"pageinit", RocknCoder.hideAddressBar);
}();


With the following:

RocknCoder.Events = function () {
$("div[data-rockncoder-jspage]").on(
'pagebeforecreate pagecreate pagebeforeload pagebeforeshow pageshow pagebeforechange pagechange pagebeforehide pagehide pageinit',
RocknCoder.Pages.Kernel);
}();
Delete the ".on..." code
Now if you run the application, you should get see the following:

That's all it takes to turn your jQuery Mobile web app into an Android app using PhoneGap. 

Complete Source Code for PhoneGap Calculator



15 comments:

  1. Just what I needed, concise and right to the point, thanks!.

    ReplyDelete
  2. When I run the application, eclipse throw 2 errors in file index.html: " is not recognized!" and " is not recognized!". Could you please tell how can I solve this problems - set any value in Preferences, change elements to ordinary element div?

    Thank you

    ReplyDelete
  3. While I haven't encountered this issue myself, there is a reference to it in the phonegap wiki: http://wiki.phonegap.com/w/page/16494774/Getting%20started%20with%20Android%20PhoneGap%20in%20Eclipse
    Please try it and let me know if it helps.

    ReplyDelete
  4. Troy excellent explanation, now i need to compile an application made in Jquery Mobile for BlackBerry Smartphones, no no playbook and no BB10, thanks

    ReplyDelete
    Replies
    1. Julian, thanks for the kind words. Have you already downloaded PhoneGap? I don't have a blackberry phone but it seems very straight forward to build the app for it. I have so far built the calculator for Android, iPhone, and Windows Phone 7. Only the Windows Phone has given me any trouble, but it doesn't seem to be PhoneGap's fault. There is some weirdness related to how WP7 handles touch events. I will explain in details in a later post. Please let me know how things work out with blackberry.

      Troy

      Delete
  5. Please, I am designing a mobile application for my MSc project. can I use phpmyadmin with phonegap.

    ReplyDelete
    Replies
    1. Hi fun_dave,

      I am not sure if I understand your question. PHP is server side tech. Are you asking if a phonegap app can contact a PHP based server? If so the answer is absolutely YES it can.

      Troy

      Delete
  6. How can I get this application for my iPhone?

    ReplyDelete
    Replies
    1. Hi Harry,

      There is a blog post for the iPhone application:

      http://therockncoder.blogspot.com/2012/06/converting-jquery-mobile-calculator-to_13.html

      Please remember: If you like a post, please +1 it.

      Troy

      Delete
  7. Thanks Troy ...

    The Getting Started guide says that you must run the "create" command from the command line before creating any new project in Eclipse. Are you familiar with this, and wondering why you didn't mention it?

    ReplyDelete
    Replies
    1. The "create" command was something added in newer versions of PhoneGap after this post was written.

      Troy

      Delete
  8. Hello Troy

    can u give me tutorials for Blackberry+phonegap?
    I am new to phonegap need help

    ReplyDelete
  9. hi can you prove me more tutorials in Phone gap thanks.

    ReplyDelete
    Replies
    1. Hi,
      As luck would have it, I am preparing to create more tutorials in both PhoneGap and Icenium. The first of which should be ready in about 2 weeks.

      Delete
  10. Hello Troy

    I used started guide and I downloaded
    https://www.apache.org/dyn/closer.cgi/cordova/cordova-3.0.0-src.zip. it not have cordova-2.9.0.jar file

    my question is: I need phoneGap too. In your tutorial you use cordova-2.9.0.jar. I found it on http://phonegap.com/install/

    what is differ between 2 downloads commented

    ReplyDelete