Flex Test Drive for Mobile: Build a mobile application in an hour

For a quick mobile tutorial that doesn't require you to set up a server, try the Twitter Trends tutorial.

Video | Code | Tutorial | Links

Build your user interface

• Download Flash Builder 4.5 Trial
• Download the setup files (ZIP, 13.3 MB)
• Download the assets files (ZIP, 1.4 MB)
• Download the completed tutorial project (ZIP, 17.7 MB)

Code

FlexMobileTestDrive.mxml

FlexMobileTestDriveHomeView.mxml

Tutorial

In this Test Drive, you are going to create a Flex mobile application that retrieves, displays, and modifies database records (see Figure 1). A Flex application does not connect directly to a remote database. Instead, you connect it to a data service written in your favorite web language (PHP, ColdFusion, Java, or any other server-side technology). You will build the front-end Flex mobile application; the database and the server-side code to manipulate database records is provided for you as a PHP class, a ColdFusion component, or Java classes.

In this module, you are going to build a Flex mobile application that retrieves data from a database and displays it. A list of employees will be displayed in one application view and employee details in another. First, you build and test the application using a desktop emulator. Next, you run and test the application on an attached mobile device.

In this tutorial, you create a new Flex Mobile project and build the user interface. You'll retrieve data from the server and display it in the next tutorial.

Step 1: Install the server files on a local application server.

Follow the instructions in one of the sections below.

The setup files include a database and server-side files to manipulate data in the database. Your Flex application will call methods of one of these server-side files, EmployeeService.

Note: If you installed the server files for the Flex 4.5 Test Drive or the Flex 4.5 trial email sample applications, you can skip this step. The same server-side files are used for all three.

Setup for PHP

1. Download the Test Drive setup (ZIP; 238 KB) archive and unzip it. Unzip the testdrive_setup_PHP file. It contains a Database and a TestDrive folder.
2. Create a testdrive_db database on your MySQL installation using the testdrive_db.sql file located in the Database folder. If you do not have permissions to create a database, use the testdrive_table.sql file instead to create two tables in an existing database. After the database is created, set user privileges for it.
3. Move the TestDrive folder, which contains the PHP service file, to your PHP server.
4. Open /TestDrive/test/test.php in an editor and change the username, password, server, and databasename properties to the correct values for your server setup. Test the setup by browsing to http://{your server:your port}/TestDrive/test/test.html. For example, browse to:

   http://localhost/TestDrive/test/test.html

   You should see a list of the names of the employees in the database successfully displayed.

5. Open /TestDrive/services/EmployeeService.php in an editor and change the username, password, server, port, and databasename properties to the correct values for your server setup. This class file contains the methods you will call from your Flex application.

Setup for ColdFusion

1. Download the Test Drive setup (ZIP; 238 KB) archive and unzip it. Unzip the testdrive_setup_CF file. It contains two CAR files (testdrive_mac.car and testdrive_win.car) and a ZIP file (testdrive.zip).
2. If you have ColdFusion Enterprise or ColdFusion Developer, deploy one of the CAR files.

• In the ColdFusion Administrator (http://localhost:8500/CFIDE/administrator/ for the default standalone installation), navigate to Packaging & Deployment > ColdFusion Archives and browse to and deploy one of the CAR files.
• In the Deploy Wizard, change the deploy locations to reflect the locations of the db and wwwroot folders on your server. For example, on a Mac: /Applications/ColdFusion9/wwwroot/TestDrive and /Applications/ColdFusion9/db/testdrive or on Windows: C:\Program Files\ColdFusion9\wwwroot\TestDrive and C:\Program Files\ColdFusion 9\db\testdrive.
• After deploying, check that you have a new data source called testdrive_db and a new folder in wwwroot called TestDrive. If your datasource verification fails, delete the datasource and recreate it: testdrive_db, Apache Derby Embedded, and point to the /ColdFusion/db/testdrive database just installed.

3. If you have ColdFusion Standard, you need to manually place the server files and create a datasource.

• Unzip testdrive.zip. It contains TestDrive and db folders.
• Place the TestDrive folder in the ColdFusion webroot, /ColdFusion/wwwroot/.
• Open the db folder. It contains a folder called testdrive.
• Place this testdrive folder in the ColdFusion db folder, /ColdFusion/db/.
• In the ColdFusion Administrator (http://localhost:8500/CFIDE/administrator/ for the default standalone installation), navigate to Data & Services > Data Sources and create a new data source called testdrive_db with an Apache Derby Embedded driver and the database folder set to the testdrive folder you just placed in the /ColdFusion/db/ folder.

4. Open /ColdFusion/wwwroot/TestDrive/services/EmployeeService.cfc in an editor and examine the code. This class file contains the methods you will call from your Flex application. Note that the methods have the access argument set to remote so that they can be called from a Flex application.
5. Open /ColdFusion/wwwroot/WEB-INF/flex/services-config.xml in an editor. This file is used when calls are made to the server from your application. Locate the <property-case> tag and change all three values to true as shown below.

Note: If you are using an earlier version of ColdFusion, your configuration file may not have these tags and you will need to add them. See the documentation on using Flash Remoting with your particular server.

6. Restart the ColdFusion server.
7. Test the setup by browsing to http://{your server:your port}/TestDrive/test/test.html. For a default standalone ColdFusion installation, browse to http://localhost:8500/TestDrive/test/test.html. You should see employee data from the database successfully displayed in a datagrid.

Setup for Java

1. Download the Test Drive setup (ZIP; 238 KB) archive and unzip it. Unzip the testdrive_setup_JAVA file. It contains a WAR file for a web application called testdrive.
2. Deploy the WAR file to your web server. It contains the Java classes, an Apache Derby embedded database, and BlazeDS 4 files.
3. Open /{your server webapps folder}/testdrive/WEB-INF/src/services/EmployeeService.java in an editor. This class file contains the methods you will call from your Flex application. It must have a no argument constructor.

Note: For Windows, the ConnectionHelper.java file assumes the testdrive web app is deployed on the C drive. If it is not deployed on the C drive, you need to modify this file appropriately and recompile it, replacing /{your server webapps folder}/testdrive/WEB-INF/classes/services/ConnectionHelper.class.

4. Open /WEB-INF/flex/remoting-config.xml in an editor and examine the code.  This file is used when calls are made to the server from your application. Note the definition for the destination called employeeService which points to the services.EmployeeService class.
5. Test the setup by browsing to http://{your server:your port}/testdrive/test/test.html. For example, for the BlazeDS turnkey server, browse to http://localhost:8400/testdrive/test/test.html. You should see employee data from the database successfully displayed in a datagrid.

Step 2: Create a Flex Mobile project.

Follow the instructions in one of the sections below.

Project settings for PHP with Flash Builder 4.5 for PHP

1. In Flash Builder 4.5 for PHP, select File > New > Flex Mobile and PHP Project and create a PHP project called TestDrive at an existing location (see Figure 2). Be sure to set the location to where you saved the TestDrive folder on your PHP server in step 1.
2. Set the appropriate server location settings (see Figure 2) and validate the configuration. Example settings for a Zend server on a Mac are shown in Figure 2; be sure to use the correct values for your server setup!

3. Click the Next button and create a Flex project called FlexMobileTestDrive and store the project files locally (see Figure 3). You can usually use the default value for the output folder, which is where the compiled application and associated files will be stored on your application server.

4. Click the Next button and select a View-Based Application with an initial view title of HomeView, select one or more target platforms, and specify application settings to reorient and scale automatically for different screen densities with a application DPI of 160 dpi (see Figure 4).

5. Locate and open the FlexMobileTestDrive-app.xml file that was created and change the id to com.adobe.samples.FlexMobileTestDrive (see Figure 5). The application ID is used by the AIR runtime and the operating system to identify the application. In order to guarantee a unique application ID, a common naming convention is to use reverse domain name notation as used here. You will modify additional attributes in this file in a later tutorial.

Project settings for Java, ColdFusion, or PHP with Flash Builder 4.5

1. In Flash Builder 4.5, select File > New > Flex Mobile Project and create a Flex Mobile AIR project called FlexMobileTestDrive and store the project files locally (see Figure 6).

2. Click the Next button and select a View-Based Application with an initial view title of HomeView, select one or more target platforms, and specify application settings to reorient and scale automatically for different screen densities with a application DPI of 160 dpi (see Figure 7).

3. Click the Next button and select your application server,  set the appropriate server location settings (see Figures 8 and 9), and validate the configuration. Example settings for Java with BlazeDS and ColdFusion servers are shown in Figures 8 and 9, respectively; be sure to use the correct values for your server setup! You can usually use the default value for the output folder, which is where the compiled application and associated files will be stored on your application server.

4. Click the Next button and assign a unique application ID, for example: com.adobe.samples.FlexMobileTestDrive (see Figure 10). The application ID you set on the Build Paths page is used by the AIR runtime and the operating system to identify the application. In order to guarantee a unique application ID, a common naming convention is to use reverse domain name notation as used here.

Step 3: Examine the generated project(s) and files.

Use the Package Explorer to explore the generated project(s) and files.

When you create a new Flex Mobile project, Flash Builder creates three or four files in the Flex project: two MXML files and one or two XML files (see Figure 11). You create Flex applications using two languages: ActionScript and MXML. Typically, you use MXML and Flex components to lay out application interfaces and ActionScript to program application logic. MXML tags and ActionScript code can reference each other, similar to HTML tags and JavaScript code. When you compile an application, the MXML is parsed and converted to ActionScript in memory, and then the ActionScript is compiled into bytecode. The result, a SWF file, is rendered by Flash Player for web applications and the Adobe AIR runtime for mobile and desktop applications and mobile applications on Google Android devices and Blackberry Playbooks. iOS devices do not support AIR so when packaging an application for the iOS platform, the SWF is converted to a native iOS application.

FlexMobileTestDrive.mxml is the main application file. The first line of code is the XML declaration for the parser. The next line is the ViewNavigatorApplication tag, which is the root container for a view-based Flex mobile application. It has a firstView attribute set to views.FlexMobileTestDriveHomeView (the second MXML file automatically generated). This is the view that displays on the device when you launch the application. Unlike desktop or web applications built in Flex, you typically do not put much content in the application container. For mobile applications, most content is placed in individual views. The ViewNavigatorApplication tag also has an applicationDPI attribute set to 160, the target device density.

The third file created, FlexMobileTestDrive-app.xml, is the application descriptor file. It includes info about the application, including its name, id, associated icons, what the initial window should look like, as well as Android and iOS specific settings. If you selected Blackberry Tablet OS as a target platform for the application, you will have a fourth file, blackberry-tablet.xml, in which you set Blackberry Tablet OS specific settings.

Step 4: Download the Mobile Test Drive assets.

Download and unzip testdrivemobile_assets.zip and add the assets folder to your project (see Figure 12).

The assets folder contains graphics that you will use in the application.

Step 5: Add a TextInput to the title area of the ActionBar.

Switch to Design mode for FlexMobileTestDriveHomeView.mxml and from the Components view, drag out a TextInput and place it in the title area (titleContent) of the ActionBar (see Figure 13). Use the Properties view to assign an id of searchTxt, a prompt of Employee Name, and a width of 100% (see Figure 15).

Flex applications are built from components such as Buttons, CheckBoxes, and Lists. The Flex 4 framework includes over 100 components, including user interface controls to display content and provide user interaction, and containers to manage the layout. The Flex 4.5 framework includes components and component skins that are optimized for mobile use and in some cases, enhanced to enable touch and throw scrolling. It also contains several new components specifically designed for mobile development including ViewNavigatorApplication, TabbedViewNavigatorApplication, View, ViewNavigator, TabbedViewNavigator, and ActionBar. When you create a mobile project, the Flash Builder Component view displays a subset of Flex components reccomended for mobile use.

The root container of your application, the ViewNavigatorApplication container, has a single child, a ViewNavigator. The ViewNavigator manages an ActionBar and a set of View instances using a stack-based history mechanism. The ActionBar component is displayed at the top of the application and appears above the views and consists of three areas: a navigator area, a title area, and an action area (see Figure 14).

Typically, you place components that let the user navigate the content (like back or home buttons) in the navigator area, a string or other components (like the TextInput used in this application) in the title area, and components that let users take an action (like buttons to search or add employees in this application) in the action area.

For each component, you can set properties and styles. Properties apply only to that particular component instance. Styles can be set inline or using CSS to create style rules to apply to your components. You can view and set object properties, styles, and more using the Flash Builder Properties view (see Figure 15).

Switch to Source mode and take a look at the generated code.

Step 6: Add buttons to the action area of the ActionBar.

In Design mode, set the preview device to Motorola Droid Pro (see Figure 16). Using the Components view, add two Button instances to the action area (actionContent) of the ActionBar (see Figure 16). Assign the first Button an id of searchBtn, delete the label, and and click the folder next to icon and select Multi-Resolution Bitmap (see Figure 17). Embed the bitmaps search160.png, search240.png, and search320.png located in the assets folder (see Figure 18). Assign the second button an id of addBtn, delete the label, and set its icon property to a multiresolution bitmap with embedded images add160.png, add240.png, add320.png.

When you created the project, you set the application DPI to 160. When using Design mode to build the application interface, you should set the preview device to one that has this same density so the design view pixels will correspond one-to-one with the pixels in the Flex code. The Motorola Droid Pro is a 160 DPI device. You will look up device DPIs in a later step.

Step 7: Add a List control to the view's content area.

Using the Components view, drop a List control below the ActionBar. Assign an id of empList and set constraints so that it fills the entire view area (see Figure 19).

The layout of a container determines how its children are positioned within it. Some containers have a preset layout mechanism (like the VGroup and HGroup containers). For others, like the View container, you can set the layout yourself. For example, you could specify a vertical layout, a horizontal layout, a basic layout , or more. Basic layout uses absolute positioning in which the positions of objects are set using x and y values (the upper-left corner of the container is 0,0) or constraints. Constraints allow you to "pin" an object to a specific location in a container, providing a way to build flexible interfaces. You set constraint properties (top, bottom, left, right, verticalCenter, horizontalCenter) to the number of pixels the object should be from that part of the container.

Step 8: Change component attributes in MXML.

Switch to Source mode and use Flash Builder Content Assist to select and set values for various properties and styles.

When you place your cursor inside a tag and press the spacebar or Ctrl+Spacebar, you get code hinting with the Flash Builder Content Assist (see Figure 20). It shows a list of all the attributes you can set for that tag, including properties, styles, events, and more. Different symbols are used for each different type of attribute. This is the same list you see in the Alphabetical view of the Design mode Properties view.

Step 9: View a component's API.

Select Help > Dynamic Help and then click a component tag in your code. In the Help view, click the component's API link to view its API (see Figure 21).

The Adobe Help AIR application opens, which allows you to view help content (including the ActionScript Language Reference, ASDocs) when you are online or offline (once the content has been downloaded and saved locally). A component's API, its application programming interface, lists everything you can set for that component and includes descriptions and code examples. If you do not see the class explorer on the left side, click the Show Packages and Class List link in the upper-left corner of the window.

Step 10: Preview the mobile application using the desktop emulator.

Use the Run button or the Run menu to compile the application. For PHP developers using Flash Builder for PHP, you can select to Run As a Mobile (PHP) Application or a Mobile Application. In the Run Configurations dialog box, launch the application on the desktop simulating a specific mobile device for a specific target platform (see Figure 22). Use the Device menu to rotate the application (see Figure 24). View common device configurations in Flash Builder by selecting Run > Run Configurations and then clicking the Configure button (see Figure 25). Then, create two run configurations for devices with different pixel densities and run the application using each (see Figures 23 and 26).

PHP developers using Flash Builder for PHP: The first time you run an application, you get a Run As dialog box. If you are running the application there is no difference between the two. If you are debugging the application and also want to debug any of the PHP code (covered in a later tutorial), you need to debug as a Mobile (PHP) Application for the PHP Debugger to run.

Your application runs in the AIR Debug Launcher (ADL) (see Figure 23). The ADL provides a way for you to run and debug mobile and desktop applications without having to first install them on a computer or device.

The ADL also provides menu items in the Device menu to emulate devices and device actions, such as rotating the device or pressing the Back button (see Figure 19). Simulate rotating the device and see the ActionBar automatically resizes to fit the screen. Note that in the emulation the view looks somewhat large because the pixel density of mobile devices is higher than that of desktop monitors.

Next, simulate the application on a device with a different pixel density. Return to Flash Builder, select Run > Run Configurations, and then click the Configure button in the launch method area. You should see a table listing screen sizes and densities for common mobile devices (see Figure 25). You can also modify this list to add your own device configurations. Notice the Motorola Droid Pro has a lower PPI and will thus use the 160 dpi assets you specified. The other Motorola Droids will use the 240 dpi assets.

Return to the run configuration dialog box and rename the existing configuration to specify a dpi or device. For example, if it is using the Motorola Droid Pro device, call it FlexMobileTestDrive (160) or FlexMobileTestDrive (Droid Pro). Click the Duplicate Launch Configuration button in the upper-left corner and create a second launch configuration for a device with a different pixel density, for example FlexMobileTestDrive (240) for the Motorola Droid X. Run the application. You will see a different size window with an application scaled to the appropriate size and using the appropriate multi-resolution assets (see Figure 26).

You have now created your application interface and tested it using the ADL simulator. In the next tutorial, you retrieve data from the database and display a list of employees in the List control.

Learn more

Refer to the following resources to learn more about this topic:

Documentation: Developing mobile applications with Flex and Flash Builder

• Building Mobile Applications with Flex 4.5
• Differences in deploying mobile, desktop, and browser application development
• Set mobile project preferences
• Lay out a mobile application
• Define navigation, title, and action controls in a mobile application
• Support multiple screen sizes and DPI values in a mobile application
• Manage launch configuration

Documentation: Building Adobe AIR Application

• Developing AIR applications for mobile devices

ActionScript 3 Reference

• TextInput 
• Button

More resources

• Mobile and Devices Developer Center
• Flex Developer Center