Deploying a Flex application with ColdFusion URL variables

As an experienced ColdFusion developer, you have worked with URL, Form, and other types of variables to dynamically update data in your applications in response to user interactions. Using the concepts in this tutorial, you can easily embed your Flex application code in a CFM page and pass ColdFusion variables to it that will appropriately update the display.

In this tutorial, you will build the Fictitious Quarterly Sales Planner application shown in Figure 1. After you set up the database and review the provided CFC, you will lay out the ColumnChart control using Adobe Flash Builder 4. Next, you will bind data to the control from a service operation that is mapped to a ColdFusion component (CFC) function.

The header of the application (with the logo, welcome message, and region tabs) is built with ColdFusion, HTML, and cascading style sheets (CSS). As a user clicks each region tab, he will pass a URL variable to the application, which will refresh the chart display with that region's information. Note that the figure shows the specified region variable in the URL string.

This tutorial does not attempt to replace ColdFusion charts with charts built using Flash Builder 4. You will want to use Flash Builder for much more interactive displays that cannot be created using ColdFusion alone. However, for simplicity's sake, you are building a straight-forward chart example to strip away any complexities in learning how to embed the SWF file into a CFM page and how to pass URL variables into the HTML embed code that, in turn, passes the variables into the application.

You can skip the steps above if you have already successfully completed the "Getting started with ColdFusion and Flash Builder 4 " tutorial or any other tutorial in this series.

This tutorial was intended for:

• Experienced ColdFusion developers without previous Adobe Flex framework or Adobe Flash Builder 4 experience.
• ColdFusion developers who are familiar with ColdFusion components.

Configuring the data return type

As mentioned in the introduction, this tutorial uses the same development environment as the Getting started with ColdFusion and Flash Builder 4 tutorial and the other tutorials in this series. In this section, you will name a second data type for use with a different service call to a CFC function.

1. Locate the Data/Services view in Flash Builder 4. You should see the F4CF_Getting_Started_Service service shown in Figure 2.

2. Expand the Data Types category. If you see the EmployeeDataByRegion data type listed (also shown in Figure 2), then you can skip to the next section, Creating the application with a column chart.
   

If you do not see the data type, follow the steps below to assign your own data type name to the returned data that is retrieved in the getAllData() service call to the CFC method.

1. In the Data/Services panel, right-click the getEmployeeDataByRegion() function of the F4CF_Getting_Started_Service and select Configure Return Type to open the Configure Operation Return Type dialog box (see Figure 3).

Each record from the query has been placed in an ActionScript object with each column of data (FIRSTNAME, LASTNAME, EMAIL, and so on) set in a name/value pair. Each record is indexed starting at zero.

Note: Unlike ColdFusion, ActionScript is a zero-indexed language.

Rather than generically referring to this returned data as an object, this wizard lets you give the data a return type name. You will do this next.

2. In the Configure Return Type dialog box, leave the default radio button set to Auto-detect the return type from sample data. Check the box next to Authentication required. (see Figure 4).

3. Click Next.
4. In the Auto-detect Return Type dialog box, in the Enter Value column, type Central (see Figure 5).

5. Leave the radio button selected to Enter a name to create a new data type, and enter EmployeeDataByRegion in the Array of input field (see Figure 6).

6. Click Finish.

You will see the EmployeeDataByRegion data type listed in the Data Types category of the Data/Services view (see Figure 7). Note that the properties of the data type are the query columns returned from the CFC method.

The data returned from the CFC contains employee information that is associated with a region: Northwest, Southwest, Central, Northeast, and Southeast. Later in this tutorial, you will learn more about passing dynamic data to Flash applications. For now, you will hard-code the region value.

Creating the application with a ColumnChart

In this section, you will bind the returned results of the getEmployeeDataByRegion() operation to a Flex framework ColumnChart control. You will not need to write any code to accomplish this; instead you will use a built-in Flash Builder wizard to generate all the code.

Adding a ColumnChart control to the layout

In this section, you will use the drag-and-drop capabilities in Flash Builder Design mode to add your ColumnChart component.

1. In the F4CF_Getting_Started project, close all open MXML files.
2. Create a new application file by selecting File > New > MXML Application from the menu.
3. Name the file F4CF_Deploying_Flex.mxml and set the Layout dropdown list to None.
4. Click Finish.

   Note: In practice you will usually have only one main application file in a Flash Builder project. You will create a new main application file for each tutorial you follow in this series to avoid creating additional Flash Builder projects.

5. Switch to Design mode by clicking the Design button below the Editor view tab (see Figure 8).

6. From the Charts folder of the Components view, drag and drop a ColumnChart control into the design area (see Figure 9).

7. In the dialog box that appears, change the ID of the chart to YTDChart (see Figure 10).

The ID property is the unique identifier for this ColumnChart control and can be used by the application, and you, for programmatic manipulation of the component. The chart will display the year-to-date sales amount sold by the employee.

8. Click OK.

Note: You may need to click the Refresh button to the right of the Design mode to display the chart. You can also double-click the Editor tab that contains the MXML file name to expand and collapse the design area.

If the legend shows up in the upper left corner of the Design area, drag and drop it next to the ColumnChart control.

Binding data to the ColumnChart

In this section you will bind data to the ColumnChart control.

1. In the Data/Services panel, drag and drop the getEmployeeDataByRegion() function onto the ColumnChart control (see Figure 11).

You should see the Bind To Data dialog box (see Figure 12). Note the table below the Configure chart heading with the two columns: Series and Y Field.

2. Click the cell in the Y Field column.

   You'll see a popup list with all the properties from the getEmployeeDataByRegion() service operation.

3. Select YTD from the dropdown list.

   The Y Field is the Y-axis property of the ColumnChart control. When you select the data field in the popup list, it will be displayed along the vertical axis for the chart.

4. Select FIRSTNAME from the popup list next to the x axis field at the bottom of the dialog box.

The x axis field is the X-axis property of the ColumnChart control. When you select the data field in the popup list, it will be displayed along the horizontal axis for the chart.

5. Click OK.

   You will be switched to Source mode with the region attribute highlighted in the getEmployeeDataByRegion() function call of the ColumnChart control click handler function (see Figure 13). Remember that the region attribute is an expected value of the CFC function.

6. Replace the variable region with a string value of 'Central'.

   Remember that you are hard-coding this value initially in the tutorial. You will learn how to pass dynamic data using this variable later in the tutorial.

7. Save the file and and click the Run (round green) button on the toolbar to run the application (see Figure 14), or select select Run > F4CF_Generating_Forms.

You should see the ColumnChart control with YTD values in the Y-axis and Employee name in the X-axis (see Figure 15).

Integrating the application into a ColdFusion web page

In this section, you will integrate the generated HTML wrapper code created by Flash Builder with HTML and CSS code in a ColdFusion web page.

Displaying the application in a CFM page

In this section, you will learn about how to turn the HTML wrapper file into a CFM file that displays a custom header.

1. In Flash Builder, select Project > Properties from the menu.
2. Select Flex Compiler and look at the HTML wrapper section towards the bottom of the dialog box (see Figure 16).

By default, Flash Builder is set to generate an HTML wrapper file for the compiled SWF file.

3. Cancel the dialog box and expand the html-template directory of this project in the Package Explorer (see Figure 17).

The html-template directory contains files that will be used to generate the HTML wrapper code for the compiled SWF file.

4. Locate the F4CF_Deploying_Flex.html file in the \wwwroot\F4CF_Getting_Started-debug directory.

   This file is the generated HTML wrapper code.

   Note: For more information about the HTML wrapper file and its supporting files, see Deployment assets.

5. Download the provided f4cf_deploying_app.zip file that accompanies this tutorial if you haven't done so already. Unzip the file to the \wwwroot\F4CF_Getting_Started-debug folder.

   Make sure that the CompanyHeader.cfm file is at the same level as the F4CF_Deploying_Flex.html file and that the assets folder is directly inside of the F4CF_Getting_Started-debug folder.

6. Open the F4CF_Deploying_Flex.html file in a code editor.

   Figure 18 shows the code that embeds the compiled SWF file for the application.

7. Close the F4CF_Deploying_Flex.html file and rename it F4CF_Deploying_Flex.cfm, with the .CFM file extension.
8. Open the F4CF_Deploying_Flex.cfm file in a browser through your ColdFusion server.

You should see the ColumnChart shown in Figure 19.

In Flash Builder, select the Project menu. By default, the Build Automatically menu item is selected. This means that every time you make a change to your MXML or ActionScript code and save your files, the SWF file will be recompiled and the HTML wrapper file will be re-generated. You can ignore the new HTML file that will be generated throughout the rest of this tutorial.

Adding region links to the ColdFusion page

Remember that this chart will show the sales numbers for employees by region. In this section, you will add a header that displays the regions as links that self-reference this CFM page.

Earlier in this tutorial, you hard-coded the region value in the data service call to the Central region. In this section, you will also pass a URL variable in the region links for use in the application.

1. Open the F4CF_Deploying_Flex.cfm file in a code editor.
2. After the opening <body> tag around line 57, include the CompanyHeader.cfm file using the cfinclude tag as shown in the following code:

This will add a header to the ColdFusion page and show the five regions as links.

3. Save the file and run it in a browser.

You will see a page with a ColumnChart and region hyperlinks (see Figure 20).

If you click the NorthWest Region hyperlink, you will notice that the page reloads and that the url parameter of region=Northwest is added to the query string in the URL. The other hyperlinks will also load the page with the corresponding name/value pair for the region. This is accomplished by the code in the CompanyHeader.cfm:

Styling the links into tabs

In the following steps, you will apply the provided stylesheet to the display to format the tabs.

1. Open the F4CF_Deploying_Flex.cfm file in the code editor.
2. Locate the <style> tag block around line 21.
3. Change the text-align property to left as shown in the following snippet:

4. Save the file and run it in a browser.

   You will see that the bulleted list of links is aligned to the left of the page instead of to the center.

5. Above the <style> tag block, add the following code to use the style sheet provided with the sample files for this tutorial.

6. Save the file and launch it in a browser.

You will see the formatted tabs shown in Figure 21.

Using the URL variables in the application

In this section, you will learn how pass the URL variables into the application.

Adding flashvars to the CFM file

As an experienced ColdFusion developer, you have used URL variables in your application development and you know that the URL variables can be printed to the HTML content. In this case, you will print the URL variables into the JavaScript code that embeds the SWF file.

1. Return to the F4CF_Deploying_Flex.cfm file in the code editor.
2. Locate the swfobject.embedSWF() method call to embed the SWF file:

Note that an object named flashvars is one of the arguments in the method call. You can create custom name/value pairs in this object to pass to the application from this embed code.

3. Locate the following line of code further up within the same <script> tag block:

4. Add the following code below that line:

This code creates a property named region in the flashvars object with a value that is dynamically set to the region variable that is passed in the URL query string.

Retrieving the url parameter

Earlier in this tutorial you had hard-coded the value for the region to Central. Now that you are passing the region into the application via the flashvars object, you can access the property and use it to update the ColumnChart control.

1. Return to Flash Builder and open the F4CF_Deploying_Flash.mxml.
2. Switch to Source mode to view the code.
3. In the <s:Application> tag, add the initialize event to call a function named init, as shown in the following snippet:

The initialize event is a system event that is triggered when the application loads. You will create a function, named init(), that will be run every time the application loads.

4. Locate the <fx:Script> tag block and below the import statement, create the init() function using the keywords private and function:

5. Declare that the function does not return any values by adding the :void data type to the end of the init() function declaration:

6. Above the new function, but below the import statement, add a variable named region using the private var syntax, data type it to a String and set it to Central:

    

This code creates a String variable within the application named region with a default value of Central.

7. In the init() function, populate the region variable with a value of this.parameters.region:

The property/value pairs that you passed into the application using the flashvars object is referenced in the ActionScript this.parameters object.

8. Change the hard-coded value of Central in the getAllData() service call to the region variable that you just populated (see Figure 22).

9. Save the file.

   Remember that a new SWF file will be compiled when you save the file and will be placed in the F4CF_Deploying_Flex-debug folder in your ColdFusion webroot.

10. Browse to the F4CF_Deploying_Flex.cfm file using a URL that includes a region, for example, http://localhost:8500/F4CF_Getting_Started-debug/F4CF_Deploying_Flex.cfm?region=Northwest.

Now, when you click the region tabs, you will see data from that region.

Where to go from here

In this tutorial you learned about the HTML wrapper file, the flashvar object, and how to use these elements to integrate your compiled Flex application with ColdFusion code and how to pass URL variables into the SWF files.

For more information on how to use style sheets and details on the tab implementation, please refer to the following links:

• CSS structure and rules
• Using style classes and IDs
• Using multiple classes within selectors

To learn more about flashvar objects, refer to Peter deHaan's Flex Examples blog.