Lesson 2: Getting Started

You’re ready to start your adventure of learning Adobe Flex, so the first thing to do is become familiar with the environment in which you will be developing your applications. This environment is Adobe Flash Builder, which is based on the Eclipse platform. The Eclipse platform is an open source integrated development environment (IDE) that can be extended. Flash Builder has extended and customized Eclipse for building Flex applications.

In this lesson, you’ll become familiar with Flash Builder by building the main application files of the FlexGrocer application that you’ll be working on throughout this book. While working on the FlexGrocer application, you’ll learn about the Flash Builder interface and how to create, run, and save application files. You’ll also discover some of the many features Flash Builder offers to make application development easier.

Creating a new project in Flash Builder

Getting Started with Flex Application Development

Before you can build a building, you must lay the foundation. This lesson is the foundation for further Flex development. You will finish this lesson knowing how to manipulate Flash Builder in ways that make the process of Flex development easier and faster. Along the way, you will create the main application file that defines the FlexGrocer application.

Part of the study of any new body of knowledge is learning a basic vocabulary, and in this lesson you will learn the basic vocabulary of both Flex development and Flash Builder. You’ll understand terms such as view, perspective, and editor in relationship to the Flash Builder workbench. Also, you’ll understand the terms describing the processes that transform the text you enter in Flash Builder into the type of file you can view with your browser using Flash Player.

Creating a Project and an MXML Application

In this first exercise, you will create a Flex application. To do so, you must first create a project in Flash Builder. A project is nothing more than a collection of files and folders that help you organize your work. All the files you create for the FlexGrocer application will be in this project. You’ll also see that you have two choices when working with an application file: You can work in either Source view or Design view. In most cases, the view you choose will be a personal preference, but at times some functionality will be available in only one view.

Also in this exercise, you will run the Flex application. You’ll discover how the code you write is turned into a SWF file that is viewed in a browser.

1. Start Flash Builder: On Windows choose Start > Programs > Adobe > Adobe Flash Builder 4.5; on Mac OS open the Flash Builder application from the Adobe Flash Builder 4.5 folder in your Applications directory.

   This is most likely the way you will start Flash Builder. You may have already installed Eclipse on your computer and added the Flex functionality using the plug-in configuration. In that case, you need to open Eclipse as you have before, and switch to the Flash perspective.

2. Choose File > New > Flex Project. For the Project name, enter FlexGrocer. Deselect the “Use default location” check box, and for the Folder location enter driveroot:/flex4tfs/FlexGrocer.

   ---

   Note

   Driveroot is a placeholder for the name of the root drive of the operating system you are using, either Windows or Mac. Replace driveroot with the appropriate path. Also, note that the directory name is case sensitive.

   ---

   

   The project name should reflect the files contained in the project. As you continue your work with Flash Builder, you’ll soon have many projects, and the project names will help remind you which files are in each project.

   Do not accept the default location entry. The default uses your Documents directory and places files very deep in the directory structure. For simplicity’s sake in this project, you are putting your work files right on the root drive.

   Flash Builder lets you choose whether to use the most recent compiler (the default choice) or one from a previous version, by selecting the appropriate “Flex SDK version” radio button. For this application, you should use the Flex 4.5 SDK and compiler.

3. Click Next.
4. Leave the Server technology set to None/Other and the output folder for the compiled Flex application as bin-debug. At this time, there is no need to change this default. Click Next.

   

5. Across the top of the dialog box, there are three radio buttons next to a label named Component set. Choose the “Spark only” option.

   Flash Builder 4.5 allows you to work with either an older style set of components named mx, the newer style components named spark, or a hybrid of the two. In this book, you will work with the latest components from the spark set only. The mx components are described thoroughly in a variety of materials including the “Flex 3 Training from the Source” series.

6. Ensure that FlexGrocer.mxml is set as the main application filename.

   By default, Flash Builder gives the main application file the same name as your project name. Flash Builder automatically creates the main application file for you and includes the basic structure of a Flex application file.

   

   ---

   Note

   MXML is a case-sensitive language. Be sure to follow the case of the filenames in tags shown in this book.

   ---

7. Click Finish and see the project and application file you created.

   Here you see your first Flex application. Currently the application is displayed in Source view. In later lessons, you will also look at this application in Design view.

The default application file contains some basic elements. The first line of code

<?xml version="1.0" encoding="utf-8"?>

is an XML document-type declaration. Because MXML is an XML standard language, the document declaration should be included in the code.

Starting with the second line of code,

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
   xmlns:s="library://ns.adobe.com/flex/spark"
   minWidth="955" minHeight="600">

you will see definitions for a Flex main application and their associated namespaces. A minimum height and width for the application are also defined. The <s:Application> tag represents the outside container, the holder of all the content in the Flex application. You can have only one <s:Application> tag per Flex application.

Inside the <s:Application> tag are two attribute/value pairs that refer to URLs, such as xmlns:fx="http://ns.adobe.com/mxml/2009". These declarations are XML namespaces: They say where the definitions for the classes you will use in your application are and how you refer to those classes. In Flex 4.5 applications, it is common to have the two namespaces provided, as you are likely to reference three particular libraries of classes: Flex language tags, represented by the fx namespace and Flex Spark components, represented by the s namespace.

The Flex language tags represent elements that are needed for Flex 4.5 applications, but these elements are not actually classes within the Flex 4.5 SDK. You will find the <fx:Declarations> tag one of the more frequently encountered language tags. Declarations will be explained in more detail when events are discussed. The Spark classes represent the set of components, Buttons, Checkboxes, and so on used in Flex 4.5.

In a configuration file called flex-config.xml, an association is made between these URIs and an associated manifest file. Each manifest file contains a delineation of all the legal tags that can be used with that particular prefix and of the location of the class to which each tag will refer. In a standard installation of Flash Builder on a PC, the manifest files are located in installationdirectory/Adobe/Adobe Flash Builder 4.5/sdks/4.5.0/frameworks. On a Mac, the manifest files are found at installationdirectory/Adobe Flash Builder 4.5/sdks/4.5.0/frameworks. The fx namespace is pointing to the mxml-2009-manifest.xml, the s namespace points to the spark-manifest.xml, and the mx namespace points at the mx-manifest.xml.

Part of the spark-manifest.xml file is shown here.

Finally, a minimum height and width are defined for the application. By specifying these, Flash Player will know whether the browser that the application is running in is large enough to fit the application. If the browser is not large enough, scroll bars need to be added to allow the user to access the rest of the application.

Understanding the Flash Builder Workbench

Before you do any more work on your application file, you need to become more familiar with the Flash Builder workbench, which is everything you see in Flash Builder. In this exercise you’ll learn what views, editors, and perspectives mean in the workbench.

1. Close the current editor by clicking the X on the right side of the FlexGrocer.mxml editor tab. All editors have a tab at the top left of the editor area.

   Whenever you open a file, it is opened in the workbench in what is called an editor. You just closed the editor containing the FlexGrocer.mxml file. You can have many editors open at once in the workbench, and each will contain a file with code in it.

2. Open the editor containing the FlexGrocer.mxml file from the Package Explorer by double-clicking the filename.

   You can also open the file by right-clicking the filename and choosing Open.

3. Make the editor expand in width and height by double-clicking the editor tab.

   Sometimes you’ll want to see as much of your code as possible, especially because Flash Builder does not wrap text. Simply double-clicking, the editor tab expands (maximizes) the editor in both width and height, showing as much code as possible.

4. Restore the editor to its previous size by double-clicking the tab again.

   As you see, you can easily switch between expanded and non-expanded editors.

5. Click the Design view button in the editor to view the application in Design view. Your application now looks more like it will look to an end user.

   The workbench looks radically different in Design view, which allows you to drag user interface controls into the application. You will also be able to set property values in Design view.

6. Return to Source view by clicking the Source view button in the editor.

   Most frequently, you will be using Source view in this book, but some tasks are better performed in Design view.

7. Close the Package Explorer by clicking the X on the Package Explorer tab. Just like editors, views have tabs at their top left.

   In Flash Builder, the sections displaying content are called views.

8. Reopen the Package Explorer by choosing Window > Show View > Package Explorer.

   After you close a view, you can reopen it from the Window menu. There are many views; in fact, if you choose Window > Show View > Other, you’ll see a window listing all the views.

   

9. Click the Open Perspective button just above the top right of the editor, and choose the Flash Debug perspective.

   

   A perspective is nothing more than a layout of views that you want to use repeatedly. Flash Builder comes with built-in Flash and Flash Debug perspectives. You can adjust the layout of views in Flash Builder in any way that works best for you, and save it as a perspective by choosing Window > Save Perspective As. Once it’s saved, you can switch to that perspective from the Open Perspective menu at any time.

10. Return to the Flash perspective by clicking the Flash perspective button.

    As you can see, it’s easy to switch between perspectives. Later in the lesson, you’ll use the Debug perspective and discover its many helpful options.

11. If they are not showing, turn on code line numbers by choosing Window > Preferences (Flash Builder > Preferences on Mac). In the dialog box, click the disclosure triangles to the right of General and then click Editors to expand the menus. Finally, click Text Editors and select the check box for “Show line numbers.”

    

    Line numbers are useful because Flash Builder reports errors using line numbers.

    ---

    Tip

    You can also turn on line numbers by right-clicking in the marker bar of the editor and choosing Show Line Numbers. The marker bar is the area just to the left of where the code is displayed in the editor.

    ---

    

Running Your Application

In the first exercise, you created your project and an application page. Before you had a chance to run the application, you took a tour of the Flash Builder workbench. You will now get back to your application. You will run it, add code to it, and learn the basics of file manipulation.

1. Open the Project menu. Be sure the Build Automatically option has a checkmark in front of it.

   

   When Build Automatically is selected, Flex continuously checks for saved files, compiles them upon saving, and prepares them to run. Even before you run your application, syntax errors are flagged, which does not occur if Build Automatically is not selected.

   ---

   Tip

   As your applications grow more complex, you might find that having the Build Automatically setting selected takes too much time, in which case you should deselect the setting. The build will happen only when you run your application or you specifically choose Build Project from the menu.

   ---

2. Run your application by clicking the Run button. You will not see anything in the browser window when it opens.

   

   You have now run your first Flex application, and it wasn’t that interesting. In this case, the skeleton application contained no tags to display anything in the browser. But you did see the application run, and you saw the default browser open and display the results, uninteresting as it was.

   ---

   Note

   What exactly happened when you clicked the Run button? A number of processes occurred. First, the MXML tags in the application file were translated to ActionScript. ActionScript was then used to generate a SWF file, which is the format Flash Player understands. The SWF file was then sent to Flash Player in the browser.

   ---

   

3. Close the browser and return to Flash Builder.
4. Add an <s:Label> tag by placing the cursor after the closing </fx:Declarations> tag; press Enter/Return; enter the less-than sign (<). You will see a long list of tags. Press the letter L (upper- or lowercase) and select the Label tag by highlighting it and pressing Enter or by double-clicking it.

   This is an example of code hinting, which is a very helpful feature of Flash Builder of which you should take advantage.

   

5. Press the spacebar, and you’ll see a list of options, including properties and methods, which you can use with the <s:Label> tag. Press the letter t and then the letter e; then select the text property.

   Code hinting shows only the elements that relate to the selected tag. So, seeing the text element appear in this list indicates that it is a valid attribute for this tag. Not only can you select tags via code hinting, but you can also choose attributes that belong to those tags.

   

   ---

   Note

   In these two instances of code hinting, both the desired options happen to be at the top of the list. If the options were not at the top, you would select the desired option either by pressing the Down Arrow key and then pressing Enter or by double-clicking the selection.

   ---

6. Enter My First Flex Application for the value of the text property. Be sure that the text is in the quotes supplied by code hinting.

   Given that MXML is an XML language, it is required to follow all XML rules and standards. Proper XML formatting dictates that the value of any attribute be placed in quotes.

7. End the tag with a slash (/) and a greater-than sign (>).

   Check to be sure that your code appears as follows:

   <?xml version="1.0" encoding="utf-8"?>
   <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
             xmlns:s="library://ns.adobe.com/flex/spark"
             minWidth="955" minHeight="600">
      <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
      </fx:Declarations>
      <s:Label text="My First Flex Application"/>
   </s:Application>

   ---

   Note

   The code in this example places the minWidth and minHeight attribute/value pairs of the Application tag on a separate indented line. The entire Application tag could have been on one line; whether or not to add line breaks to code is a matter of personal preference. Some developers like the look of placing each attribute/value pair on a separate indented line.

   ---

   Proper XML syntax gives you two ways to terminate a tag. You just used one of them—to place a slash at the end of the tag, which is called a self-closing tag. The other option is to use the slash in front of the tag name, which is completely typed out again, as follows:

   <s:Label text="My First Flex Application">
   </s:Label>

   You usually use the self-closing tag, unless there is a reason to place something inside a tag block. For example, if you want to place the <s:Label/> tag inside the <s:Application> tag block, you have to terminate the </s:Application> tag on a separate line.

8. Save the file and run it. The text “My First Flex Application” appears in your browser.

   Finally, you get to see something displayed in your new Flex application.

   

   The <s:Application> tag comes with a default background color of white (#FFFFFF). You will learn more about adjusting styles in Lesson 16, “Customizing a Flex Application with Styles.”

9. Change the value of the text property from “My First Flex Application” to New Text. Save the file and run it.

   The next step shows another helpful feature of Flash Builder, but to see this feature you must have at least two saved versions of the file, which is why you changed the text and saved another version of the file.

10. Right-click in the editor, and from the contextual menu choose Replace With > Local History.

    A large dialog box appears.

11. Compare the current version of your file, which is located on the left side of the dialog box, to the older version on the right. Select the first item in the list. A history of the last 50 versions of your file is kept at the top of the dialog box. Click Replace to bring back your original text, which reads “My First Flex Application”.

    You will find this feature very helpful when you want to roll back to a previous version of code.

    

    ---

    Tip

    You can alter the settings for Local History by choosing Window > Preferences. Then from the dialog box, choose General > Workspace and click Local History.

    ---

12. Purposefully introduce an error into the page by removing the ending l from Label, changing the <s:Label> tag to <s:Labe>, and save the file. This will cause an error, because the compiler can find the Label class in the s namespace, but not a Labe class.

    After you save the file, the compiler checks your code. The error is found and reported in two ways. First, a small white X in a red circle will appear next to the line of code in which the coding mistake is located. Also, a description of the error appears in the Problems view.

    ---

    Tip

    You can place the pointer over the Red circle by the line number to see the complete description. You can also double-click the error listed in the Problems view, and the pointer will then appear at the appropriate line of code in the editor.

    ---

    

13. Run the application. You’ll see the following warning, telling you there are errors in your project and prompting you to confirm that the launch should continue. In this case, click Cancel.

    

    Because of the compile-time error, Flash Builder will not be able to compile the application with the latest change. If you click Proceed in this dialog box, Flash Builder will run the last successfully compiled version of your application.

14. Correct the error, save the file, and run it to be sure that everything is again working properly. Close the file.

Exploring the Flash Builder Debugger

As you build applications, things will sometimes not work properly or will perhaps throw errors. To help you understand what is causing these problems, Flash Builder has an interactive debugger. The debugger lets you set breakpoints in the code and inspect various property and variable values at the point where the execution of the code stops. You can also use the debugger to step through the code, so you can see how those values change over time.

1. From the main menu of Flash Builder, choose File > Import > Flash Builder > Flash Builder Project. This project file contains a small application with a button, a label, and ActionScript code that will add two numbers and display the results. Flash Builder has the ability to import pre-existing projects packaged in the FXP format as a stand-alone file.
2. In the Import Flash Builder Project dialog box that opens, click the first Browse button on the right of the screen. Navigate to the flex4tfs/Lesson02/independent directory, and select the DebugTest.fxp file. Set the location for “Extract new project(s) to” as driveroot:flex4tfsDebugTest.

   

   If the DebugTest directory does not exist (and it probably doesn’t, unless you have done these steps before), it will be created for you. If it does exist, and you want to replace the previous version, be sure to select the “Overwrite existing project” radio button in the “Import method” section of the dialog box. If you are overwriting an existing version, you will be prompted to confirm that the previous version is to be replaced. At this prompt, you will need to click OK to continue.

3. Click Finish.
4. In Flash Builder, notice that a new DebugTest project has been created. Expand the src and default package nodes to find the DebugTest.mxml file. Open DebugTest.mxml by double-clicking it.

   

5. Run the application and click the Click Me button. You should see a line of text appear next to the button, reading “2 + 4 = 6”.

   

   When you clicked the button, the event handler defined on line 26 was executed, calling the button_clickHandler() method. This method defines two integer variables (numTwo and numFour) and passes them to a function that adds the integers together and then displays the results in a label. The ActionScript syntax, event handlers, and datatyping variables will all be covered in detail in the next few chapters.

6. In Source view, double-click the line number 24 to set a breakpoint on that line. You need to double-click the number itself, not merely that line of code. When the breakpoint is set, you should see a blue circle appear to the left of that line number.

   

   Flash Builder may move your break point to line 26. Flash Builder will always look for the next executable line of code. In this case, that is line 26 where the click occurs.

   When the application runs in Debug view, and a user clicks the button, the application will stop executing at the line with the breakpoint. You will be able to debug from that point in the application. You can set breakpoints at any line of executable code in an application, such as an event handler in MXML, or a line of ActionScript in the Script block.

7. Launch the application in Debug view, by clicking the button that looks like a bug (located to the right of the Run application button).

   

8. When the browser launches the application, click the button labeled Click Me. This time the application runs until it reaches the breakpoint, then control is passed from the browser to Flash Builder. If Flash Builder is in the Flash perspective, you will be asked if you want to switch to the Debug perspective. Select the Remember My Decision check box, then click Yes.

   

   As you learned earlier in this chapter, Eclipse (and therefore Flash Builder) uses perspectives to group together sets of views. By default, the Debug perspective adds four views above the code. To the left is the Debug view, which shows where the application encountered the breakpoint. This view also has buttons to continue running the application, to stop debugging, and to step into the code, step over a line in the code, or return to the place that called the current function.

   To the right of the Debug perspective are three tabbed views. The Variables view shows the current state of the variables, the Breakpoints view shows all the breakpoints, and the Expressions view shows any watch expressions you have added. You will explore these views and buttons in the next few steps.

   

9. In the Debug view, click the Step Into button, which will move control to the button_clickHandler() method.

   The Debug view is showing you that you’re looking at the button_clickHandler() method. The Variables view will still show this event, as it did initially, but three new items are visible there as well, representing the three variables defined locally to the function. Since you have not yet executed the line of code that instantiates and sets the values of those variables, they currently have a value of undefined.

   

10. Click the Step Over button and notice that control is moved to the next line of executable ActionScript. Control stops immediately before this line executes. Click Step Over again to execute the code on the line that instantiates a variable named numTwo and assigns it a value of 2.

    Now that the numTwo variable has a value, you can see the value in the Variables view.

    

11. In the Variables view, click the value numTwo, and change it from 2 to 3.

    The Variables view lets you change the values of variables and see what effect the change has on the application. Changing this value won’t change the underlying code that set the value, but it will let you see what happens if the value is different.

    

12. In the Debug view, click the Resume button to allow the application to continue executing.

    This time, the label reads “3 + 4 = 7”, as we changed the value of the numTwo variable from 2 to 3.

    

13. In the Debug view, click the Terminate button (red square) to stop this debugging session. Double-click the line number 14 to set a breakpoint there.

    You now have breakpoints set at lines 14 and 24.

    

14. Click the Breakpoints tab to see that view and notice that you now have breakpoints set on lines 14 and 24. You can turn on or off breakpoints by clicking the check boxes next to each breakpoint. At this point, we no longer want to use the breakpoint at line 24, so deselect its check box.

    Deselecting the check box leaves the breakpoint in place but instructs Flash Builder to ignore it for now. You’ll notice that the icon on that line of the code has changed from a blue circle to a white circle. If you want to completely remove a breakpoint, you can either double-click its line number again, or right-click the breakpoint in the Breakpoints view and choose Remove.

    

15. Run the application in Debug view again, and click the Click Me button when the application starts.

    Notice that this time, the execution stops at the breakpoint on line 14, and that the numTwo and numFour variables are already populated.

16. Click the Step Into button to step into the addInts() function.

    Notice that the Debug view shows a click on the button called the button_clickHandler(), which in turn has now called addInts(). Also notice that the Variables view is showing another set of variables instead of numTwo and numFour, which were variables local to the button_clickHandler() method. It is now showing value1 and value2, the arguments to the method.

17. Click the Step Over button two times.

    As it did the previous times you used Step Over, the debugger executes the next line, this time populating the sumInts variable with the value 6.

18. Click the Step Return button. Then click the Step Over button.

    Notice that control returns to the button_clickHandler() method, and that the sumInts variable is now properly populated with the value 6, as it was computed in the addInts() method.

Congratulations! You know how to use the debugger. This will be extremely useful as you work through the exercises in this book and as you develop real-world Flex applications.

There’s one more interesting feature available with breakpoints in Flash Builder: conditional breakpoints. You can enable conditional breakpoints by right-clicking a breakpoint (either next to the line numbers, or in the Breakpoints view), and choosing Breakpoint Properties. From the Breakpoint Properties view, you can enable or disable breakpoints. You can also set conditions. For example, you can set a breakpoint to fire only if a variable has a certain value, or when a potential breakpoint is encountered a certain number of times. While this feature may not be terribly useful as you first start your explorations in Flex, you’ll find it invaluable as you build more complex applications.

Getting Ready for the Next Lessons

As you go forward though the rest of the book, you’ll need certain files, such as graphics, to complete the rest of the application. In the same way you imported a project from an FXP file to learn about debugging, you’ll also import an FXP file that will be the basis for the application you work on throughout this book.

When you import a project into Flash Builder, the IDE makes a determination if you already have a project with the same unique identifier (UUID). If you do, it will allow you to overwrite the existing project with the newly imported one. If not, and you already have a project of the same name as the one you are importing, it will ask you to rename the newly imported project. To avoid any confusion, you’re going to completely delete the project you had created previously in this lesson, and then import a nearly identical project, which includes some graphics that will be used throughout the rest of the book.

1. In the Package Explorer, right-click the FlexGrocer project, and choose Delete.

   

2. A dialog box will appear asking if you want to delete only the Flash Builder project, or also the files for the project from the file system. Select the radio button to also delete contents.

   

   The project and related files will be removed from the file system.

3. From the main menu of Flash Builder, choose File > Import > Flash Builder Project.
4. In the Import Flash Builder Project dialog box, click the first Browse button on the right of the screen. Navigate to flex4tfs/Lesson02/complete and select the FlexGrocer.fxp file. Set your project directory as the location for “Extract new project to”.

   

5. Click Finish.

You are now ready to continue through the rest of the book. If you care to verify that the project imported properly, look in the Project Explorer and confirm that there is now an assets directory in your project.

What You Have Learned

In this lesson, you have:

• Created a project to organize your application files (pages 18–24)

• Toured the pieces of the Flash Builder workbench (views, editors, and perspectives) used to create application files (pages 24–28)

• Run and modified application files while using code hinting and local history to produce the code for those files (pages 28–33)

• Learned about debugging an application with the Flash Builder debugger (pages 34–41)

• Prepared for the next lessons (pages 41–43)