July 25, 2011 / Daniel Freeman

Tutorial 7: MadComponents AMF Service Test Drive for Mobile

In this final MadComponents tutorial we’re going to look at the third and final Flash Builder 4.5 tutorial (from here), and do it the MadComponents way. Adobe’s Flex Test Drive for Mobile: Build a mobile application in an hour, takes you through building an AMF web service, and then building a mobile client application that connects to that service. We’re going to build the same application using MadComponents.

AMF is a binary format used to serialise ActionScript objects. A binary AMF packet is usually significantly smaller than REST XML or SOAP packet. Hence AMF services are typically much faster.

This tutorial assumes that you have some expertise in building web services, using PHP, Coldfusion, or Java. But if you’d rather do a tutorial where the web service already exists, then have a go at building a twitter client.

We recommend that you first take a look at the first six parts of this tutorial series, which will bring you up-to-speed with using MadComponents.

Here is what our application will look like, one the right, next to the original Flash Builder 4.5 version:-

So let’s get started, and go though the steps to build our MadComponents Mobile application:-

Set Up The Web Service

1. You’ll need to set up an AMF web service. You can do this using PHP, Coldfusion, or Java. You can download the resources from here. Follow the instructions in the original Flash Builder tutorial. Just follow the section entitled “Setup for PHP”, “Setup for ColdFusion”, or “Setup for Java”, depending which server-side technology you want to use. Don’t go further than the section entitled “Step 2: Create a Flex Mobile project. We’re going to do everything else the MadComponents way. If having looked at the Flex tutorial, you want a peek at how much easier it is using MadComponents, look here.

Creating the project

Create a new MadComponents project. We’ve already learnt how to do this in previous tutorials, but I’ll copy the steps here to save you looking it up.

2. If you haven’t done so, download MadComponents. Familiarise yourself with the demos, and see what it can do.

Flash users can download the project from http://code.google.com/p/mad-components/downloads/list .

Flex (Flash Builder) users can check-out the latest .swc and MadComponents demos from the Subversion repository at: http://code.google.com/p/mad-components/source/checkout .

Please click “like” on the Google code site, if you like MadComponents.

Although the pictures below depict MadComponentsLib0_5.swc, you’ll need the latest version. Currently MadComponentsLib0_5_7.swc (or a newer version when available).

3A. If you’re using Flash. You need to find your libs folder. For Flash CS5, you’ll find this directory at the following path, from your Flash application folder:-

Adobe_Flash_CS5/Common/Configuration/ActionScript_3.0/libs

Once you’ve found this folder, put MadComponentsLib into it:-

3B. If you’re using Flash Builder (Flex), just include the .swc into the project in the usual way.

( Project -> Properties -> ActionScript Build Path -> Library Path -> Add SWC Folder… lib )

4. Create a new ActionScript application. Call it “MadTwitterTrends”. Either Adobe AIR ActionScript applications, or a browser based application.

5. For an Adobe AIR application, set your window size to 300 x 454. (not applicable to a browser application). In Flash, you’ll see this in the properties panel:-

( On a real device, it will adapt to the screen size, but in simulation – it assumes 300 x 454 pixels )

6. Now save your application. In Flash, make sure you’ve made a new folder for it.

7. In Flex, you’ll already have a top ActionScript class. In Flash you’ll need to create one. File->New->ActionScript File. Call it “MadTestDrive.as”. Save it in the same folder as MadTestDrive.fla .

8. In Flash, create a link between the timeline project, and the ActionScript file. (No need to do anything in Flex). Click on the first cell on the timeline, and in the Actions Panel, type:

new MadTestDrive(this);

Now we’re ready to write some code.

Model for AMF Service

We’re going to connect to our AMF service. The EmployeeService.getEmployeesSummary method returns an array of objects. Here is an example of an object:-

{id:7, firstname:”Elizabeth”, lastname:”Roe”, title:”Senior Experience Designer”, photofile:”eroe.jpg”}

We’re going to represented each of these objects by a row in a list, using a custom item renderer like this:-

We use a model tag to map the object properties, onto the item renderer:-

<model url=”http://localhost/MobileTestDrive/gateway.php” service=”EmployeeService.getEmployeesSummary” action=”loadAMF”>

 <firstname>label</firstname>

 <lastname>label</lastname>

 <photofile>image</photofile>

 <title/>

 <id/>

</model>

title, and id are mapped onto components of the same name. (Actually, there is no component named id, but the row data will contain this property). photofile is mapped onto image. Note that both firstname and lastname are mapped onto the same label. MadComponents will concatenate the two strings, so that “Elizabeth” and “Roe” becomes “Elizabeth Roe”.

Here is our first program with the list, model, and custom renderer:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;

	public class MadComponentsAMF0 extends Sprite {

		protected static const AMF_LIST:XML = 	<list id="list" sortBy="lastname">

			<model url="http://localhost/MobileTestDrive/gateway.php" service="EmployeeService.getEmployeesSummary" action="loadAMF">
				<firstname>label</firstname>
				<lastname>label</lastname>
				<photofile>image</photofile>
				<title/>
				<id/>
			</model>

			<horizontal>
				<imageLoader alignV="centre" id="image" base="http://localhost/TestDrive/photos/">40</imageLoader>
				<vertical>
					<label id="label"/>
					<label id="title"><font size="10" color="#999999"/></label>
				</vertical>
			</horizontal>

		</list>;

		public function MadComponentsAMF0(screen:Sprite = null) {
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, AMF_LIST);
		}
	}
}

Notice how we’ve ordered the list by lastname. sortBy=”lastname”

Searching

We can easily add a search field to this list. Within the <list> tags, put:-

<search field=”label”/>

With field=”label”, we don’t need to write any code. When the user types text into the search field, it filters the list rows by the label field.

Detail Page

When the user clicks on a list row, we want to display a detail page with more details, such as cell phone number, office phone number, email, and office.

<columns id=”detail” widths=”80,100%”>

 <imageLoader id=”photofile” base=”http://localhost/TestDrive/photos/”>80</imageLoader>

 <vertical gapV=”0″>

 <label>Title</label>

 <label id=”title”>{FONT}</label>

 <label/>

 <label>Cell Phone</label>

 <label id=”cellphone”>{FONT}</label>

 <label/>

 <label>Office Phone</label>

 <label id=”officephone”>{FONT}</label>

 <label/>

 <label>Email</label>

 <label id=”email”>{FONT}</label>

 <label/>

 <label>Office</label>

 <label id=”office”>{FONT}</label>

 <label/>

 </vertical>

</columns>

This time, we’ve utilised ids that correspond to the property names in the EmployeeService.getEmployeesByID service. (photofile, title, cellphone, officephone, email, office). So we don’t have to specify any mappings within the <model> tags. We can just write:-

<model url=”http://localhost/MobileTestDrive/gateway.php” service=”EmployeeService.getEmployeesByID”/>

Notice there’s no action attribute. We’re going to control it using actionscript.

Putting it together

We’re going to put the list and the detail page into a <navigation> container.

<navigation id=”navigator” autoTitle=”label”>

{AMF_LIST}

{DETAIL}

</navigation>

autoTitle=”label” tells the navigation container to automatically take a property called label from the list item clicked, and set the navigation container’s title to this string.

We are going to load the detail page under actionscript control. When the user clicks on a list row, we want to extract the id for that row, and pass it as a parameter to the EmployeeService.getEmployeesByID service.

protected function pageChange(event:Event):void {

   if (_navigator.pageNumber == 1) {

   _detail.data = {image:null}; //clear old image in detail page

   _detail.model.loadAMF(“”, “”, [_navigator.row.id]);

   }

   else {

   _navigator.title = “”;

   }

}

The heart of this code sample is the line:-

_detail.model.loadAMF(“”, “”, [_navigator.row.id]);

The first parameter is the URL, the second parameter is the service. But as we’ve already specified both of these in the model tag, so we just pass an empty string “”, to utilise our defaults. The third parameter is an array of parameters. _navigator.row.id is the id of the list row clicked.

Putting all the pieces together, here is the complete code:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;

	public class MadComponentsAMF extends Sprite {

		protected static const AMF_LIST:XML = 	<list id="list" sortBy="lastname">

			<model url="http://localhost/MobileTestDrive/gateway.php" service="EmployeeService.getEmployeesSummary" action="loadAMF">
				<firstname>label</firstname>
				<lastname>label</lastname>
				<photofile>image</photofile>
				<title/>
				<id/>
			</model>

			<search field="label"/>

			<horizontal>
				<imageLoader alignV="centre" id="image" base="http://localhost/TestDrive/photos/">40</imageLoader>
				<vertical>
					<label id="label"/>
					<label id="title"><font size="10" color="#999999"/></label>
				</vertical>
			</horizontal>

		</list>;

		protected static const FONT:XML = <font size="14"/>;

		protected static const DETAIL:XML =  <columns id="detail" widths="80,100%">

				<model url="http://localhost/MobileTestDrive/gateway.php" service="EmployeeService.getEmployeesByID"/>

					<imageLoader id="photofile" base="http://localhost/TestDrive/photos/">80</imageLoader>
					<vertical gapV="0">
						<label><b>Title</b></label>
						<label id="title">{FONT}</label>
						<label/>
						<label><b>Cell Phone</b></label>
						<label id="cellphone">{FONT}</label>
						<label/>
						<label><b>Office Phone</b></label>
						<label id="officephone">{FONT}</label>
						<label/>
						<label><b>Email</b></label>
						<label id="email">{FONT}</label>
						<label/>
						<label><b>Office</b></label>
						<label id="office">{FONT}</label>
						<label/>
					</vertical>
				</columns>;

		protected static const NAVIGATION:XML = <navigation id="navigator" autoTitle="label">
								{AMF_LIST}
								{DETAIL}
							</navigation>;

		protected var _detail:UIForm;
		protected var _navigator:UINavigation;

		public function MadComponentsAMF(screen:Sprite = null) {
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, NAVIGATION);

			_detail = UIForm(UI.findViewById("detail"));
			_navigator = UINavigation(UI.findViewById("navigator"));
			_navigator.addEventListener(Event.CHANGE, pageChange);
		}

		protected function pageChange(event:Event):void {
			if (_navigator.pageNumber == 1) {
				_detail.data = {image:null};
				_detail.model.loadAMF("","",[_navigator.row.id]);
			}
			else {
				_navigator.title = "";
			}
		}

	}
}

What’s next ?

That was the last in this series of tutorials. I set out to show how the could be utilised to create powerful and lightweight mobile applications – but also how MadComponents can simplify the development process – making them a viable alternative to Flash Builder. I’m bound to be blogging more about MadComponents, so watch this space, and keep the feedback and questions coming.

Extended Madness

You may have noticed ExtendedMadness on the download site. I’ll be blogging about it soon. ExtendedMadness library is an alternative to MadComponents. It does everything that MadComponents does, but has lots more components. (Take a look at the MadComponentsDesktop.as example on the code repository.) I wanted to keep the core MadComponents library light, and that’s why further components have been included in the bigger ExtendedMadness library.

Please Blog about MadComponents

Please help spread the word about MadComponents and blog or twitter about it. It would be great if you could contribute more examples and tutorials, or even just talk about MadComponents, and what it can do.