10 Essentials for developing commercial Flex 4.5.1 mobile applications

This post is for Adobe Flex/Actionscript/Flash developers who are looking to build commercial-grade mobile apps. I’ve tried to pull together a high-level check list of items you’ll need to build successful and stable apps based on Flex 4.5.1. I’ve also uploaded a fully-functional prototype that demonstrates these concepts in a real-time, GPS navigation app. You can download the app here. So, here goes.

1. Set your initial splashScreenImage and application icon. For your app to look professional you’ll want to display an image while it launches so there isn’t just a blank screen. Here’s a great blog post that goes into more detail and covers handling multiple screen resolutions. One caveat on the splashScreenMinimumDisplayTime property is use this with caution. If you delay the app start too much you run the risk of really annoying users.

<s:TabbedViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
splashScreenImage="@Embed('assets/splashscreen.png')"
splashScreenMinimumDisplayTime="1500"
splashScreenScaleMode="letterbox">

And, be sure to set the application icon. When you install your app, this is the image that will be displayed in the phone’s UI. Configure this in the yourappname-app.xml file. Note if you image icon isn’t the absolute correct size you’ll get a compiler error:

<icon>
     <image16x16>assets/appicon16x16.png</image16x16>
     <image32x32>assets/appicon32x32.png</image32x32>
     <image36x36>assets/appicon36x36.png</image36x36>
     <image48x48>assets/appicon48x48.png</image48x48>
     <image72x72>assets/appicon72x72.png</image72x72>
     <image114x114>assets/appicon114x114.png</image114x114>
     <image128x128>assets/appicon128x128.png</image128x128>
</icon>

2. Manage your applications life-cycle. The best article to read is the old but still very useful Hero View and ViewNavigator  – Functional and Design Specification and this blog post on Understanding View and ViewNavigator. For some reason the ViewNavigatorEvent poperties listed below aren’t documented in the Adobe on-line help. I’ve complained and so should you!

  • viewActivate Event – called when the view is fully activated. It actually happens after the creationComplete event. If you want to know more about view states in general then read this Adobe article.
  • viewDeactivate Event – use this in a View if you want to handle certain things when the user changes to a different View and the current one has been deactivated.
  • removing Event – This is called right before the viewDeactivate Event. So if there is something you want to do right before the view is fully deactivated then use this event.
  • persistNavigatorState – This property works at the application level and allows you to save the navigator’s view stacks and navigation history to a local persistent object. This is a property that is set in the main application’s mxml file and by default it is set to false. The standard architecture of a mobile app is to destroy the view contents when a user switches views so that the application saves memory. But, if there is a significant cost to destroying and recreating a particular view then you should test setting this property to never. Cost in this case means the amount of time, memory and CPU it takes to destroy and recreate a view. Also, if your end user is repeating this over and over that will ultimately affect battery life. Once a view is destroyed my guess is that memory is set for garbage collection. For info see this very informative Adobe blog post.
    <s:TabbedViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
         xmlns:s="library://ns.adobe.com/flex/spark"
         persistNavigatorState="true">
    
  • destructionPolicy – This is a property that can be set on individual views and can prevent an individual view from having all its data destroyed when the view is deactivated. For example, you may allow some views to be destroyed where others are mission critical and shouldn’t be destroyed because it’s too expensive to recreate them. As I write this, I believe this only works if the persistNavigatorState property has been set but it’s been a while since I verified that.
    <s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
    		xmlns:s="library://ns.adobe.com/flex/spark"
    		destructionPolicy="never"
    		viewActivate="settingsViewActivateHandler(event)"
    		viewDeactivate="settingsViewDeactivateHandler(event)">
    

3. Manually changing views. Use pushView(), popView(), popToFirstview(), popAll() and replaceView().

  • pushView() navigates the user to a new screen.
  • Use popView() to move back to the previous screen.
  • popToFirstView() changes to the screen to the very first view that was opened. This is programmatically referred to as the view at the bottom of the view stack and uses the FIFO principal.
  • popAll() returns a blank screen. I’ve never used this and I haven’t come across a use case (yet) that would require given the user a blank screen.
  • replaceView() removes the current view and replaces it in the view stack with the new view you that you assign.

4. Passing data between views. One of the requirements of commercial apps is sharing data between different views. There are a number of ways to do this including singletons, dependency injection and using the data property in the pushView() method. Here are some good articles on all three:

  • Using singletons or tightly coupling data. This is typical for prototyping where you don’t want or need the overhead of a full framework. The prototype app download (link at top of page) uses a singleton model for simplicity.
  • Using framework-based, dependency injection. Use this when you want to use a framework such as Swiz, Parsely or Robotlegs.
  • Using the pushView() data property. When you have fairly simple data needs use this via the pattern pushView(viewClass:Class, data:Object = null, context:Object = null, transition:spark.transitions:ViewTransitionBase = null) Note that this pattern is for basic usage and the data object only supports standard content within the object such as Strings, Array, ArrayCollection, etc. If you have a custom class be sure to register them with the registerClassAlias() method or you’ll get runtime errors when you go to switch views.

5. Set application permissions.These are root permissions that are set via manifestAdditions for Android and infoAdditions for iOS – and these are located in the yourappname-app.xml file in your application’s root directory. Here’s an Adobe article with additional details. When the application is installed the user will be alerted to what permissions you are asking for.

<android>
     <manifestAdditions><![CDATA[
          <manifest android:installLocation="auto">
	       <!--See the Adobe AIR documentation for more information about setting Google Android permissions-->
	       <uses-permission android:name="android.permission.INTERNET"/>
	       <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
	       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
	       <uses-permission android:name="android.permission.DISABLE_KEYGUARD"/>
               <uses-permission android:name="android.permission.WAKE_LOCK"/>
               <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
               <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
	   </manifest>
	]]>
     </manifestAdditions>
</android>

6. Shutdown the app. This only works on Android. On iOS, the user has to do this manually.

NativeApplication.nativeApplication.exit(); 

7. Temporarily disable the screen saver. This is required in apps where you don’t want the screen to go to sleep such as navigation apps where it may be open for a long time without any user intervention. You also need to set the WAKE_LOCK permission in the manifest file.

<uses-permission android:name="android.permission.WAKE_LOCK"/>

 

//Make sure we are on a mobile device and then
//keep the application awake so it doesn't go to sleep and close the screen.                                                      
if(Capabilities.cpuArchitecture == "ARM")
{                                                                             
     NativeApplication.nativeApplication.systemIdleMode = SystemIdleMode.KEEP_AWAKE;                                                                            
}

8. Detecting when phone rotates. If you need to know when the phone rotates use this listener:

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE,stateChangeHandler);

9. Gracefully fail when network connection is lost. If your app needs network access then it’s a best practice to gracefully fail and let the user know when internet connection is lost and then again when it’s restored.

public function NetworkChangeController(autoStart:Boolean = false)
{             
    var req:URLRequest = new URLRequest(_MAP_URL);
    _urlMonitor = new URLMonitor(req);
    _urlMonitor.addEventListener(StatusEvent.STATUS,serviceMonitorStatusHandler);

    NativeApplication.nativeApplication.addEventListener(Event.NETWORK_CHANGE,networkChangeHandler);
}

private function networkChangeHandler(event:Event):void
{
     if(!_urlMonitor.running)
     {
          _urlMonitor.start();
     }
}

private function serviceMonitorStatusHandler(event:StatusEvent):void
{
     trace("Network Status Event: " + event.code + ", " + _urlMonitor.available);
     _urlMonitor.stop();
     event.code == "Service.unavailable" ? _doSomething = false : _doSomething = true;
}

10. Multiple Device Support –sizing for different dpi’s. Last, but not least is using CSS and media queries to help with sizing and layout. Media queries are actually part of the W3C core CSS spec. The cool thing about them is they let you auto-majically detect the users screen dpi (dots-per-inch) and operating system and adjust your CSS accordingly. This saves a huge amount of work on your part:

@namespace s "library://ns.adobe.com/flex/spark";
/* DPI specific styles */
s|Button{
     color:#000000;
     fontWeight:bold;
}

@media (application-dpi:240)
{
     s|Button{
          color:#FF0000;
     }
}

@media (application-dpi:320)
{
     s|Button{
          color:#0000FF;
     }
}

/* Platform specific styles */
@media (os-platform:"IOS")
{
     s|Application{
          backgroundColor:#FFCCCC;
     }
     
     s|ActionBar{
          defaultButtonAppearance:beveled;
     }                      
}

@media (os-platform:"Android")
{
     s|Application{
          backgroundColor:#CCCCFF;
     }
}

Flex/ActionScript Making Complex UIComponents Draggable

Adobe Flex makes it really easy to enable dragging for your UIComponents.  For example, if you have a spark BorderContainer you simply assign mouse listeners to it and then use the startDrag() and stopDrag() methods. What gets tricky is when you have TextInput, or TextArea boxes or other user accessible content inside the component and you don’t want the entire container to drag around when the user clicks on them.

The easiest way I know to prevent this annoying bug from happening is to listen on the MouseEvent for the event target type, and then use that to determine what course of action you want to take. In my case, since I’m using a BorderContainer I listen on the MouseEvent then use the getQualifiedClassName() method to look for the class name string called “spark.skins.spark::BorderContainerSkin”. That way the drag functionality will only be enabled when the user clicks directly on the container. If they click on a text field, then the event.target will be different and the component won’t be draggable!

protected function routeDirectionsContainer_mouseDownHandler(event:MouseEvent):void
{
	//Only allow dragging if user clicks on the parent container rather than the text fields.
	var className:String = flash.utils.getQualifiedClassName( event.target );
	if(className == "spark.skins.spark::BorderContainerSkin")
	{
		routeDirectionsContainer.startDrag(false,null);
	}

protected function routeDirectionsContainer_mouseUpHandler(event:MouseEvent):void
{
	routeDirectionsContainer.stopDrag();
}

The event target property tells you exactly what the user has clicked on. By intercepting that information you can precisely tune what happens in your user interface components. If you don’t know how to get this information, set a debug point on the method that receives the MouseEvent and then inspect the string that is returned by the getQualifiedClassName() method.

Just for reference here’s how to drag enable a UIComponent:

<!-- Note: includes mouseOut listener for mobile. -->
<s:BorderContainer id="routeDirectionsContainer"
	mouseDown="routeDirectionsContainer_mouseDownHandler(event)"
	mouseUp="routeDirectionsContainer_mouseUpHandler(event)"
	mouseOut="routeDirectionsContainer_mouseUpHandler(event)">

	<s:TextInput id="fromText" text="380 New York St, Redlands, CA, 92373"/>
	<s:TextInput id="toText" text="300 Main St., Santa Monica, CA"/>

</s:BorderContainer>

Debugging Flex-AIR apps on iPhone and iPad

Debugging iPad or iPhone apps that you built with FlashBuilder has a number of extra steps that you don’t need when developing with Android. This is especially true if you use Windows as your primary operating system. The good news is that once you’ve done it once or twice it should be fairly straight forward. So here are a few hints to get you going.

Step 0. If you are building on Windows make sure to install the latest version of iTunes. Then check that your iPad or iPhone can be synched with iTunes. If you use a mac you’ve most likely already done this step (in your sleep a hundred times).

Step 1. Make sure you have a certificate and provisioning file. This must be configured under FlashBuilder Project > Properties > Flex Build Packaging. IMPORTANT: If the certificate and provisioning file are not set up or are not valid you will not be able to compile your project. If you don’t know what this is or how to do it, additional info can be found here in a great blog post by Holly Schinsky (@devgirlFL).

Step 2. Set up a Debug Configuration. If you don’t know where that is, select the pulldown next to the bug icon on the FlashBuilder toolbar and then choose Debug Configuration, or go to Run > Debug Configurations. Choose Apple iOS as your Target Platform. Be sure to select the On Device Packaging Method > Fast! If you don’t do this and you choose the Standard option it will take five or more minutes to compile the build each time you hit debug, and that can become a huge time waster really fast. One advantage of using the Standard option is it will perform more like the final release build. In comparison, the Fast version won’t be as performant. So, for the vast majority of your debugging you should probably use Fast, and when you want to test a final build then you might want to choose Standard. When you are ready select the Debug button.

Step 3.  You will then see a popup window with six important instructions. Once you have completed Steps one and two, select the Show package in Explorer link.

Step 4. Drag the .ipa file from your file browser window into the iTunes Library > Apps area.

Step 5. Select the Sync button on the bottom right hand corner of iTunes. You should see Sync In Progress screen on your device. Let the operation complete. When it’s finished you should see a message in the message box at the top of iTunes that says the sync was successful. If there was an error it will also show up in the message box at the top of the iTumes application window.

Step 6. Launch the application on your iPad or iPhone. You should get a popup window titled Flash Debugger that asks for the IP address or hostname.  Important:  your iPad or iPhone and your development machine need to be on the same wireless LAN, if they aren’t then this step won’t work. If you don’t have a wireless LAN handy you can always log both machines into a MiFi or some other type of mobile hotspot. Then enter the IP address of your development machine. On a windows machine you can easily get that in a DOS prompt using the command ipconfig. Hit OK.

The Final Result. If all goes well the app will launch and you will start to see debugging output in FlashBuilder.

Adobe Flex Mobile: Detecting View and Orientation Change with Event Listeners

There will be a time when you want to have more control over the transitions between Adobe Flex Views, or detecting when the device orientation changes. For example, I recently built an app that had some event listeners that stayed persistent even when the user changed views. So, I needed to listen for the change event when using tabbed view navigator <s:TabbedViewNavigatorApplication/> so I could remove those event listeners and I did it like this:

this.addEventListener(Event.REMOVED_FROM_STAGE,tabChangeHandler);

I also had a need to detect when the phone was tilted. Yeh, in a perfect world everything in the app’s user interface would automatically adjust to the new state, but that isn’t always the case especially when building more complex apps. What I did was listen for orientation changes like this:

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE,stageOrientationChangeHandler);

Even if you are using some other Flex methodology for your mobile app, hopefully these examples will give you some ideas!

Adobe Flex Mobile Styles – Easily change the color of a Button

Have a mobile app using a default spark Button <s:Button /> and you simply want to change the background color? Wait just a second before you start creating a full-blown skin! It’s actually very simple – change the chromeColor. This info is buried way down near the bottom of the online reference doc. This also applies to ActionBar, ButtonBar, CheckBox, HSlider, and RadioButton.

Here’s one way to do it using CSS:

<fx:Style>
   @namespace s "library://ns.adobe.com/flex/spark";
   #shutdownButton
   {
      chromeColor: #FF0000;
   }
</fx:Style>

<s:Button id="shutdownButton" label="Shutdown?" click="shutdownButton_clickHandler(event)"/>	 

 Reference:

Basics of Mobile Skinning

Yes, you need Flash Player 10.3 now! Better control over Flash Cookies.

There some really important changes in Adobe’s Flash Player 10.3 that you should know about. Even though it’s been out since the end of June, I’ve run into several situations recently where the developer or user hadn’t installed the latest update yet. The primary change to know about it is the new Flash Player Settings Manager which is accessible through the Windows Control Panel and acts as Flash Player’s global content manager. Just ignore the fact that the information page links to the old Macromedia domain name and read about how you can control SWF and FLV content. To me, this brings Flash Player one giant step closer to being on par with the cookies controls in all modern browsers.

Change the Default Security Setting. The very first thing you should do when installing 10.3 is consider whether or not to change the default local storage from “Allow sites to save information on this computer” to either “Ask me before…” or “Block all sites…”. You can see these settings under the Storage tab. Depending on which exact version of 10.3.x you have the wording may vary slightly. My recommendation is to choose any setting but the current default. Yes, it can be a bit annoying but it’s much more secure. Eventually I would guess that Adobe will add a finer level of control of this, similar to the zones of control most browsers allow. On Windows I was able to access these settings via Start > Control Panel > Flash Player (32-bit).

What’s a Flash Cookie? Mainstream literature universally refers Flash cookies as any data that is stored in Flash Player by a 3rd party web site. To developers, this so called Flash cookie is any data stored in the Flash Player local store. To access the local store you can use flash.net.SharedObject ActionScript class. SharedObject has been around for a while and it’s nothing new. However, in this era of ever increasing web security awareness, Adobe has now made huge strides in expanded our control over how 3rd parties can use this local store.  

Fine Tuning Your Local Store. A few other important things to know when fine tuning your local store:

  • What sites are already using my local store? Under Storage > Local Storage Settings by Site, you may be surprised to see that sites are already using your local store. You can adjust the settings by each site here. For example if you are debugging and testing using the local store you don’t want to be pestered every time you run a new build then you change the permissions for your machine to “allow”. You can also remove the information stored using the remove button.
  • How can I delete the local store in my browser? Go to Storage > Delete All. Enough said!
  • How can I delete ALL local storage on all my browsers? Go to Advanced > Delete All. Booyah!
  • Can I control trusted local content? Yes, go to Advanced > Trusted Location Settings.
  • Do the local store settings work across all browsers? Yes. The Flash Player Settings Manager now acts as a global control center with one caveat: You can have different versions of Flash Player in your different browsers, so be careful.  Go to Advanced > [Under Updates] Check Now to make sure you have the latest version installed on all browsers.

A Few Handy Links

Find my Flash Player Version (Note: Check with all your browsers)

Flash Player Debugger Version

Flash Player Settings Manager