How to use the ActionSheet in PhoneGap

By  on

The ActionSheet is a handy control on the iPhone, and is a very intuitive way of getting a multiple-choice answer from a user in a modal but unobtrusive way.

Using it in PhoneGap makes interacting with your user easy, while keeping the display responsive. And as an added bonus, you don’t need to update any HTML or CSS to get the buttons to look right. The native iPhone codebase handles it for you.

So the question is, how do you use it effectively? As most Web2.0-style developers are aware, the only sensible way to develop flexible applications that don’t bog down the browser is to make your applications behave asynchronously, and make use of callback functions to get feedback from external systems (HTTP requests, users, etc). The ActionSheet on PhoneGap is no different.

The ActionSheet is grouped into the PhoneGap “Dialog” class, and is called like so:

dialog.openButtonDialog(title, buttons..., options);

The title property lets you specify the label to show at the top of the ActionSheet. If you don’t want a title, then simply pass in a null value.

The list of buttons is specified as a series of objects, which I’ll describe below.

Finally, the options let you customize how the ActionSheet is displayed (via the “style” property) and lets you set an onClick handler for the entire ActionSheet.

The example above illustrates several options of the ActionSheet PhoneGap control.

  1. On a per-button basis you can specify your own onClick callback which will be run when that button is pressed.
  2. A global onClick handler can be specified in the openButtonDialog options argument, which will get called no matter what button is pressed.
  3. You can choose what the appearance of the dialog should be (currently only “opaque” and “translucent” are supported)
  4. A button requires a label property, but you can optionally specify a “type” property (can be “normal”, “cancel” or “destroy”).

The callback functions are simply called with two arguments, the index of the button being clicked, and the label of the button the user clicked on.  So if it’s easier for you to work with array indexes, or with text labels, you can easily find out which button was pressed and when.

So go ahead and try out the ActionSheet control.  Either you can use my latest release in my branch of PhoneGap, or you can use these more advanced features once my changes have been merged in with the official branch.

comments powered by Disqus