Building the Concept2 rowing widget

The following is a brief introduction to Adobe® Flex®, the Open Source Framework for creating Rich Internet Applications (RIA).
This tutorial will show you how easy it is to create a simple dynamic widget while hopefully inspiring you to learn more about the Flex framework and Adobe® AIR™ runtime.

Requirements

Before we get started you will want to download the Java Runtime and the Flex SDK.

(if you are running Vista 64Bit you may need to configure your JAVA_HOME environement variable to point a 32Bit JVM e.g. C:\Program Files (x86)\Java\jre6)

Getting Started

Download and unzip the latest Flex SDK from http://www.adobe.com/products/flex/flexdownloads/ (it's over 100MB so might take a few minutes).

Your first step toward getting comfortable with Flex should be to build and run the component explorer, a sample application included with the SDK.

The explorer application will introduce you to the many components available with Flex and provide sample markup for quick start copy and paste.

Building the explorer is as simple as changing into the samples/explorer directory within the SDK and running build.bat (Windows) or build.sh (Linux). Depending on the speed of your machine this can take several minutes (Coffee Break)...

If everything built as expected you should now be able to open up the explorer.html in your browser and play with the many containers, controls and effects available with Flex.

Hello Rowers!

By now you should be eager to get started and what better way to provide instant gratification than a traditional Hello Rowers app.

Adobe have a great quick start guide to Flex Click Here which includes the following mxml code (slightly modified):

<?xml version="1.0" encoding="utf-8"?>
 
<mx:Application
  xmlns:mx="http://www.adobe.com/2006/mxml"
  horizontalAlign="center" verticalAlign="middle"
  width="300" height="160"
> 

  <mx:Panel
    paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10"
    title="My Application" 
  >

  <mx:Label text="Hello Rowers!" fontWeight="bold" fontSize="24"/>

  </mx:Panel>

</mx:Application>

So how do we turn this mxml document into a shiny new Flex application?

Easy - just save the code above as hellorowers.mxml and pass this file as an argument to the mxml compiler (located in the bin directory) e.g.

mxmlc hellorowers.mxml

If there was anything wrong with the code (e.g. typos) the compiler will let you know and you will have to fix them and compile again.

You should now have a shiny new hellorowers.swf ready to run....only how do you run it?

Inside the runtimes/player directory you can find a standalone Flash Player (projector) application that once installed and run will allow you to open your hellorowers.swf file and render the finished application.

How easy is that?

Cool - So how do I add images?

Embedding your image into the code above requires just a few lines of Actionscript.

<mx:Script>
  <![CDATA[
  [Embed(source="concept2.png")]
  [Bindable]
  public var Logo:Class;
  ]]>
</mx:Script>

Those lines, when inserted after the mx:Application tag, tell Flex to import the file concept2.png (Other formats supported) e.g. GIF/JPEG) and bind the image to the variable Logo. All that is needed now is to add an mx:Image tag with the source configured to use our image as follows:

<mx:Image id="Concept2Logo" source="{Logo}" maxWidth="200" />

If you have been following along with your hellorowers.mxml file, you should now have the following:

<?xml version="1.0" encoding="utf-8"?>
 
<mx:Application
  xmlns:mx="http://www.adobe.com/2006/mxml"
  horizontalAlign="center" verticalAlign="middle"
  width="300" height="180"
> 

  <mx:Script>
    <![CDATA[
    [Embed(source="concept2.png")]
    [Bindable]
    public var Logo:Class;
    ]]>
  </mx:Script>

  <mx:Panel
    paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10"
    title="My Application" 
  >

  <mx:Image id="Concept2Logo" source="{Logo}" maxWidth="200" />

  <mx:Label text="Hello Rowers!" fontWeight="bold" fontSize="24"/>

  </mx:Panel>

</mx:Application>

Notice how I change the height of the application tag to make room for the image

Try compiling that file (remembering to copy your image into the same folder as your mxml) and opening the helloworld.swf in your Flash Player.

Now what about a progress bar?

So we have an image header on this widget and some text where we can display the meters rowed. Now what about a progress bar to show how close we are to making it into the Million Meter Club. :)

Well that's as simple as adding a mx:progressBar tag to the application as follows:

<mx:ProgressBar
  id="progress"
  minimum="0"
  maximum="100"
  label="Challenge Completed 0%"
  mode="manual"
/>

Notice the mode="manual" attribute on that tag. By setting the mode property to manual we are telling Flex that we will control the progress via Actionscript, so let's add a few lines to change the progress after the application loads, we can also update the label at the same time:

private function onApplicationComplete ():void
{
  progress.setProgress(50,100);
  progress.label = "Challenge Progress: 50%";
}

You can see that by simply referring to the id you have access to all the properties of the progressbar via dot notation. If you are wondering where to find the complete list of properties / methods that each component has, just head over to the Language Reference or alternatively download the Flash Builder application where you can benefit from autocompletion!. So putting it all together we have the following:

<?xml version="1.0" encoding="utf-8"?>
 
<mx:Application
  xmlns:mx="http://www.adobe.com/2006/mxml"
  horizontalAlign="center" verticalAlign="middle"
  width="300" height="220"
  applicationComplete="onApplicationComplete()"
> 

  <mx:Script>
    <![CDATA[
    [Embed(source="concept2.png")]
    [Bindable]
    public var Logo:Class;

    private function onApplicationComplete ():void
    {
      progress.setProgress(50,100);
    }
    ]]>
  </mx:Script>

  <mx:Panel
    paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10"
    title="My Application" 
  >

  <mx:Image id="Concept2Logo" source="{Logo}" maxWidth="200" />

  <mx:Label text="Hello World!" fontWeight="bold" fontSize="24"/>

  <mx:ProgressBar
    id="progress"
    minimum="0"
    maximum="100"
    label="Challenge Completed 50%"
    mode="manual"
  />

  </mx:Panel>

</mx:Application>

So there you go, if you got this far your pretty much ready to explore on your own, and if you take a look at the Adobe Flex website you'll find a lot more tutorials to whet your appetite.

How do I get my finished app onto a webpage?

Your not going to want keep having to open up your application inside the Flash Player, so that leaves embedding into a webpage or converting your app into a standalone package that can run outside the browser using Adobe Air.

I'm not going to go over the standalone packaging here, I'll leave that for another tutorial and instead refer you to the Adobe Air website. I will however show you how easy it is to get your swf into a webpage using SWFobject.

You'll need to download the SWFObject zip file from the website http://code.google.com/p/swfobject/.

Once downloaded you need to copy the swfobject.js and expressInstall.swf files into the same folder as your hellorowers.swf. You can then create a new file called hellorower.html that contains the following code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
  <head>
    <title>HelloRower</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    <script type="text/javascript" src="swfobject.js"></script>
    <script type="text/javascript">
    swfobject.registerObject("myId", "9.0.115", "expressInstall.swf");
    </script>
  </head>
  <body>
    <div>
      <object id="myId" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" width="3000" height="220">
        <param name="movie" value="HelloRower.swf" />
        <!--[if !IE]>-->
        <object type="application/x-shockwave-flash" data="hellorowers.swf" width="300" height="220">
        <!--<![endif]-->
          <p>Alternative content</p>
        <!--[if !IE]>-->
        </object>
        <!--<![endif]-->
      </object>
    </div>
  </body>
</html>

That's it! Open the hellohower.html file in your favourite browser and let SWFObject do all the hard work for you!

What Now?

Well by now you should have the basics under your belt and I would highly recommend you spend some time at the Flex Learning Paths site where you can learn more about communicating with web services and accessing data.

The code for the widget on the Wave2 website can be found here. You'll notice I changed the background color to blend in with the site and added some Actionscript to parse a webpage for total meters rowed before updating the progressbar.

If you are looking to access data from websites other than the one hosting your Flex application, you really need to checkout the Flash Security page as you are bound to run into a security violation at some point!.