Macromedia FLEX BUILDER-USING FLEX BUILDER User Manual

Using Flex Builder

Trademarks

ActiveEdit, ActiveTest, Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware, Authorware Star, Backstage, Blue Sky Software, Blue Sky, Breeze, Bright Tiger, Captivate, Clustercats, ColdFusion, Contents Tab Composer, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, Help To Source, HomeSite, Hotspot Studio, HTML Help Studio, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia, Macromedia Action!, Macromedia Central, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra, Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC Logo and Design, Mediamaker, Movie Critic, Open Sesame!, RoboDemo, RoboEngine JFusion, RoboHelp, RoboHelp Office, RoboInfo, RoboInsight, RoboPDF, 1-Step RoboPDF, RoboFlash, RoboLinker, RoboScreenCapture, ReSize, Roundtrip, Roundtrip HTML, Shockwave, Sitespring, Smart Publishing Wizard, Software Video Camera, SoundEdit, Titlemaker, UltraDev, Web Design 101, what the web can be, WinHelp, WinHelp 2000, WinHelp BugHunter, WinHelp Find+, WinHelp Graphics Locator, WinHelp Hyperviewer, WinHelp Inspector, and Xtra are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites.

Copyright © 2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual provided with the software for the sole purpose of learning to use such software by such owner or authorized user; provided, that no part of this manual may be printed out, reproduced, distributed, resold or transmitted for any other purposes, including without limitation, commercial purposes, such as selling copies of this documentation or for providing paid for support services

Acknowledgments

Senior Management: Sheila McGinn

Project Management: Charles Nadeau

Writing: Charles Nadeau

Editing: Lisa Stanziano, Mary Ferguson, Rosana Francescato, Linda Adler

Production Management: Patrice O’Neill

Media Design and Production: John Francis, Adam Barnett, Aaron Begley

Special thanks to Heidi Bauer-Williams, Gabe Chua, Larry McLister, Paul Gubbay, Brad Becker, David Lenoe, Lucian Beebe, Lori Hylan-Cho, Mark Shepherd, Tanya Dimalsky, Matthew Hoffberg, Jon Varese, Dave George, Brandon Purcell, Stephen Gilson and the Flex IMD team, the beta testers, and the entire Flex Builder engineering and QA teams.

Second Edition: December 2004

Macromedia, Inc. 600 Townsend St.

San Francisco, CA 94103

CHAPTER 1: Getting Started with Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Exploring the authoring environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Starting a new application in Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Defining a site for the Flex Sample Apps application. . . . . . . . . . . . . . . . . . . . . . . 12

Getting help in Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

What you need to build Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Typographical conventions of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

CHAPTER 2: Flex Builder Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Tutorial: Setting up a development environment. . . . . . . . . . . . . . . . . . . . . . . . . . 21

Tutorial: Creating a layout with Flex Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Tutorial: Building custom components with Flex Builder . . . . . . . . . . . . . . . . . . . 34

Tutorial: Binding components to data with Flex Builder . . . . . . . . . . . . . . . . . . . . 58

Next steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

CHAPTER 3: Creating, Coding, and Debugging Flex Files . . . . . . . . . . . . . . . . . . 75

Creating MXML or ActionScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Working with the code in Flex files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Testing and debugging Flex files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

CHAPTER 4: Building a Flex User Interface Visually . . . . . . . . . . . . . . . . . . . . . . 95

Customizing the Document window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Laying out your user interface with MXML containers . . . . . . . . . . . . . . . . . . . . . 97

Adding Flex components to the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Repositioning Flex components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Resizing Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Cutting, copying, and pasting Flex components . . . . . . . . . . . . . . . . . . . . . . . . . 100

Editing Flex component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Applying CSS styles to Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Applying effects to Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Assigning event handlers to components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

CHAPTER 5: Working with Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Inserting controls and containers in an MXML file . . . . . . . . . . . . . . . . . . . . . . . 117

Creating MXML component files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Synchronizing with custom components on the server . . . . . . . . . . . . . . . . . . . . 125

CHAPTER 6: Working with Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Binding a control or container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Editing a binding visually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Working with Flex data models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Working with Flex data services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

APPENDIX A: Basic Flex Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

About the Flex application model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Typical application development steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

About Flex files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

About Flex containers, components, and controls . . . . . . . . . . . . . . . . . . . . . . . . 148

About Flex data bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

4 Contents

CHAPTER 1

Getting Started with Flex Builder

This chapter provides an overview of Macromedia Flex Builder and steps to get started developing Flex applications.

Flex Builder is an integrated development environment (IDE) for Flex developers. Because it’s tightly integrated with the Macromedia Flex server, the Flex application model, and the Flex programming languages, Flex Builder can improve the productivity of all members of your development team.

This guide focuses on Flex Builder. If you’re new to Flex, you may want to review Appendix A,

“Basic Flex Concepts,” on page 145. For in-depth information about Flex (as opposed to Flex

Builder), see Developing Flex Applications Help and the Flex ActionScript and MXML API Reference Help.

The following topics are covered in this chapter:

• “Exploring the authoring environment” on page 5

• “Starting a new application in Flex Builder” on page 9

• “Defining a site for the Flex Sample Apps application” on page 12

• “Getting help in Flex Builder” on page 17

• “What you need to build Flex applications” on page 18

• “Typographical conventions of this guide” on page 20

Exploring the authoring environment

The Flex Builder IDE lets you write, edit, debug, and preview MXML and ActionScript files, and includes the following features:

The Start page provides links to quickly define a site, create and open files, and access useful

information about Flex Builder. For example, you can take a quick tour, explore Flex samples, take tutorials, and learn about debugging in Flex Builder.

Design view (View > Design) lets you lay out and edit an MXML user interface visually. Design

view has two modes: Expanded and Standard. In Expanded mode, you can easily insert, edit, position, or resize MXML components because Flex Builder adds temporary borders and padding around objects. In Standard mode, Flex Builder removes the borders and padding to give you a more accurate picture of how the MXML file will look in Macromedia Flash Player.

Code view (View > Code) lets you work with code. MXML and ActionScript syntax is color-

coded and code hints assist you as you type. Design view tools such as the Insert bar, Tag inspector, and Data panel are also fully functional in Code view.

The ActionScript debugging panels help you debug your code after setting breakpoints and

switching to debug mode. The debugging panels include the Variables panel, the Watch panel, the Output panel, and the Call Stack panel. For more information, see “Debugging ActionScript”

on page 87.

The Network Monitor panel helps you monitor network traffic and data going back and forth

between the client and the Flex server. For more information, see “Debugging applications by

monitoring interactions with the server” on page 91.

The Insert bar lets you rapidly insert Flex containers and components in Design view by clicking

or dragging. The Insert bar also lets you rapidly insert their tags in Code view.

Note: The Favorites tab found in Macromedia Dreamweaver is not supported in Flex Builder.

6 Chapter 1: Getting Started with Flex Builder

The Tag inspector lets you set the properties of containers and components in the file. You can

also use it to apply effects, specify event handlers, modify CSS styles, and create data bindings.

The Tag inspector replaces the traditional Property inspector in Dreamweaver. While you can still use the Property inspector for editing HTML and other document types in Flex Builder, it is disabled when you work on MXML or ActionScript files.

The Bindings panel in the Tag inspector lets you visually bind components, Flex data models,

and Flex data services to other components, data models, and data services. After creating the binding, data can pass between the objects at runtime.

Exploring the authoring environment 7

The Data panel lets you inspect the data services (such as web services) and data models in the

current MXML file, as well as insert or delete services in the file.

You can work in Design view, Code view, or both.

To switch between Design and Code views:

Open any MXML file in Flex Builder by double-clicking the file in the Files panel (Window > Files).

If you’re in Code view and you want to work in Design view, do one of the following:

■ Click the Design button on the Document toolbar.

■ Select View > Design.

■ Press Control+’ (the slanted quotation mark that usually shares the tilde (~) key).

Note: You can’t work on ActionScript files in Design view. Because ActionScript files don’t render in Flash Player, they would appear blank in Design view. As a result, Flex Builder always displays ActionScript files in Code view.

If you’re in Design view and you want to work in Code view, do one of the following:

■ Click the Code button on the Document toolbar.

■ Select View > Code.

■ Press Control+’ (the slanted quotation mark that usually shares the tilde (~) key).

To split the view to see both Design and Code views, do one of the following:

■ Click the Split button on the Document toolbar.

■ Select View > Code and Design.

To place Code view on a separate monitor, open the Code inspector (Window > Code Inspector or F10) and position it on the second monitor.

For more information on the coding environment, see “Working with the code in Flex files”

on page 76. For more information on the visual environment, see Chapter 4, “Building a Flex User Interface Visually,” on page 95.

8 Chapter 1: Getting Started with Flex Builder

Starting a new application in Flex Builder

The first step in creating any new Flex application in Flex Builder is to define a Flex Builder site. A Flex Builder site is analogous to a project in other development environments: it lets you manage files and transfer them to the computer running the Flex server. A Flex Builder site also lets you visually design, preview, and debug MXML and ActionScript files without leaving Flex Builder.

You need access to a Flex server before you can define a site. The server allows you to run and debug MXML and ActionScript files without leaving Flex Builder (see “What you need to build

Flex applications” on page 18). You can install the Flex server or consult your system

administrator. For information on installing the server, see Installing Flex on the Macromedia website at www.macromedia.com/go/flex_install/. For information on installing the server on the same computer as Flex Builder, see “Install the Flex server on your computer” on page 22.

This section covers the following topics:

• “Defining a Flex Builder site” on page 9

• “Identifying a Flex application root folder” on page 11

Defining a Flex Builder site

You can define a Flex Builder site quickly or with more advanced options, as follows.

To quickly define a Flex Builder site:

In Flex Builder, select Site > Manage Sites, click the New button on the Manage Sites dialog box, and select Flex Site from the context menu.

Tip: You can also click Flex Site on the Start page.

The Flex Server Site Setup dialog box appears.

Enter new values or accept the default values for your site.

Accept the default values only if you installed the Flex server on the same computer as Flex Builder using the integrated JRun/Flex install option.

For a list of possible settings for this dialog box, see “Examples of site settings” on page 15.

For more information, click the Help button.

Starting a new application in Flex Builder 9

To define a Flex Builder site with advanced options:

In Flex Builder, select Site > Manage Sites, click the New button on the Manage Sites dialog box, and select Site from the context menu.

The Site Definition dialog box appears. If the Basic tab is selected, click the Advanced tab and select Local Info from the Category list (it should be the default).

For possible settings for this dialog box, see “Examples of site settings” on page 15.

In the Local Info category, specify where you want to store your application files.

If the Flex server is installed on the same computer as Flex Builder, specify a Flex application root folder as the Local Root Folder. For more information, see “Identifying a Flex application

root folder” on page 11.

For more information on setting the Local Info category options, click the Help button on the dialog box.

(Optional) In the Remote Info category, specify where you want to upload or download files from a remote server.

Complete this category if the Flex server is running on a different computer than Flex Builder. This folder must be an application root folder on the server. For more information, see

“Identifying a Flex application root folder” on page 11.

If you are using FTP access, enter the Flex application root folder as the Host Directory value. If you are using network access, enter the Flex application root folder in the Remote Folder text box.

For more information on setting the Remote Info category options, click the Help button on the dialog box.

In the Testing Server category, select MXML for JSP from the Server Model pop-up menu.

In the Testing Server category, specify where Flex Builder can “test” your files—that is, how and where it sends the files to be compiled at design time.

Flex Builder sends MXML and ActionScript files to the server for compilation at design time so that you can preview Flex files, get debugging information, and connect to back-end systems.

Specify how and where to send the files as follows:

■ In the Access pop-up menu, select the method Flex Builder should use to send the files to

the server. Select Local/Network if you want to transfer the files to a local folder or to a remote folder with network access. Select FTP if you want to transfer the files to a remote folder using FTP.

■ In the Testing Server Folder text box, specify a folder where MXML and ActionScript files

can be compiled by the Flex server. This folder must be a Flex application root folder as specified in steps 2 or 3 above. For more information, see “Identifying a Flex application

root folder” on page 11.

10 Chapter 1: Getting Started with Flex Builder

In the URL Prefix text box, specify the URL prefix that Flex Builder should append to Flex file names.

To get a file compiled at design time, Flex Builder sends the file to the Flex application root folder and then attempts to request it using a URL—in effect Flex Builder becomes a client. Flex Builder deduces the correct URL by combining the URL prefix you specify with the file name.

For example, if your application’s URL is www.macromedia.com/flex/start.mxml, you enter the following URL prefix in the Testing Server category:

http://www.macromedia.com/flex/

If Flex Builder runs on the same computer as your Flex server, you can use localhost for your domain name, as follows:

http://localhost:8700/flex/

Note: The default port number is 8700. If you changed it during installation, use the appropriate number in the URL prefix.

For more information on setting the Testing Server category options, click the Help button on the dialog box.

Click OK to define the Flex Builder site and dismiss the Site Definition dialog box, and then click Done to dismiss the Manage Sites dialog box.

You can now start developing your application with Flex Builder.

Identifying a Flex application root folder

You must specify a valid Flex application root folder when defining a Flex Builder site. Flex Builder puts files such as MXML, ActionScript, CSS, and image files in this folder in order to run and debug files at design time. If the folder is not a valid application root folder, Flex Builder will not work properly.

To identify a folder as a Flex application root folder:

• Look for a WEB-INF/flex/ subfolder with a flex-config.xml file in it.

A Flex application root folder always has a WEB-INF/flex/ subfolder with a flex-config.xml file in it. For example, if you’re using JRun 4 as the J2EE server, the application root folder is as follows:

jrun_root/servers/server/Flex_app

where jrun_root is the J2EE server’s root folder, server is the name of a defined JRun server (such as “default”), and Flex_app is the application root folder. The Flex_app folder must contain a WEB-INF/flex/ subfolder with a flex-config.xml file in it, as follows:

Flex_app/WEB-INF/flex/flex-config.xml

Starting a new application in Flex Builder 11

For example, if you installed the Flex server on a Windows computer using the integrated JRun4/Flex install option, the application root folder of the default application is as follows:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\flex

In this example, the JRun root (jrun_root) is C:\Program Files\Macromedia\Flex\jrun4\, the JRun4 server (server) is called default, and the Flex application (Flex_app) is called flex. The flex folder has a WEB-INF\flex subfolder with a flex-config.xml file:

...\flex\WEB-INF\flex\flex-config.xml

For more examples, see “Examples of site settings” on page 15.

Defining a site for the Flex Sample Apps application

A Flex application called Flex Sample Apps is created when you install the Flex server using the integrated JRun4/Flex install option. This application provides a number of sample applications you can use to explore Flex and learn to work with Flex Builder. This section describes how to define a Flex Builder site to work with the Flex Sample Apps application.

Note: If you didn’t use the JRun4/Flex install option to install Flex, then you must deploy the samples .war file yourself.

For information on installing Flex server, see Installing Flex on the Macromedia website at

www.macromedia.com/go/flex_install/. For information on installing Flex server on the same

computer as Flex Builder, see “Install the Flex server on your computer” on page 22.

This section consists of the following sections:

• “Defining the site if the Flex server is local” on page 12

• “Defining the site if the Flex server is remote” on page 14

• “Examples of site settings” on page 15

Defining the site if the Flex server is local

This section describes how to define a Flex Builder site to work with the Flex Sample Apps application installed with the Flex server. The section assumes you installed the server on the same computer as Flex Builder using the integrated JRun4/Flex install option (see “Install the Flex

server on your computer” on page 22). For settings for other configurations, see “Examples of site settings” on page 15.

For information on setting up Flex Builder when the Flex server is on another computer,

“Defining the site if the Flex server is remote” on page 14.

To set up Flex Builder for the samples application if Flex is running locally:

In Flex Builder, select Site > Manage Sit es, click the New button in the Manage Sites dialog box, and select Flex Site from the context menu.

The Flex Server Site Setup dialog box appears.

Tip: You can also open this dialog box by clicking the Flex Site link on the Start page.

In the Site Name text box, enter Flex Sample Apps or something similar.

The name identifies your Flex Builder site.

12 Chapter 1: Getting Started with Flex Builder

In the Local Root Folder text box, click the folder icon and select the following folder:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\

This step tells Flex Builder where the application files are located on your hard drive.

In the Flex Server Root Folder text box, make sure the following path is specified:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\

This folder must always be a Flex application root folder on the server. To determine whether a folder is an application root folder, check to see if it has a WEB-INF/flex folder containing a flex-config.xml file. An application root folder always has this folder and file. For more information, see “Identifying a Flex application root folder” on page 11.

This step tells Flex Builder where it can “test” files—that is, where it can send MXML and ActionScript files to be compiled by the Flex server at design time. Flex Builder needs to get these files compiled so you can preview MXML files, get build and debugging information, and connect to back-end systems.

In the URL Prefix text box, enter the following URL:

http://localhost:8700/samples/

Note: The default port number is 8700. If you changed it during installation, use the appropriate number in the URL prefix.

To get the Flex server to compile files while you work, Flex Builder uploads the file to the application root folder you specified and attempts to request it using the URL prefix.

The Flex Server Site Setup dialog box should look as follows:

Click OK to define the site and close the Flex Server Site Setup dialog box, and then click Done to close the Manage Sites dialog box.

The Flex Sample Apps site is defined and you can start exploring, editing, previewing, and debugging the sample apps with Flex Builder.

Caution: You should make a backup of the samples folder so you can restore files if necessary.

Defining a site for the Flex Sample Apps application 13

Defining the site if the Flex server is remote

This section describes how to define a Flex Builder site to work with the Flex Sample Apps application if the Flex server is installed and running on a different computer than Flex Builder. For more information, see Installing Flex on the Macromedia website at www.macromedia.com/

go/flex_install/.

Before you start, you can review example settings for common J2EE servers. See “Examples of site

settings” on page 15.

To set up Flex Builder for the samples application if Flex is running remotely:

In Flex Builder, select Site > Manage Sites, click the New button on the Manage Sites dialog box, and select Site from the context menu.

The Site Definition dialog box appears. If the Basic tab is selected, click the Advanced tab and select Local Info from the Category list (it should be the default). You use the Local Info category to tell Flex Builder where the Flex application files are located on your hard drive.

In the Site Name text box, enter Flex Sample Apps or something similar.

The name identifies your Flex Builder site.

In the Local Root Folder text box, click the folder icon and specify where you want to store your files on your hard drive while you work on them with Flex Builder.

In the Remote Info category, specify where you want to put files to the remote server.

For this Flex Builder site, you must specify the folder called samples on the server. For example, if you installed Flex with JRun 4, the application root folder is as follows:

jrun_root/servers/default/samples

where jrun_root is the J2EE server’s root folder, default is the name of a defined JRun server, and samples is a Flex application root folder.

The remote folder for a Flex site must always be an application root folder on the server. To determine whether a folder is an application root folder, check to see if it has a WEB-INF/flex folder containing a flex-config.xml file. An application root folder always has this folder and file. The samples folder contains a WEB-INF/flex/ subfolder with a flex-config.xml file in it, as follows:

samples/WEB-INF/flex/flex-config.xml

For more information, see “Identifying a Flex application root folder” on page 11.

If using FTP access, select FTP from the Access pop-up menu and specify the samples folder as the Host Directory value, as well as any other FTP settings required to access that folder.

If using network access, select Local/Network from the Access pop-up menu and specify the network path to the samples folder in the Remote Folder text box.

For more information on setting the Remote Info category options, click the Help button on the dialog box.

14 Chapter 1: Getting Started with Flex Builder

Click Testing Server in the Category list to display the Testing Server settings.

You use the Testing Server options to tell Flex Builder where it can “test” files—that is, where it can send files to be compiled at design time. Flex Builder needs to get these files compiled so you can preview MXML files, get build and debugging information, and connect to back-end systems.

Select MXML for JSP from the Server Model pop-up menu.

This tells Flex Builder what kind of web application you’re developing.

In the Access pop-up menu, select the same access method you selected in the Remote Info category (FTP or Local/Network).

After you make your selection, Flex Builder automatically populates the rest of the dialog box based on the information you entered in the Remote Info category. This is only a best guest. Make sure the following values are used:

■ Testing Server Folder (if using Local/Network access) is identical to the remote folder in

the Remote Info category (.../samples)

■ FTP settings (if using FTP access) are identical to the settings in the Remote Info category

■ URL Prefix is an HTTP address Flex Builder can use to request a file in the testing server

folder, such as http://<hostname>/samples/.

To get a file compiled at design time, Flex Builder uploads the file to the testing server folder you specified and attempts to request it using the URL prefix.

Click OK to define the site and dismiss the Site Definition dialog box, and then click Done to dismiss the Manage Sites dialog box.

The Flex Sample Apps site is defined and you can start exploring, editing, previewing, and debugging the sample apps with Flex Builder.

Caution: You should make a backup of the samples folder so you can restore files if necessary.

Examples of site settings

This section lists Flex Builder site settings for the Flex Sample Apps application running on common J2EE servers. This application provides a number of sample applications you can use to explore Flex and learn to work with Flex Builder.

The Flex Sample Apps application is created when you install the Flex server using the JRun4/ Flex install option. If you don’t use this install option, you must deploy the samples .war file yourself.

Use the following settings in the Flex Server Site Setup dialog box. For more information, see

“Defining a Flex Builder site” on page 9. You can also use these settings in the advanced Site

Definition dialog box (if you access the server through a network). Enter the Flex Server Root Folder value in both the Remote Folder text box and the Testing Server Folder text box in the Site Definition dialog box.

Replace items in angle brackets with the information specific to your server configuration.

Defining a site for the Flex Sample Apps application 15

Caution: These site settings assume default installations of both the application server and the Flex server. The settings may not work for custom installations.

Integrated JRun4/Flex - Local Install

Local Root Folder: C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples

Flex Server Root Folder: C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples

URL Prefix http://localhost:8700/samples/

Non-integrated JRun4 - Local Install

Local Root Folder: C:\JRun4\servers\<servername>\samples\

Flex Server Root Folder: C:\JRun4\servers\<servername>\samples\

URL Prefix http://localhost:<port>/samples/

Tomcat 5.0 - Remote Install

Local Root Folder: Any folder on the computer running Flex Builder

Flex Server Root Folder: ...<installfolder>\Tomcat 5.0\webapps\samples

URL Prefix http://<hostname>:8080/samples/

WebSphere 5.1 - Remote Install

Local Root Folder: Any folder on the computer running Flex Builder

Flex Server Root Folder: ...<installfolder>\WebSphere\AppServer\installedApps\<nodename>\<ap

pname>.ear\samples.war (where <nodename> is the machine name—but could also be an IP or a fqdn—and <appname> is configurable at deploy time)

URL Prefix http://<hostname>:9080/samples/

WebLogic 8.1 - Remote Install

Local Root Folder: Any folder on the computer running Flex Builder

Flex Server Root Folder: ...<installfolder>\bea\user_projects\<domain>\applications\samples

(assumes you exploded the war file into a folder named samples to get a samples context root)

URL Prefix http://<hostname>:7001/samples/

16 Chapter 1: Getting Started with Flex Builder

Getting help in Flex Builder

Flex Builder has a variety of resources to help you develop Flex applications. You can get contextsensitive help about an MXML tag, find out how to use a Flex Builder feature, or look up a term in the Flex ActionScript Language Reference.

This section covers the following topics:

• “Context-sensitive help” on page 17

• “Flex Builder Help” on page 17

• “Macromedia website resources” on page 18

Context-sensitive help

While working in Code view, you can get context-sensitive help about MXML components.

To get help about an MXML component:

In Code view, click anywhere inside the MXML component’s tag.

Press F1.

Flex ActionScript and MXML API Reference Help opens and displays information about the tag.

You can also access this help from the Help menu.

Flex Builder Help

The Flex Builder Help menu gives you access to thousands of pages of information while you work. The following menu items can be useful for Flex developers:

Using Flex Builder describes how to use Flex Builder to develop Flex applications.

Developing Flex Applications is a code-centric developer guide that describes how to develop

Flex applications with MXML and ActionScript. The guide includes chapters on working with various controls, containers, and their properties.

Flex ActionScript Language Reference is a revised version of the ActionScript Reference Guide

included in Flash MX 2004. The reference also acts as a developer guide providing a good overview of ActionScript syntax, information on how to use ActionScript when working with different types of objects, and details on the syntax and usage of the language elements.

Flex ActionScript and MXML API Reference is an API reference for Flex developers.

Using Dreamweaver provides comprehensive, task-oriented information about Dreamweaver

MX 2004, the professional web authoring tool built into Flex Builder.

Getting help in Flex Builder 17

Macromedia website resources

The Macromedia website contains the following resources to support Flex developers:

Flex Builder support pages on the Macromedia website at www.macromedia.com/go/

fb_support/ helps you get the most out of Flex Builder. The website is updated regularly with the

latest information on Flex Builder, plus advice from expert users, examples, tips, updates, and information on advanced topics.

The Flex Support Center on the Macromedia website at www.macromedia.com/go/

flex_support/ provides information on Flex technology.

The Flex Documentation Center on the Macromedia website at www.macromedia.com/go/

flex_docs/ provides product manuals, tutorials, and articles about Flex.

Macromedia Developer Center on the Macromedia website at www.macromedia.com/go/

devnet/ provides tools, tutorials, and more for all Macromedia products.

The Flex online forum on the Macromedia website at www.macromedia.com/go/

flex_newsgroup.

What you need to build Flex applications

To develop and test Flex applications with Flex Builder, you need a computer running Microsoft Windows 2000 or Windows XP. For more information, see “System requirements for Flex

Builder” on page 19.

You also need the Flex server (see “About the Flex server” on page 20), which requires the following software:

• An HTTP web server (see “About web servers and Flex” on page 19)

• A J2EE application server (see “About J2EE application servers and Flex” on page 19)

You can quickly set up a Flex server by using the HTTP web server and J2EE server installed with the Flex server. For added convenience, you can install and run this software on the same computer as Flex Builder. For more information, see “Install the Flex server on your computer”

on page 22.

You can also configure the Flex server to work with third-party web servers and J2EE servers. For more information, see the Flex installation guide on the Macromedia website at

www.macromedia.com/go/flex_install/, or consult your system administrator. Generally, it’s best

to match your development environment to your production environment as closely as possible. For example, if you use Tomcat in your production environment, you may want to configure your development environment around Tomcat.

A Flex best practice is to place the code implementing the functionality or business rules of the application in a business layer. Flex is designed for building the presentation layer (or user interface) of multi-tier enterprise applications. There is no inherent database support. To access databases, you must connect your presentation layer to a business layer. For more information, see

“Flex data services” on page 152. The development of the business and data layers is beyond the

scope of this guide.

18 Chapter 1: Getting Started with Flex Builder

This section covers the following topics:

• “System requirements for Flex Builder” on page 19

• “About web servers and Flex” on page 19

• “About J2EE application servers and Flex” on page 19

• “About the Flex server” on page 20

System requirements for Flex Builder

The following hardware and software is required to run Flex Builder.

• Windows 2000 or Windows XP

• An Intel Pentium III processor or equivalent, 600 MHz or faster

• At least 256 MB of available RAM (512 MB recommended)

• At least 275 MB available disk space

• A 16-bit (thousands of colors) monitor capable of 1024 x 768 pixel resolution or better

(millions of colors recommended)

About web servers and Flex

To host websites containing Flex files, you need a web server, which is sometimes called an HTTP server. A web server is software that serves files in response to requests from web browsers using the HTTP protocol. Common web servers include Apache HTTP Server and Microsoft Internet Information Server (IIS).

If you select the integrated JRun4/Flex option when installing the Flex server, you don’t need a separate web server. JRun4 has a web server that’s installed and configured for you. For more information, see “Install the Flex server on your computer” on page 22.

If you plan on using Tomcat as your J2EE application server, you don’t need to install a web server either. Apache HTTP Server is built into Tomcat. For more information, see “About J2EE

application servers and Flex” on page 19.

For information on installing and configuring a web server, see the server vendor’s documentation or your system administrator.

About J2EE application servers and Flex

A J2EE application server helps the Flex server process MXML and ActionScript files.

If you select the integrated JRun4/Flex option when installing the Flex server, you don’t need a separate J2EE server. A J2EE server (JRun 4) is installed and configured for you. For more information, see “Install the Flex server on your computer” on page 22.

The following are the application servers supported by Flex:

• Macromedia JRun 4 with Updater 2. You can install JRun 4 with the Flex server by selecting

the integrated JRun4/Flex install option. You can also download a trial version of JRun 4 from the Macromedia website at www.macromedia.com/go/jun_trial/.

What you need to build Flex applications 19

• Jakarta Tomcat 4.1.29 or 5.0.18. You can download a copy of Tomcat from the Jakarta Project

website at http://jakarta.apache.org/tomcat/.

• IBM WebSphere Application Server 5. You can download a trial version from the IBM website

at www7b.software.ibm.com/wsdd/downloads/WASsupport.html#download.

• BEA WebLogic Server 7 or 8.1. You can download a trial version from the BEA website at

http://commerce.bea.com/index.jsp.

For information on installing and configuring an application server, see the server vendor’s documentation or your system administrator.

About the Flex server

To compile and run MXML and ActionScript files, you need the Flex server, which is available for Windows, Linux, and Solaris operating systems.

You can order the Developer edition of the Flex server for a nominal fee from the Macromedia website at www.macromedia.com/go/flex_trial/. The Developer edition is for noncommercial use for developing and testing Flex applications. It is not licensed for deployment. After 60 days, it will support requests from only five IP addresses (plus localhost), but you can still use it for development and testing as long as you want. The software does not expire.

For information on installing the Developer edition on the same computer as Flex Builder, see

“Install the Flex server on your computer” on page 22. For information on other possible

configurations, see the Flex installation guide on the Macromedia website at

www.macromedia.com/go/flex_install/.

Typographical conventions of this guide

The following typographical conventions are used in this guide:

• Menu items are shown in this format: menu name > menu item name. Items in submenus are

shown in this format: menu name > submenu name > menu item name.

• Code font indicates HTML tag and attribute names as well as literal text used in examples.

• Italic code font indicates replaceable items (sometimes called metasymbols) in code.

• Bold roman text indicates text for you to enter verbatim.

20 Chapter 1: Getting Started with Flex Builder

CHAPTER 2

Flex Builder Tutorials

This series of four interconnected tutorials explains how you can build a simple Macromedia Flex application using Macromedia Flex Builder. The application is part of a website for the fictitious Flex Store company. The application gives visitors the ability to view a product catalog, find out more about each product, and add products to a shopping cart. The application is a simplified version of the Flex Store application installed with the Flex server.

The tutorials focus on using the development tools in Flex Builder, not on developing Flex applications. The goal is to show you how to use Flex Builder to develop a Flex application more rapidly and with less coding.

You can complete each tutorial as a stand-alone unit or as a part of a larger four-part tutorial. You don’t have to complete all the tutorials or complete them in order, except for the first tutorial, which you must complete before you can start any of the others.

The first tutorial shows you how to set up a Flex development environment. The second shows you how to lay out a Flex user interface with Flex Builder. The third shows you how to use Flex Builder to create custom components, the building blocks of Flex applications. The fourth shows you how to visually bind components to data with Flex Builder.

This chapter includes the following tutorials:

• “Tutorial: Setting up a development environment” on page 21

• “Tutorial: Creating a layout with Flex Builder” on page 26

• “Tutorial: Building custom components with Flex Builder” on page 34

• “Tutorial: Binding components to data with Flex Builder” on page 58

Tutorial: Setting up a development environment

This tutorial shows you how to install the Flex server on your computer, copy sample files to a folder, and define a Flex Builder site. You must complete these tasks to complete the other tutorials in this chapter.

In this tutorial, you’ll accomplish the following tasks:

• “Install the Flex server on your computer” on page 22

• “Copy the tutorial folders to the Flex samples folder” on page 24

• “Define a Flex Builder site” on page 25

Install the Flex server on your computer

This part of the tutorial describes how to set up the Developer edition of Flex on the same computer as Flex Builder. To compile and run MXML and ActionScript files, you need access to a Flex server.

The setup described in this part of the tutorial is only one of many possible configurations. You can also install Flex on a remote server running a different J2EE server and access it through a network or using FTP. If you don’t select the integrated JRun4/Flex install option, make sure you deploy the samples .war file. For more information, see the Flex installation guide on the Macromedia website at www.macromedia.com/go/flex15_install/.

The Developer edition is for noncommercial use for developing and testing Flex applications. It is not licensed for deployment. After 60 days, it will support requests from only five IP addresses (plus localhost), but you can still use it for development and testing as long as you want. The software does not expire.

Copy the Windows version of the Flex installer from the Macromedia Flex CD.

In Windows, double-click the Flex installer file, flex-15-win.exe.

The install wizard appears:

Follow the onscreen instructions.

When prompted for a serial number, leave the text box blank.

You don’t need to enter a serial number for the Developer edition. The Flex server works for 60 days as a trial edition; after that, it becomes a Developer edition.

22 Chapter 2: Flex Builder Tutorials

On the Install Options dialog box, select the second option, Macromedia Flex with integrated JRun4.

The dialog box gives you another installation option. This tutorial assumes that you selected the Integrated JRun4/Macromedia Flex option.

After you finish installing Flex 1.5, install any Flex updaters available on the Macromedia website at www.macromedia.com/go/flex_updaters.

Start the server by selecting Start > All Programs > Macromedia > Macromedia Flex > Start Integrated Flex Server.

The server displays startup information.

Caution: Do not close the Start Integrated Flex Server dialog box once the server is running. Closing it shuts down the Flex server.

Tutorial: Setting up a development environment 23

For more information, see the Flex installation documentation on the Macromedia website at

www.macromedia.com/go/flex15_install/.

You can verify that the Flex server is running normally as follows:

Open the following URL in your browser:

http://localhost:8700/samples

The Flex Sample Apps page appears.

Select a sample application to run it.

If the application doesn’t run, try the following troubleshooting suggestions:

Problem Possible solution

Port conflicts If you created a new server for the Flex application, make sure the ports used by

that server don’t conflict with other servers running on your web application server.

Application server

Flash Player Make sure you’re running the latest Macromedia Flash Player. Flash Player is

Make sure the integrated JRun4/Flex server is running. In Windows, select Start > All Programs > Macromedia > Macromedia Flex > Start Integrated Flex Server.

installed when you install Flex Builder.

Copy the tutorial folders to the Flex samples folder

In this part of the tutorial, you copy the Flex Builder tutorial folders to the folder called samples on the Flex server. The samples folder is the Flex application root folder of the Flex Sample Apps application.

Caution: You must copy the tutorial folders to the folder called samples or the tutorials will not work properly.

Locate the Tutorial folder in the following folder on your hard disk.

C:\Program Files\Macromedia\Flex Builder 1.5\Tutorial\

If you didn’t install Flex Builder to the default location, locate the Tutorial folder on your hard disk.

Select the three folders (fbBindings, fbComponents, and fbLayout) in the Tutorial folder and copy them to the following Flex application root folder:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\

Note: If you installed Flex on a different computer, you must copy the files to the samples folder on the remote computer. For more information, see “Examples of site settings” on page 15.

In the Flex application root folder, locate the folder named products in the \samples\flexstore\assets\ folder and copy it to the \samples\fbBindings\assets\ folder.

The products folder contains the product images used in the tutorial. If you're working with the integrated JRun4/Flex server locally, the path of the original products folder is as follows:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\flexstore\assets\products

After copying the folder, it should also appear at the following location:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\fbBindings\assets\products

24 Chapter 2: Flex Builder Tutorials

Define a Flex Builder site

In this part of the tutorial, you define a Flex Builder site for the tutorials. A Flex Builder site lets you visually design, preview, and debug MXML and ActionScript files without leaving Flex Builder.

After you define the Flex Builder site, you can start working on the tutorials.

This section assumes you installed the Flex server on the same computer as Flex Builder using the integrated JRun/Flex install option. If you installed the Flex server on a different computer, you must use a procedure that’s different from the one below to define the site. For instructions, see

“Defining the site if the Flex server is remote” on page 14.

In Flex Builder, select Site > Manage Sit es, click the New button in the Manage Sites dialog box, and select Flex Site from the context menu.

The Flex Server Site Setup dialog box appears.

Tip: You can also open this dialog box by clicking the Flex Site link on the Start page.

In the Site Name text box, enter Flex Builder Samples.

The name identifies your site. The samples folder contains not only the Flex Builder tutorials, but other sample applications as well.

In the Local Root Folder text box, click the folder icon and select the following folder:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\

It should contain the Flex Builder tutorial folders (see “Copy the tutorial folders to the Flex

samples folder” on page 24), among other folders.

This step tells Flex Builder where your files are located on your hard disk.

In the Flex Server Root Folder text box, make sure the following path is specified:

C:\Program Files\Macromedia\Flex\jrun4\servers\default\samples\

This folder must always be a Flex application root folder on the server. You can tell if a folder is an application root folder by checking to see if it has a WEB-INF/flex folder containing a flexconfig.xml file. An application root folder always has this folder and file. For more information, see “Identifying a Flex application root folder” on page 11.

Tutorial: Setting up a development environment 25

In the URL Prefix text box, enter the following URL:

http://localhost:8700/samples/

Caution: Flex Builder may auto-populate this text box with http://localhost:8700/flex/. Make sure you change the value to http://localhost:8700/samples/.

To get the Flex server to compile files while you work, Flex Builder uploads the file to the application root folder you specified and attempts to request it using the URL prefix.

The Flex Server Site Setup dialog box should look like this:

Click OK to define the site and close the dialog box, and then click Done to close the Manage Sites dialog box.

The Flex Builder site is defined and the tutorials are set up. To start working on a tutorial, see any of the following:

• “Tutorial: Creating a layout with Flex Builder” on page 26

• “Tutorial: Building custom components with Flex Builder” on page 34

• “Tutorial: Binding components to data with Flex Builder” on page 58

Tutorial: Creating a layout with Flex Builder

This tutorial shows you how to use Flex Builder to quickly lay out a Flex user interface.

You can complete this tutorial as a stand-alone unit or as the first part of a multipart tutorial. In either case, you must complete the setup tutorial before you begin. For instructions, see “Tutorial:

Setting up a development environment” on page 21.

In this tutorial, you’ll accomplish the following tasks:

• “Review the approved user interface mock-ups” on page 27

• “Create an MXML file” on page 28

• “Import your CSS styles” on page 29

• “Position the page title” on page 30

• “Position the catalog component” on page 31

• “Position the product detail and shopping cart components” on page 32

• “Add view buttons to the product catalog” on page 33

26 Chapter 2: Flex Builder Tutorials

Review the approved user interface mock-ups

During the planning and approval stages of the project, members of your team produced final mock-ups of the user interface for the Flex Store. You will use these mock-ups to guide you when you create the MXML layout.

The final mock-ups for the Flex Store application are stored in your fbLayout folder:

/fbLayout/mockups

You can open a mock-up file in your favorite image editor from the Files panel in Flex Builder. This feature is useful if you want to quickly change or touch up a mock-up.

In Flex Builder, make sure the Flex Builder Samples site is selected in the Files panel.

If the Files panel is closed, select Window > Files to open it.

In the Files panel, locate the uiGrid.png image and double-click it.

Flex Builder opens the image in your default image editor. For more information on setting a default image editor, see “Setting external image editor preferences” in Using Dreamweaver Help.

The first mock-up file, uiGrid.png, shows the general layout of the Flex Store user interface:

Tutorial: Creating a layout with Flex Builder 27

The user will also have the option of viewing thumbnails in the product catalog on the left side of the layout. The second mock-up file, uiThumbs.png, shows this thumbnail view:

The layout contains the following custom components:

• Two interchangeable product catalog components on the left side, which give the user two

views of the catalog

• A product detail component on the upper right side

• A shopping cart component on the lower right side

Another tutorial shows you how to build these components (see “Tutorial: Building custom

components with Flex Builder” on page 34). In this tutorial you create the basic layout of the

application.

Create an MXML file

In this part of the tutorial, you take the first step in laying out the application by creating an MXML file. MXML is a XML-based language for building Flex applications. For more information, see “About MXML files” on page 146.

In Flex Builder, make sure the Flex Builder Samples site is selected in the Files panel.

Select File > New.

The New Document dialog box appears.

Select Flex Development in the left pane and MXML Application in the right pane, and then click Create.

The dialog box closes and a blank MXML file appears.

28 Chapter 2: Flex Builder Tutorials

Set the following property in the Attributes panel of the Tag inspector (Window > Tag Inspector):

■ Styles > verticalGap: 0

Note: The angle bracket means the verticalGap property is located in the Styles category of the Attributes tab. This convention is used throughout the tutorials.

Save the file in the fbLayout folder by selecting File > Save, double-clicking the fbLayout folder, and naming the file as follows:

flexstore.mxml

Import your CSS styles

In this part of the tutorial, you import CSS styles into the flexstore.mxml file. You want to import styles defined in an external CSS file to make sure your site has a consistent look and feel. CSS styles also give you more flexibility when you want to change the design of your site.

Make sure the flexstore.mxml file is open in Flex Builder.

Open the CSS Styles panel (Window > CSS Styles) and click the Attach Style Sheet button at the lower edge of the panel.

The Attach External Style Sheet dialog box appears.

In the Attach External Style Sheet dialog box, click Browse to select the external CSS style sheet called flexstore.css located in the fbLayout folder.

After you click OK twice to close the dialog boxes, the name of the external CSS style sheet appears in the CSS Styles panel. You can click the Plus (+) icon to display a tree view of all the styles in the style sheet and their properties.

Save your work.

Tutorial: Creating a layout with Flex Builder 29

Position the page title

After importing the CSS styles, the next task is to create a basic layout for the user interface. In this part of the tutorial, you position the page title (Flex Store) in the upper left corner of the layout, as indicated in the mock-up of the user interface (see “Review the approved user interface

mock-ups” on page 27).

You decide to use a VBox (for vertical box) container to position the page title at the top of the file. The rest of the user interface will be positioned below the page title.

In Design view, click the Expanded button on the Document toolbar and then click anywhere inside the Application container.

Expanded mode adds borders and padding to controls and containers in Design view to help you lay out your application. (The borders and padding appear only at design time.) You can click the Standard button at any time to get a better representation of how your project will look after it’s compiled.

In the Containers category of the Insert bar, click the VBox button.

Flex Builder inserts a VBox container in the file.

Insert the page title by clicking anywhere inside the VBox container and clicking the Label button in the Controls category of the Insert bar.

Flex Builder inserts a Label control in the file and selects it.

Modify the Label text by double-clicking the Label control to open the Quick Tag Editor, and then changing the

text property value to "Flex Store" as follows and pressing Enter.

With the Label control still selected, set the following property in the Attributes panel:

■ Common > styleName: appTitle

You can select the style from the pop-up menu that appears when you click the field for the

styleName property.

You can see the effect of applying the style in Design view.

Save your work.

30 Chapter 2: Flex Builder Tutorials

+ 128 hidden pages

Macromedia FLEX BUILDER-USING FLEX BUILDER User Manual

CONTENTS

Getting Started with Flex Builder

Exploring the authoring environment

Starting a new application in Flex Builder

Defining a Flex Builder site

Identifying a Flex application root folder

Defining a site for the Flex Sample Apps application

Defining the site if the Flex server is local

Defining the site if the Flex server is remote

Examples of site settings

Getting help in Flex Builder

Context-sensitive help

Flex Builder Help

Macromedia website resources

What you need to build Flex applications

System requirements for Flex Builder

About web servers and Flex

About J2EE application servers and Flex

About the Flex server

Typographical conventions of this guide

Flex Builder Tutorials

Tutorial: Setting up a development environment

Install the Flex server on your computer

Copy the tutorial folders to the Flex samples folder

Define a Flex Builder site

Tutorial: Creating a layout with Flex Builder

Review the approved user interface mock-ups

Create an MXML file

Import your CSS styles

Position the page title