Tuesday, November 6, 2012

Building a Native Menu with PhoneGap Android

So this question has been posed to me quite a few times over the past couple of weeks so I figure this is probably a good idea for a series of blog posts. In this instalment I'll talk about creating a native menu and next time we'll use only HTML.

So when I talk about a native menu I mean an Android options menu and a lot of the information I'm going to give you is covered very well on this Android Developer page but what I'm going to do is help show you where to add the hooks into your PhoneGap application. Here is an example of an options menu from the Contacts app:


The first step in creating the menu is to define it in XML. My recommendation is to create a menu folder under the res folder in your Android Eclipse project. Then you create a new File with an XML extension. For this post I'll call mine example.xml. When your're done your res folder should look something like this:


Don't worry about the red X's as we haven't edited the XML file yet so it is going to complain about a premature end of file. For a real good description of what goes into a menu XML file read this. For our purposes I'm just going to give you the XML to paste into the file:

But when you view the file in Eclipse you'll still see errors:


and that is to be expected as we haven't added the two images to the drawables folder nor have we added our two new strings to strings.xml. To fix these issues first download these two images:


and copy them to your projects res/drawable-hdpi folder. When you want to put out a professional application you'll need to provide icons of various sizes but the above is enough for our needs.

To fix the rest of the red X's you'll need to open the res/values/strings.xml and add two new Strings. The first should have the name "settings" and a value of "Settings. The second should have the name"help" and, predictably, the value of "Help". At this point all the red X's from example.xml and from the res folder hierarchy should have disappeared. 


If they haven't, well then you've done something wrong and should probably go back over all the steps to make sure you haven't missed anything.

Okay, so now we've got all the resources in place. Let's go write some actual Java code. Don't worry much of it will be cut and paste. In Eclipse open up your main Java class, you know the one that extends DroidGap.

First we'll need to tell your application what to do when it detects that the menu button has been pressed. You'll need to paste the following code into you main Java class:

You shouldn't need to change anything unless you've called your menu XML file something different than example.xml. If you have you'll need to change R.menu.example into R.menu. where you replace with the name of your file minus the .xml extension.

The second bit of code you need to add is a method that will tell your application what to do when the individual menu items are clicked. Here's some example code:


When you click on the Setting button we'll use an Android intent to load the devices Settings panel. If you click on the Help button then we'll execute some JavaScript code. That's it! You don't need to add anything to your HTML/JS code to get a native Android options menu working with your PhoneGap application. Here is what it would look like:



Please note, I'm just providing a quick example and you are not limited to how you handle the menu button clicks in the least. You may want to handle it in Java and do something that you can't do in JavaScript or you may want to call a JavaScript function on your page to have your UI react in some interesting way.

In my next post I'll show you the reverse. How to handle everything in HTML and JavaScript!

13 comments:

Pointsurfing said...

Great tutorial, one of the best and easiest to follow for creating a menu

Super Cockroach said...

This is a fantastic and to the point tute.

Shawn Christopher said...

Simon, how is this triggered in the emulator for Android 4.2? I'm not seeing a menu button anywhere near the back, home, recent buttons.

Simon MacDonald said...

@Shawn Christopher

Yeah, there is no more HW or SW menu buttons on newer Android phones. The new way to provide a menu is through the ActionBar interface. I've got that on my to do list for upcoming blog posts.

Shawn Christopher said...

OK, I know it's not really your job, but (perhaps), can you edit some of your blog post. Without build (Cordova or Android), being mentioned, as I'm going through it's killing me to find things that are out of lifecycle now.

I love your writing style, it's easy to understand and get started with, just again versioning (I know fragmentation isn't your fault).

THANKS! And keep posting!

Simon MacDonald said...

@Shawn Christopher

I am working on a massive update of all the posts and code to bring everything up to date with 2.3.0 or greater so stay tuned. I'm probably going to release it as an ebook with all new material as well.

Shawn Christopher said...

@Simon McDonald
That you know of, is there anyway through PhoneGap to incorporate an ActionBar or is this going to require reading up/using the Android documentation moreso than any PhoneGap resources?

Simon MacDonald said...

@Shawn Christopher

Mac! MacDonald!

Sorry, where was I. I have not looked into it in great detail yet but it is probably more of an Android exercise than a PhoneGap one. It's on my todo list to write up.

Shawn Christopher said...

@Simon MacDonald

Ooops, MacDonald sorry. Thanks for looking into it.

Racing Classifieds said...

I continue to get a "eclipse menu item cannot be resolved to a type" error at this line: public boolean onOptionsItemSelected(MenuItem item) {

Simon MacDonald said...

@Racing Classifieds

Right click, quick fix, Import 'MenuItem'.

nikx said...

Hi,

Thanks a lot for this tutorial. It was easy to create menu although I do not have any programming knowledge.

Could you please guide me in loading the help file when the help button is clicked? Also please let me know the location for storing the help file and the required format of help file i.e. txt, doc, html, etc.

Also I would like to add a menu item which will point to the Google Play link for my app.

Sincerely request you to guide.

Thanks,

Nikx

Simon MacDonald said...

@nikx

If I were you I'd do my help in HTML and use the InAppBrowser to load it.

http://docs.phonegap.com/en/2.8.0/cordova_inappbrowser_inappbrowser.md.html#InAppBrowser

I'm confused why you would need a link to your app in Google Play if you are already in your app. If you wanted to do it from the Java side you would do:

this.appView.sendJavascript("window.location='market://search?q=google'");

Where market://search?q=google would find all Google apps. You'd just have to modify the url for your app.

https://developer.android.com/distribute/googleplay/promote/linking.html