Building a data-centric application using Flash Catalyst CS5 and Flash Builder 4

In this tutorial, you'll build an employee address book application that lets users enter search criteria and view a list of results fetched from a database (via a ColdFusion service), from which they can select an employee to get their full contact information. The completed application could work either as a browser-based application (using Adobe Flash Player) or a desktop application (using Adobe AIR). For this tutorial, the application will be deployed via the browser.

Figures 1 through 3 show what the completed application looks like.

1. The user can enter a letter or part of a surname to search for matching employees in the database.

2. A list of matching employees is presented to the user, from which the user can make a selection to see more detail.

3. Detailed information about an employee—including employee ID, date of birth, job title, and contact information—is shown to the user.

If you haven't done so already, download the sample files that accompany this tutorial and unpack the contents to your local drive.

Import your design file

1. Launch Flash Catalyst. You will be presented with a Welcome screen that gives you the option to open a recent project, create a new project from a design file, or create an empty project. For this tutorial you're going to use an existing design file created in Illustrator CS4.

   Optional: If you'd like to examine the structure of the document in Illustrator and potentially make alterations to the design of the application user interface then you can do so. You should pay particular attention to the use of layer folders and groups to logically specify the structure of the Illustrator document.

2. From the Welcome screen, select the From Adobe Illustrator AI File option (see Figure 4).

3. From the file selector window choose the example file that will be used in this tutorial, it is named: employee_app.ai.
4. When the Illustrator Import Options dialog box appears (see Figure 5), click OK to accept the default import options. Flash Catalyst will now import the Illustrator file. You may experience a slight delay during which the import libraries are initialized and the import process takes place.

Flash Catalyst will display the imported Illustrator file on the artboard and you should also see a number of panels open by default, including the Tools panel on the top right, with the Layers and Properties panels directly below (see Figure 6). At the top of the screen you'll see a visual list of pages/states and at the bottom you may see the Timelines panel.

Convert artwork to components

The application you are about to build will have multiple states, representing the search input (Search state), the search results (List state), and the detail information for the selected employee (Detail state). Note that the Illustrator sample file only defines a single view and that Flash Catalyst lists a single default state. Later in the tutorial you will define additional states of the application.

First, you need to look at the structure of the imported Illustrator file and decide how to represent the various parts of the user interface in your application.

1. Look at the Layers panel (see Figure 7). You'll see that the designer used layer folders to separate common controls (in the Controls folder) from the search results elements (in the left panel folder) and the detail elements (in the right panel folder). This makes it easier for you to identify graphical assets based on where they are used in the interface and is a recommended approach for designers to take when preparing design files in either Illustrator or Photoshop.

2. Select the first Group item under the Controls folder; this represents the Close button, which, in a desktop application, lets you exit an application. However, since you want to create a browser-based application, you will use the button to reset the application interface and just show the user the Search state.
3. Locate the Heads-up display, or HUD (it's the black floating panel), and select Button from the Convert Artwork to Component popup menu (see Figure 8).

Note that Flash Catalyst changes the description of the element from a Group to a Button. Behind the scenes, Flash Catalyst has created a Flex Button component and made sure that the generated graphical skins for that button are representative of the visual design.

4. Repeat Steps 2 and 3 to convert the Minimize button (<) to a Button component as well.
5. The Controls folder also contains a number of graphics that together will represent the Text Input component that lets users enter their search criteria. Select all four graphics and then convert them to a Text Input component using the appropriate menu item in the HUD. After doing so, your layers panel should look similar Figure 9.

Define states for your button components

Typically, button controls and other user interface elements provide a visual response as the user interacts with it. Just as an application can have multiple states defined, each component can also have a number of different states; a button, for example, can have an Up, Over, Down, and Disabled state.

1. Select the Close button on the artboard and from the HUD select the Over state button under Edit Button Appearance (see Figure 10). You are now editing the individual states of the selected button and can make changes that the user will see when they interact with the component.

2. Select the path used to define the button, either directly using the Direct Select tool (the white arrow in the Tools panel) or by expanding the group at the top of the layers panel and selecting the Close layer, and then change the color using the Properties panel (see Figure 11).

If you want to make edits to the other states of the button, you can select an alternative state using the Pages/States panel (see Figure 12).

3. When you have finished making changes to the component and want to return to editing the application, use the breadcrumb navigation at the top of the artboard to step out of the button component (see Figure 13).

At any time you can use the File > Run Project menu command to compile the application and test it in the browser (see Figure 14). If you do this now you should be able to test the rollover functionality of the button you just worked on.

Creating the scrollbar and list components

You need to create two more complex components in your application: a customized scrollbar and a list control that is used to display the search results (look closely, and you'll see that the designer has already created graphics for these two items).

1. Start with the scrollbar. Select the graphical parts of the scrollbar either in the layers panel or on the artboard and then choose Convert Artwork to Component > Vertical Scrollbar in the HUD. You should see that the HUD reports that you need to undertake some additional steps to make the component work correctly (see Figure 15).

2. Click the Edit Parts button in the HUD to edit the newly created scrollbar component.
3. Select each graphical part of the scrollbar in turn and assign it correctly using the Assign Parts menu in the HUD (see Figure 16); only the Thumb and Track are required, but your design also specifies the Up/Down buttons, so you should assign those as well. When you are finished assigning the correct parts, navigate out of the component.

4. Select the text element and the background element for the list item and use the HUD to convert them into a "Data List" component. You will notice that the HUD reports component issues, just as we saw with the scrollbar.

   In this case, you need to specify which part of the design will repeat for each and every data item.

5. Click the Edit Parts button in the HUD, then reselect both the text element and the background element and choose Repeated Item (required) from the HUD to specify that both of these will repeat. You should see that Flash Catalyst now repeats the item a number of times on the artboard.

6. With the repeated item selected, use the Properties panel to adjust the vertical spacing between each item; the default value is 6, but for this design a space of 2 is more appropriate. Also adjust the height of the repeated item so that it is approximately 325 pixels high; you can do this either on the artboard or through the Properties panel (see Figure 18).

The final step in creating the data list is to edit the states for the repeated item so that when a user moves the mouse over an item in the list the background changes color.

7. Double-click the repeated item to edit the actual item renderer for the data list, then select the Over state as shown in Figure 19.

8. Use the Layers panel to remove the layer named ItemHighlight Rectangle by selecting it and clicking the Trashcan icon. This default roll-over effect will be replaced by an effect you'll define shortly.
9. Use the Properties panel to set the color of the rectangle that provides the background for the item renderer (see Figure 20).

10. Navigate out of the data list component and return to the main application user interface.

    Optional: You can use the Design-Time Data panel to add dummy data so as to see how your user interface will render typical data values (see Figure 21); add/remove rows and edit the text in each row and Flash Catalyst will update the artboard accordingly.

Next, you need to ensure that the scrollbar is attached to the data list component, so that in the completed application the user can scroll through the search results.

11. Select the scrollbar component and press Ctrl+X (Cmd+X) to cut it. Next, double-click the data list component to edit it and then paste in the scrollbar. This automatically associates the scrollbar with the data list.

Define the user interface states and navigation

Next, you'll define the different states of the application user interface as well as specifying the user interaction required to navigate between those states.

1. Double-click the Page 1 text in the Pages/States panel and rename the state to Detail. Then click the Duplicate State button to make a copy of the current state; rename this new state to List.

With the List state selected (indicated by a light blue background) you need to make the necessary changes on the artboard to represent the user interface for this state.

2. In the Layers panel, use the context menu on the right panel folder and select the Group menu option; this will allow you to perform transitions on the group, rather than each individual element later in the tutorial.
3. Click the eye icon next to the right panel folder to make that folder invisible (see Figure 23); this has the effect of removing any items contained within the folder from the List state.

You should also hide the minimize (<) button using the same technique, as this will not be shown in the List state.

4. Use the Selection tool (the black arrow in the Tools panel) to move the Close button and the Signed In indicator, and then to resize the panel. The List state for your application should look similar to Figure 24.

5. Now duplicate the List state in the Pages/States panel and rename the newly created state Search. The Pages/States panel should now show three states: Detail, List, and Search (see Figure 25).

6. Apply the same techniques as before to amend the user interface presented in the Search state so that it is similar to Figure 26.

7. When your application loads in the browser, you want the user to initially be presented with the Search state. By default Flash Catalyst will show the first state, which in this case is actually the Detail state. To change this, use the context menu on the Search state in the Pages/States panel and select the Set as Default State option (see Figure 27).

Now that you've defined the states of your application, you need to specify what will trigger the actual change of state when the application is running; typically this will be in response to the user interacting with user interface elements.

1. With the search Text Input component selected in the Search state click the + Add Interactions button in the Interactions panel. You will see a number of interactions that are available for use with the Text Input component listed.

   You want to display the List state of the application after the user has typed his or her search criteria and then pressed Enter on the keyboard, so the trigger here will be the On Enter interaction (see Figure 28).

2. Select the On Enter interaction and then, using the popup menus, select Play transition to state in the first; then, in the second, select the state you want to show the user, so select List.
3. Now move to the List state using the Pages/States panel and select the Data List component on the artboard. You'll need to repeat the process for the Text Input component, however, note that the list of custom interactions for a Data List is different. Select the On Change interaction > Play transition to State > Detail so that the application will display the Detail state when the user selects an item from the list of employees (see Figure 29).

4. Finally, move to the Detail state; select the minimize button (<) and apply a custom interaction such that when users click the button, the application will display the List state; repeat the operation with the Close button (x), but this time the interaction should cause the Search state to display.

Applying transitions between states

Although you could just have the application jump between different states, it is likely that you'll want to apply smooth transitions that provide users with a sense of context as to where they have come from and where you're taking them to in the application user interface.

You can apply such transitions between states using the Timelines panel.

1. If it is not already visible, then double-click the panel header to display it. You should see a list of state transitions for the application, none of which have any timeline-based animations specified as of yet (see Figure 30).

2. You can apply a default set of transitions between states by selecting the desired State transition from the list on the left side (in this case you're working with the Search > List transition) and then clicking the Smooth Transition button (see Figure 31).

Although this is most likely an improvement over the static movement between states, if you test the animation by clicking the Play button in the Timelines panel you'll see that the order and length of the individual animations could be improved to provide a better effect.

3. Try adjusting the position of the Fade and Move operations as shown in the timeline in Figure 32, and then extend the length of the Resize effect. Experiment with applying timeline-based effects between different states of the application.

Note: In addition to previewing the animations using the Timelines panel, you should always test the state transitions by running the project to ensure that you get the desired effect when the application is deployed.

The final step you need to complete is to export the project so that a developer can undertake further development of the application in Flash Builder.

4. From the File menu, select Save As and save an FXP file to a location of your choice. This file can be opened in Flash Catalyst, should you wish to make further changes to the project, or you can pass the FXP file to a developer who can import it using Flash Builder.

In this part, you'll work with the project file created in Flash Catalyst to create a fully functional application in Flash Builder 4. You'll define data services, implement the search, bind the results to the data list control, and generate a form that displays the details of the selected employee.

1. Launch Flash Builder, open the File menu, select the Import FXP option and in the resulting dialog box browse to the location of the file named employee_app.fxp.

2. Click Finish and Flash Builder will perform the import operation and create a new Flash Builder project named employee_app.
3. Examine the project that has been imported from the FXP file; expand the project using the Package Explorer or navigate through the code using the Outline panel.

You'll see the following:

• The project contains a number of skin and item renderer MXML files within the components package.
• The main application file, Main.mxml, contains the following significant blocks of code:
  • The outer DesignLayer element, which contains all the visual MXML markup for the application.
  • The transitions element, which specifies all the transitions created by the interaction designer.
  • The states element, which specifies the application states.
• The Flash Builder design view correctly presents the application user interface and the States panel can be used to move between each of the application states defined in Flash Catalyst.

Optional: Note that Flash Catalyst has named various component skins and item renderers in the components package using default values, such as Button1.mxml, RepeatedItem1.mxml. You can rename these to more meaningful names; use the context menu for each item, choose Rename and be sure to update references to the file using the dialog box presented on screen.

Set up the ColdFusion sample service

Note: If you prefer to use PHP, deploy the Employees.php file to the services directory located in the PHP webroot. Use the employees.sql file to create the Employees table in a MySQL database. The sample assets that accompany this article include the PHP service.

Now that you have a basic understanding of the project structure you can move on to use the new data-centric development (DCD) features in Flash Builder.

1. Open the Data/Services panel and select the Connect to Data/Service link. Alternatively, you can select Data > Connect to Data/Service from the menu bar.
   

The next dialog box presents a number of options for connecting to data services. For this tutorial, you will connect to a ColdFusion service, but the process for using any of the other back-end technologies listed in this dialog box is similar (see Figure 36).

2. Deploy the employees.cfc file to the directory com.employee.services located in the ColdFusion webroot. For a ColdFusion 8 installation, use the built-in web server, located at <cfinstall>/wwwroot/.
3. Use the employees.sql file to create the Employees table in a MySQL database.
4. In the ColdFusion administrator, create a connection to the database named employees.

   When you imported the project from Flash Catalyst, Flash Builder created a generic Flex project type; however, to connect to data services that rely upon BlazeDS, ColdFusion, LiveCycle Data Services, or PHP, you need to use a Flex server project type.

   Flash Builder will alert you to this issue and allow you to change the server settings for the project (see Figure 37).

For a project that uses ColdFusion, select Flex Server and the Application server type ColdFusion (see Figure 38). You should also select the "ColdFusion Flash Remoting" option and provide the necessary server location details for your ColdFusion installation.

Note: For additional configuration information or for instructions for PHP, BlazeDS, or LiveCycle Data Services, refer to the Flash Builder documentation.

5. Click the Validate Configuration button and then check that the compiled Flex application location is correctly defined as a subdirectory on your server.

   After making the above changes, you'll be presented with the New Flex Service dialog box (shown in Figure 39). You'll use this dialog box to configure the service that you want to use in your application.

6. Flash Builder can generate a sample ColdFusion component (CFC), which you can use as a template to implement the required database access functionality. You'll use an existing CFC in this tutorial, therefore you should specify the CFC location using the Browse button (see Figure 39).

This CFC implements a number of methods to perform create, read, update and delete (CRUD) operations; the CFC also supports the paging and data management features in Flash Builder. In this tutorial, however, you will only make use of the getAllItems operation; this method takes a string value that is used to search the database, returning a list of employees.

When you click Finish, Flash Builder will generate ActionScript classes under the "services.employees" package; these will be used when accessing the ColdFusion service from within the application.

8. Before you can use the getAllItems operation, you need to configure the type of data that it will return. To do that, select getAllItems from the list of operations in the Data/Services panel, then click the Configure Return Type button in the panel toolbar, or use the context menu to select the same option.

   This opens the Configure Operation Return Type dialog box (see Figure 41). Use this dialog box to invoke the getAllItems operation, verify the data that is returned from the operation, and define a return type that you can use in our application. Ensure the option "Auto-detect the return type from sample data" is selected, and then click Next..

9. You will need to invoke the operation so that Flash Builder can understand the type of data that is being returned. Because the operation you are using requires an argument named search, you need to supply this. Select the type as String and enter a value to use as the argument. In the example in Figure 42, you are searching for employees whose surname begins with the letter s; you could enter any letter here or the empty string '' to return all values.

10. Click Next. Flash Builder will invoke the operation and display the properties and types for the data type (see Figure 43). Each item in the array received from the service will represent a single employee, so specify the data type as an Array of "Employee" and then click Finish.

Bind your data to visual components

You are now ready to bind the data returned from the getAllItems operation to a visual component, so as to display the data to the user. You can bind such operations to ComboBox, List, DataGrid and charting components. For your application you want to bind the data to the List control created in Flash Catalyst.

1. In Design view, ensure the List state is selected using the States panel and then select the List control (it has been given an ID of list1 by Flash Catalyst; you can change this using the Properties panel). With the List selected, click the Bind control to Data icon in the Data/Services panel (see Figure 44), or, alternatively, use the context menu to select the Bind to Data item. You can also select the operation GetAllItems from the Data/Services panel and drag and drop it onto the List control in design view.

Because you assigned some dummy data to the list using the Design-Time Data panel in Flash Catalyst, Flash Builder will ask you to confirm that you want to replace the existing data binding with the result of a new service operation (see Figure 45).

2. You need to confirm which operation you want to bind to the List control; if it is not displayed already then you should select the Employees service and choose the getAllItems(…) operation (see Figure 46).

The default behaviour for a List is to display a string as a Label for each item that exists in the returned collection; Flash Builder provides a popup down list of the available fields from the Employee data type that can be displayed in the List. You should select the empty field, however, because you are going to amend the custom item renderer for the List control that was generated by Flash Catalyst. This will allow you to have more control over how each item in the List is displayed.

3. Click OK. Flash Builder will switch to code view and you'll see that an event handler function for the creationComplete event on the List component has been defined. When the component has finished rendering, this will be called to invoke the getAllItems operation and the returned data will be displayed in the List.

   Although this may be suitable in some situations, you want to initiate the call when the user enters search criteria into the Text Input control, so you'll need to make some amendments here.

4. Locate the Text Input control and give it an id of search. Next, locate the event handler function for the enter event on the Text Input in the Script block, it should be called TextInput_enter()—this function will be called when the user presses the Enter key after typing a search term in the Text Input box.
5. Copy the code from the list creationComplete event handler, paste it into the newly generated event handler for the enter event and then delete the, now empty, creationComplete event handler. Also be sure to remove the reference to the creationComplete event from the List control itself (see Figure 47).

6. You want the search criteria to be defined as whatever the user entered into the search Input Text control; to do this alter the argument for the employees.getAllItems function call so that you are referencing the text in the TextInput control, that is employees.getAllItems(search.text).
7. To define what should be displayed in the List we will edit the item renderer for the component; this is defined in the components.RepeatedItem1.mxml file.

   Open the file and change the text attribute of the RichText control to read as follows:

8. Save the file and then run the application to verify that the when you submit a search you see the expected results displayed in the list.
9. Return to the main application file and switch to Design view; you're now going to specify the detailed information to display about the selected employee. With the List state selected, right-click the List component and select Apply Current Properties to All States. Select the Detail state in the States panel and then right-click the List component and select Generate Details Form from the menu (see Figure 48).

10. Although you can use Flash Builder to generate editable forms, you want to use the form only for displaying employee information. In the dialog box that is displayed verify that you are generating a form for the Employee data type, and ensure that the Make for editable check box is cleared (see Figure 49), and then click Next.

11. Rather than display all the properties defined for the Employee data type, you just want to show the employee number, birth date, phone number, job title, and email address. Uncheck the properties that are not required and for each required property ensure that the Control to be used is defined as Text (see Figure 50).

12. Click Finish and Flash Builder places the generated form on the design surface. Select it and drag it into position as shown in Figure 51.

13. Use the Properties panel to adjust the font size and color so that the design of the form is consistent with the application user interface. You can also choose to edit the label text for each form item if you wish (see Figure 52).

When you run the application you will see that, as you select different employees from the list of search results, the detail form that you just created will update automatically to show the details of the selected employee.

Where to go from here

I leave it to you, as an exercise, to change the static text representing the user's first name and last name in the Detail state to the correct values—you'll need to edit the value of the text and bind it to a property of the employee object.

You may also want to use a DateFormatter to ensure that the user's date of birth is displayed in an easier to read format. Check the documentation on the DateFormatter class in the Flex API reference for an example as to how to do this.

To learn more about Flash Catalyst, check out the resources and tutorials in the Flash Catalyst Developer Center.

Also be sure to visit the Flash Catalyst team blog for news and topics of interest.