Example: Creating a basic application

You can create external ActionScript source files with an .as extension using Flash, Flex Builder, Dreamweaver, or any text editor.

ActionScript 3.0 can be used within a number of application development environments, including the Flash authoring and Flex Builder tools.

This section walks through the steps in creating and enhancing a simple ActionScript 3.0 application using the Flash authoring tool or Flex Builder. The application you'll build presents a simple pattern for using external ActionScript 3.0 class files in Flash and Flex applications. That pattern will apply to all of the other sample applications in this manual.

Subtopics

Designing your ActionScript application

You should have some idea about the application you want to build before you start building it.

The representation of your design can be as simple as the name of the application and a brief statement of its purpose, or as complicated as a set of requirements documents containing numerous Unified Modeling Language (UML) diagrams. This manual doesn't discuss the discipline of software design in detail, but it's important to keep in mind that application design is an essential step in the development of ActionScript applications.

Our first example of an ActionScript application will be a standard "Hello World" application, so its design is very simple:

The application will be called HelloWorld.
It will display a single text field containing the words "Hello World!"
In order to be easily reused, it will use a single object-oriented class, named Greeter, which can be used from within a Flash document or a Flex application.
After you create a basic version of the application, you will add new functionality to have the user enter a user name and have the application check the name against a list of known users.

With that concise definition in place, you can start building the application itself.

Creating the HelloWorld project and the Greeter class

The design statement for the Hello World application said that its code should be easy to reuse. With this goal in mind, the application uses a single object-oriented class, named Greeter, which is used from within an application that you create in Flex Builder or the Flash authoring tool.

To create the HelloWorld project and Greeter class in Flex Builder:

In Flex Builder, select File > New> Flex Project,
If the New Flex Project dialog box asks you to select a Flex Server Technology, select Basic, and then click Next.
Type HelloWorld as the Project Name, and then click Finish.
Your new project will be created and should be showing in the Navigator panel. By default the project should already contain a file named HelloWorld.mxml, and that file should be open in the Editor panel.
Now to create a custom ActionScript class file in the Flex Builder tool, select File > New > ActionScript File.
In the New ActionScript File dialog box, select HelloWorld as the parent folder, type Greeter.as the filename, and then click Finish.
A new ActionScript editing window is displayed.

Continue with adding code to the Greeter class.

adding code to the Greeter class

The Greeter class defines an object, Greeter, that you will be able to use in your HelloWorld application.

To add code to the Greeter class:

Type the following code into the new file:

package 
{
    public class Greeter 
    {
        public function sayHello():String 
        {
            var greeting:String;
            greeting = "Hello World!";
            return greeting;
        }
    }
}

The Greeter class includes a single sayHello() method, which returns a string that says "Hello World!".

Select File > Save to save this ActionScript file.

The Greeter class is now ready to be used in an application.

Creating an application that uses your ActionScript code

The Greeter class that you have built defines a self-contained set of software functions, but it does not represent a complete application. To use the class, you need to create a Flash document or Flex application.

The HelloWorld application creates an new instance of the Greeter class. Here's how to attach the Greeter class to your application.

var myGreeter:Greeter = new Greeter();
mainText.text = myGreeter.sayHello();

To create an ActionScript application using Flex Builder:

Open the HelloWorld.mxml file, and type the following code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" 
    layout="vertical"
    creationComplete = "initApp()" >
    
    <mx:Script>
        <![CDATA[
            private var myGreeter:Greeter = new Greeter();
            
            public function initApp():void 
            {
                // says hello at the start, and asks for the user's name
                mainTxt.text = myGreeter.sayHello();
            }
        ]]>
    </mx:Script>

    <mx:TextArea id = "mainTxt" width="400" />        
    
</mx:Application>

This Flex project includes three MXML tags:

An <mx:Application> tag, which defines the Application container
An <mx:Script> tag that includes some ActionScript code
An <mx:TextArea> tag, which defines a field to display text messages to the user
The code in the <mx:Script> tag defines a initApp() method that is called when the application loads. The initApp() method sets the text value of the mainTxt TextArea to the "Hello World!" string returned by the sayHello() method of the custom class Greeter, which you just wrote.
Select File > Save to save the application.

Continue with Publishing and testing your ActionScript application.

Publishing and testing your ActionScript application

Software development is an iterative process. You write some code, try to compile it, and edit the code until it compiles cleanly. You run the compiled application, test it to see if it fulfills the intended design, and if it doesn't, you edit the code again until it does. The Flash and Flex Builder development environments offer a number of ways to publish, test, and debug your applications.

Here are the basic steps for testing the HelloWorld application in each environment.

To publish and test an ActionScript application using Flex Builder:

Select Run > Run. Make sure that the Project field shows "HelloWorld" and the Application file field shows "HelloWorld.mxml".
In the Run dialog box, click Run.
The HelloWorld application starts.
- If any errors or warnings are displayed in the Output window when you test your application, fix the causes of these errors in the HelloWorld.mxml or Greeter.as files, and then try testing the application again.
- If there are no compilation errors, a browser window opens showing the Hello World application. The text "Hello World!" should be displayed.

You have just created a simple but complete object-oriented application that uses ActionScript 3.0. Continue with Enhancing the HelloWorld application.

Enhancing the HelloWorld application

To make the application a little more interesting, you'll now make it ask for and validate a user name against a predefined list of names.

First, you will update the Greeter class to add new functionality. Then you will update the application to use the new functionality.

To update the Greeter.as file:

Open the Greeter.as file.

Change the contents of the file to the following (new and changed lines are shown in boldface):

package
{
    public class Greeter
    {
        /**
         * Defines the names that should receive a proper greeting.
         */
        public static var validNames:Array = ["Sammy", "Frank", "Dean"];

        /**
         * Builds a greeting string using the given name.
         */
        public function sayHello(userName:String = ""):String 
        {
            var greeting:String;
            if (userName == "") 
            {
                greeting = "Hello. Please type your user name, and then press the Enter
                    key.";
            } 
            else if (validName(userName)) 
            {
                greeting = "Hello, " + userName + ".";
            } 
            else 
            {
                greeting = "Sorry " + userName + ", you are not on the list.";
            }
            return greeting;
        }
        
        /**
         * Checks whether a name is in the validNames list.
         */
        public static function validName(inputName:String = ""):Boolean 
        {
            if (validNames.indexOf(inputName) > -1) 
            {
                return true;
            } 
            else 
            {
                return false;
            }
        }
    }
}

The Greeter class now has a number of new features:

The validNames array lists valid user names. The array is initialized to a list of three names when the Greeter class is loaded.
The sayHello() method now accepts a user name and changes the greeting based on some conditions. If the userName is an empty string (""), the greeting property is set to prompt the user for a name. If the user name is valid, the greeting becomes "Hello, userName." Finally, if either of those two conditions are not met, the greeting variable is set to "Sorry userName, you are not on the list."
The validName() method returns true if the inputName is found in the validNames array, and false if it is not found. The statement validNames.indexOf(inputName) checks each of the strings in the validNames array against the inputName string. The Array.indexOf() method returns the index position of the first instance of an object in an array, or the value -1 if the object is not found in the array.

Next you will edit the Flash or Flex file that references this ActionScript class.

To modify the application using Flex Builder:

Open the HelloWorld.mxml file.
Next modify the <mx:TextArea> tag to indicate to the user that it is for display only, by changing the background color to a light gray and preventing the user from editing the displayed text:
```
    <mx:TextArea id = "mainTxt" width="400" backgroundColor="#DDDDDD" editable="false" />
```

Now add the following lines right after the <mx:TextArea> closing tag. These lines create a new TextInput field that lets the user enter a user name value:

    <mx:HBox width="400">    
        <mx:Label text="User Name:"/>    
        <mx:TextInput id="userNameTxt" width="100%" enter="mainTxt.text = myGreeter.sayHello(userNameTxt.text);" />
    </mx:HBox>

The enter attribute specifies that when the user presses the Enter key in the userNameTxt field, the text in the field will be passed to the Greeter.sayHello() method, and the greeting displayed in the mainTxt field will change accordingly.

The final contents of the HelloWorld.mxml file should look like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" 
    layout="vertical"
    creationComplete = "initApp()" >
    
    <mx:Script>
        <![CDATA[
            private var myGreeter:Greeter = new Greeter();
            
            public function initApp():void 
            {
                // says hello at the start, and asks for the user's name
                mainTxt.text = myGreeter.sayHello();
            }
            
        ]]>
    </mx:Script>

    <mx:TextArea id = "mainTxt" width="400" backgroundColor="#DDDDDD" editable="false" />        

    <mx:HBox width="400">    
        <mx:Label text="User Name:"/>    
        <mx:TextInput id="userNameTxt" width="100%" enter="mainTxt.text = myGreeter.sayHello(userNameTxt.text);" />
    </mx:HBox>
    
</mx:Application>

Save the edited HelloWorld.mxml file. Select File > Run to run the application.
When you run the application, you will be prompted to enter a user name. If it is valid (Sammy, Frank, or Dean), the application will display the "Hello, userName" confirmation message.