I will assume you have some familiarity with AIR for mobile and Granite. It’s mostly the same as for Flex but there are some things you have to take into account.

1. Get the right version of Granite

The latest version of Granite is 2.2.1 GA. However, in the most recent version of AIR and Flex Adobe made some changes in the API which breaks backwards compatibility for some features of Granite. Therefore this release of Granite won’t work using the newest SDK. Refer to this post on the Granite form for more info on how to make these changes yourself. If you don’t want be bothered with building Granite yourself just download this version of GraniteDS to get started immediately.

2. Connecting to the right server

A problem for AIR applications in general (both desktop and mobile) is setting the right server settings. It is quite simple when running within the browser: The server address is changed with a single reconfiguration of the swf-file and all clients are using the new address on a browser refresh. With AIR it is a bit different and you’re not always at liberty to ‘hardcode’ the service settings in the AIR distribution package.
Granite offers a method for dynamic server configuration using the server initializer component:

Tide.getInstance().addComponentWithFactory(
  "serviceInitializer",
  DefaultServiceInitializer, {
    contextRoot: '/my-app',
    serverName: “10.0.0.1”,
    serverPort: “8080”
});

Note that once a connection is made, it is not possible to reconnect with another configuration, because the service initializer is only used once. You have to restart the application to enable the new connection settings or reset Tide’s RemoteObject. Unfortunately Tide’s API doesn’t support this reset. I came up with a small workaround which requires you to extend the EJB class with an extra reset method with the following body:

public class Ejb extends org.granite.tide.ejb.Ejb {
  /**
   * Reset the Tide Connection to allow new server settings
   */
  public function resetConnection():void {
    if (_ro) {
      _ro.disconnect();
    }
    _ro = null;
  }
 
}

This method resets Tide’s RemoteObject so the next remote call will force a reinitialization using the current settings of serviceInitializer. Refer to Granite’s issue tracker or forum thread for more details.

3. Automatic logout

Applications running on mobile platforms are always susceptible to unpredictable interruptions. For example when a phone call or text is received. Mobile AIR applications provide a deactivate event which is dispatched when the application is halted somehow. The application I wrote was using Tide’s Identity class for user login. Therefore I added an event handler to automatically logout the user and push the LoginView on top of the navigator stack:

private function deactivateHandler(event:Event):void {
  if (identity.loggedIn) {
    identity.logout();
  }
  navigator.popAll(); // Purge the navigator history to disable back button usage
  navigator.pushView(LoginView);
}

4. Build, build, build!

This isn’t directly related to Granite or AIR for mobile. But since they can both be used for enterprise scale applications I thought I’d mention it shortly: Make sure you have a proper build script. Now, I’ve got an example from Chris Black which provides a good starting point. I’ve only added the metadata compiler options required for Tide and of course a reference to the Granite libraries and generated Actionscript classes.

 
 <mxmlc ... >
 
  <!-- .... -->
 
  <!-- location of generated as classes with gas3 -->
  <source-path path-element="${gen.src.dir}" />
 
  <compiler.library-path dir="${basedir}/libs" append="true">
    <include name="granite-essentials.swc" />   
    <include name="granite.swc" />
  </compiler.library-path>
 
  <keep-as3-metadata name="Bindable" />
  <keep-as3-metadata name="ChangeEvent" />
  <keep-as3-metadata name="Destroy" />
  <keep-as3-metadata name="Id" />
  <keep-as3-metadata name="In" />
  <keep-as3-metadata name="Inject" />
  <keep-as3-metadata name="Managed" />
  <keep-as3-metadata name="ManagedEvent" />
  <keep-as3-metadata name="Name" />
  <keep-as3-metadata name="NonCommittingChangeEvent" />
  <keep-as3-metadata name="Observer" />
  <keep-as3-metadata name="Out" />
  <keep-as3-metadata name="PostConstruct" />
  <keep-as3-metadata name="Transient" />
  <keep-as3-metadata name="Version" />
 
</mxmlc>

One plus one

I can imagine one must be thinking: ‘Everyone could have figured that out!’ And I totally agree, because that’s exactly what this article is about. With some experience with Flex, a developer can write a mobile application on top of a Java EE backend. It doesn’t take much to utilize an existing backend from a mobile platform. Since the latest release of AIR the performance for iOS and Android is pretty good and together with the Granite Enterprise Platform the barrier to emerge an enterprise application to a mobile platform has become much lower.

Goal

We will create a simple RSS reader. Not a very exciting example, but already shows some nice features of AIR for mobile. I’ll assume you have experience with Flex or AIR, but I think you will manage with some level of programming experience. If not, feel free to leave a reply if you have any questions or take a look at the full source.

Setup

Download and install the preview release of Flash Builder called Burrito It provides a wizard to start an empty mobile application. By default the wizard creates two mxml files containing a MobileApplication and a View component.

The MobileApplication class is inherited from the Application class used for desktop AIR. The mobile version provides, among other things, an action bar and a navigator. Furthermore its firstView property points to the empty view component. The view component is a normal group, but optimized for mobile use as well.

Article list

Open the main view component (called <projectName>Home.mxml). Create a List component in the main view. Provide positioning constraints to let it occupy the whole screen.

<s:List left="0" top="0" bottom="0" right="0" />

To retrieve the feed, create an HTTPService pointing to the RSS feed in the declaration section of the view. Add a resultHandler function to parse the feed-data. Parsing xml data is quite simple. You can just navigate to the DOM-tree as it were a normal ActionScript object. Use the data property of the view to store the articles locally. Using this property will provide some benefits with navigation, which will become clear in a bit.

<fx:Script>
  <![CDATA[
    import mx.rpc.events.ResultEvent;
 
    protected function service_resultHandler(event:ResultEvent):void {
      data = event.result.rss.channel.item;
    }
  ]]>
</fx:Script>

<fx:Declarations>
  <s:HTTPService
    id="service"
    url="http://lsd.luminis.nl/feed/"
    result="service_resultHandler(event)" />
</fx:Declarations>

Now there are only a couple of things left to do. Invoke the server and provide the list with the articles and instructions to show them.

Both are quite simple. The feeds are retrieved by invoking the send() method of the service. To automatically retrieve them, this method should be invoked when the view is created so we will use the creationComplete handler.

<s:View
  xmlns:fx="http://ns.adobe.com/mxml/2009" 
  xmlns:s="library://ns.adobe.com/flex/spark"
  title="Home"
  creationComplete="service.send()">

Finally, bind the data property to the dataProvider of the list and set its labelField attribute to ‘title’.

<s:List
  dataProvider="{data}"
  labelField="title"
  left="0" top="0" bottom="0" right="0" />

Your view will probably look something like this.

<?xml version="1.0" encoding="utf-8"?>
<s:View
  xmlns:fx="http://ns.adobe.com/mxml/2009" 
  xmlns:s="library://ns.adobe.com/flex/spark"
  title="Home"
  creationComplete="service.send()">
 
  <fx:Script>
    <![CDATA[
      import mx.rpc.events.ResultEvent;
 
      protected function service_resultHandler(event:ResultEvent):void {
        data = event.result.rss.channel.item;
      }
 
    ]]>
  </fx:Script>
 
  <fx:Declarations>
    <s:HTTPService
      id="service"
      url="http://lsd.luminis.nl/feed/"
      result="service_resultHandler(event)" />
  </fx:Declarations>
 
  <s:List
    dataProvider="{data}"
    labelField="title"
    left="0" top="0" bottom="0" right="0" />
 
</s:View>

Emulator

Emulate hardware buttons

When the emulator is launched it shows a list of articles after a couple of seconds. Now you can select Rotate Right from the Device menu to display the landscape view. You will also notice the list is able to scroll up and down when dragging your mouse pointer (Which of course is the emulated equivalent of a one-finger swipe)

Article details

Next is to create a detailed view showing the full content of an article. Close the emulator and return to Flash Builder. In the views package, create a new component and call it DetailView. Bind the title attribute to data.title. Add a label as well and bind the text property to data.description. Don’t forget to specify the positioning constraints.

<s:View
  xmlns:fx="http://ns.adobe.com/mxml/2009" 
  xmlns:s="library://ns.adobe.com/flex/spark"
  title="{data.title}">
 
  <s:Label
    text="{data.description}"
    left="20" right="20" bottom="20" top="20" />
</s:View>

All view components provide a navigator object. We will use this in the change event handler of the article list. This event is fired when the user selects an article from the list. It looks as follows:

import spark.events.IndexChangeEvent;
 
protected function articleList_changeHandler(event:IndexChangeEvent):void {
  navigator.pushView(DetailView, data[event.newIndex]);
}

It simply instructs the navigator to create a new DetailView and push it on top of of the navigation stack. Furthermore the selected item from the article list is passed on to the data property of the DetailView.

Add the change handler and assign it to the change event of the article list:

<s:List
  dataProvider="{data}"
  labelField="title"
  change="articleList_changeHandler(event)"
  left="0" top="0" bottom="0" right="0" />

Article list inside the emulator

For performance optimization, AIR destroys the view when a user navigates away and recreates it when he returns. Only the contents of the data property is saved and passed into a recreated view of the same type. This is why we used it to store the articles. Otherwise the user has to wait for a reload when he returns to the main view.

When you launch the new version in the emulator, you will notice the application slides to the detail view when an article is selected. Click Back from the Device menu to simulate a click on the hardware back button.

Last but not least: action buttons

One thing our application is missing, is a button to go to the original webpage showing the full article. This button is placed inside the header of our detail view, next to the title.
To achieve this, add the button inside the actionContent of the detail view. Give the button an icon (I used one from the Tango project) and set the click handler to open the url of the article.

<s:actionContent>
  <s:Button
    click="{navigateToURL(new URLRequest(data.link))}"
    icon="@Embed('/assets/internet-web-browser.png')"/>
</s:actionContent>

Of course you might want an additional button to return to the article list instead of using the ‘hardware button’. Place this button inside the navigationContent. This will place the back button at the upper left corner. The click event of this button will invoke the navigation.popView() method to remove the current view from the stack and return to the previous one.

<s:navigationContent>
  <s:Button
    click="navigator.popView()"
    icon="@Embed('/assets/go-previous.png')"/>		
</s:navigationContent>

Action and navigator buttons

If you launch the application you will notice the buttons are nicely aligned at the top of the screen.

What’s next?

The next step will be to package the application to an apk file so you could install it on an Android device. This is done by the Export Release build wizard inside the Project menu of Flash Builder. It includes the ability to sign your application to allow distribution through the Android Market.

Another nice feature which I will not discuss in detail is to add gesture based navigation. Take a look at this article from Adobe to find out more. The approach discussed should be working for mobile AIR applications as well.

Unfortunately the most interesting benefit of using AIR for mobile didn’t become clear with this tutorial. It would be nice to deploy our application on other mobile plastforms as well. However the cross compiler for iOS isn’t available yet and the same goes for AIR on Windows Phone, BlackBerry or Symbian. We will just have to wait when Adobe is ready so we can fully benefit from the “Write once, run anywhere” promise.