I’m going to try for once to write a tutorial which will enable you to create a useful application! To illustrate the use of an MXML project in Flex2, I will try to illustrate the installation of a Flex AgessaCalculator mini project using AS3 classes and an MXML file generated by Flex2.

We will therefore produce a tool which will particularly interest artists or authors affiliated to the Maison des Artistes or the AGESSA, which will allow us to calculate the deduction at source to be placed on invoices. For the moment, I have to calculate for each invoice all of the different values by hand. I think that this tutorial can give freelancers the basics for creating a virtual office containing all of the essential tools… Well we will maybe not go that far, the goal of this tutorial is to initiate oneself with the use of MXML in Flex :)

For those who don’t yet know what MXML is, here is a little reminder.

MXML is a language created by Adobe/Macromedia similar to XAML or XUL based on the text format XML. This language is an ‘under layer’ of AS3 used by the compiler of the SDK of Flex2 which makes it possible for users to quickly develop interactive content based on a swf animation without really worrying about the complex code necessary to set up it. It is possible in a MXML format to use style sheets, components, code in AS3 format, etc It is of course possible to use ActionScript 3 code in parallel with a MXML file.

Here a simple example of a MXML file:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2006/mxml" >
  <mx:Panel title="Test">
    <mx:Label text="Hello World !" fontSize="25" />
  </mx:Panel>
</mx:Application>

For the moment MXML mainly uses components developed by Adobe, but if you want to it is possible to create your own Framework of components (while appreciating that it is a big job!).

MXML language therefore has many tags for each component and many tools available in the MX framework of Adobe. I will not go into detail in this tutorial regarding all of the tags and components available but I assume that you can brush up on Flex2 references on this subject if necessary before moving onto the rest of this tutorial.

1 - Open Flex Builder 2 (we never know if this comment might be useful to someone!)

2 – In the Navigator panel (on your left by default in Flex Developer mode), right click and select New → Flex Project.

3 – A “New Flex Project� window will open. You can leave it on basic mode by default and click on Next.

4 – You can now name your project (for my version I am using the name AgessaCalculator) then click on Next.

5 – It is possible in this new window to add a “source path� or “library path� which can contain code coming from other frameworks. By default, if you look in the library paths you will notice that Flex by default puts numerous swc files in place to create an MXML application ( playerglobal.swc, utilities.swc, flex.swc, framework.swc, etc… ).

In this final screen, for this project, you should add the name of the directory: src into the textfield: Main source folder. The idea of doing this is to locate the classes and the mxml files in a directory at the root of the project. In doing this you will not have the impression of having loads of files at the root of your project (just trying to organise things here!).

You then just need to click on Finish to generate your Flex Project. If all went well you should have your new AgessaCalculator project in the Flex2 Navigator panel with the 3 basic folders: bin, HTML-template and src.

• bin : directory which contains the deployment of your application (compiled swf files, basic HTML pages, script .js)
• html-template : directory containing basic elements to generate the content in the bin directory at each project compilation.
• src : the directory “source codeâ€� containing your mxml files and your AS3 classes.

6 - In the src directory you can see your main file which will allow you to launch the application: AgessaCalculator.mxml. It should contain the following MXML code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
 
</mx:Application>

Note: There are 2 methods to choose another launch file for your application.

• Right click on the project name in the current Navigator panel, then choose the properties option. Then in the menu on the left you can choose the option Flex Applications.
• In the src directory in the Navigator panel right click on the file that you want to define by default by choosing the option Set as Default Application.

7 - We are now going to create the class that will give us the calculations for the deduction at source for AGESSA or MDA.

We will create a package for the project class while creating a sub directory src/net/ekameleon/util/ in the src directory. To do this you need to right click in the Flex2 Navigator in the src directory to make a New → Folder. (This must be done for each sub directory that you want to create in your project).

We’re now going to create the PrecompteCalculator.as file in the src/net/ekameleon/util directory. To do this you must right click on the util directory and choose the option New→ActionScript Class.

A New ActionScript Class panel will open. By default in the package field Flex has automatically added the correct package net.ekameleon.util. You just need to add a name to your class: PrecompteCalculator. Click Finish at the bottom of the panel.

The PrecompteCalculator.as file will appear in your project structure. Please note we have not used SuperClasses or Interfaces to define this class. By default, Flex generates a basic class with the following code:

package net.ekameleon.util
{
	public class PrecompteCalculator
	{
	}
}

We are now going to modify the code with the following:

/*
 
  The contents of this file are subject to the Mozilla Public License Version
  1.1 (the "License"); you may not use this file except in compliance with
  the License. You may obtain a copy of the License at 
 
           http://www.mozilla.org/MPL/ 
 
  Software distributed under the License is distributed on an "AS IS" basis,
  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  for the specific language governing rights and limitations under the License. 
 
  The Original Code is net.ekameleon Framework.
 
  The Initial Developer of the Original Code is
  ALCARAZ Marc (aka eKameleon)  <vegas@ekameleon.net>.
  Portions created by the Initial Developer are Copyright (C) 2004-2005
  the Initial Developer. All Rights Reserved.
 
  Contributor(s) :
 
*/
 
package net.ekameleon.util
{
 
	public class PrecompteCalculator
	{
 
		// ----o Constructor
 
		public function PrecompteCalculator( value:Number=0 )
		{
 
			this.value = isNaN(value) ? 0 : value ;
 
		}
 
		// ----o Constants
 
		static public const MIN_PERCENT:Number = 0.97 ;
 
		static public const CSG:Number = 7.5 ;
		static public const CRDS:Number = 0.5 ;
		static public const WIDOWHOOD:Number = 0.85 ;
 
		// ----o Private Properties
 
		/**
		 * Value of the value before tax.
		 */
		public var value:uint ;
 
		// -----o Public Methods
 
		/**
		 * 1% of the total price before tax.
		 */
		public function get authors():Number
		{
			return Math.round(value / 100) ;
		}
 
		/**
		 * total payments to be made to AGESSA
		 */
		public function get contributions():Number
		{
			return crds + csg + widowhood + authors ;
		}
 
		/**
		 * amount payable to C.R.D.S.
		 */
		public function get crds():Number
		{
			return Math.round(CRDS * (value * MIN_PERCENT) / 100) ;
		}
 
		/**
		 * amount payable to C.S.G.
		 */
		public function get csg():Number
		{
			return Math.round(CSG * (value * MIN_PERCENT) / 100) ;
		}
 
		/**
		 * total payable to the artist
		 */
		public function get total():Number
		{
			return value - (crds + csg + widowhood) ;
		}	
 
		/**
		 * amounts payable for illness and widowhood - 0.85% of the gross sum before tax
		 */
		public function get widowhood():Number
		{
			return Math.round(WIDOWHOOD * value / 100) ;
		}
 
		/**
		 * character string defining all of the details.
		 */
		public function toFormatString():String
		{
			var calculator:PrecompteCalculator = this ;
			var s:String = "" ;
			s += "> gross before tax : " + calculator.value + " euro\r" ;
			s += "  * illness/widowhood 0.85 % of gross before tax : " + calculator.widowhood + " euro\r" ;
			s += "  * C.S.G at 7.50 % of 97 % of gross before tax : " + calculator.csg + " euro\r" ;
			s += "  * C.R.D.S at 0.50 % of 97% of gross before tax : " + calculator.crds + " euro\r" ;
			s += "  * Contribution payable by the publisher (1% of gross before tax) : " + calculator.authors + " euro\r" ;
			s += "> Total costs : " + calculator.contributions + " euro\r" ;
			s += "> Total payable : " + calculator.total + " euro\r"  ;
			return s ;
		}
 
	}
}

Think about frequently saving your file, I generally do CTRL + S all the time in Flex2. This allows Flex to test your project to find errors.

8 – Now we must add the graphical elements to the application. To do this we need to go back to the AgessaCalculator.mxml file. You will see in the top of the mxml file that there are 2 tabs: Source and Design. We are now going to go into Design mode for the following processes. I advise you to display the Components and Flex Properties panels to start by going via the Window panel at the top of Flex2. It is in Design mode that these 2 panels show their importance.

The Design mode is a creation mode like in Dreamweaver which allows you to quickly create the visual aspects of your Flex application. You can for example slide components into the application zone and define properties for each of them (or a group) by passing by the Flex Properties panel.

For this exercise we are going to slide different components onto the scene:

• 1 component - Label
• 1 component - Button
• 1 component - TexInput
• 1 component - TextArea

It is very easy to define your visual environment with this method. It is also possible to select multiple components on the scene and to go from the Layout section in the FlexProperties panel to define the alignment of a group of components in the main scene.

You can go back to the source code of your MXML file at any time by clicking on the Source tab. This will allow you to see your modifications to the graphical interface in real time.

9 - Finalisation of the MXML document

It is very easy to put the visual part of the application in place using the Design mode but then I prefer to switch back to the Source mode to use the MXML code directly. Everything is made easier by the auto-completion facility available in Flex2.

At the end I get the following MXML code in my AgessaCalculator.mxml file:

<?xml version="1.0" encoding="utf-8"?>
 
<mx:Application 
 
	xmlns:mx="http://www.adobe.com/2006/mxml" 
	layout="absolute"
	backgroundGradientColors="[#fdefc4, #955413]"
 
>
 
	<mx:Script>
		<![CDATA[
 
			import net.ekameleon.util.PrecompteCalculator;
			import flash.ui.Keyboard ;
 
			public function calculate():void
			{
				var value:Number = Number(input.text) ;
				var calculator:PrecompteCalculator = new PrecompteCalculator(value) ;
				result.text = calculator.toFormatString()  ;
				input.text = "" ;
			}
 
			public function keyDown(event:KeyboardEvent):void
			{
				if (event.keyCode == Keyboard.ENTER)
				{
					calculate();
				}
			}
 
		]]>
	</mx:Script>
	<mx:Button 
		id = "bt"
		label="calculer" 
		click="calculate();"
		horizontalCenter="116.5"
		verticalCenter="-109"
		width="106"
		fontFamily="Arial"
		fontSize="11"
		color="#005555"
		cornerRadius="4" 
		fillColors="[#c4ba86, #808040]"
	/>
 
	<mx:TextInput 
		id = "input"
	        keyDown="keyDown(event)"
	 	horizontalCenter="-81.5"
	 	verticalCenter="-109" 
	 	width="274"
	 />
 
	<mx:TextArea 
		id = "result"
		width="397" 
		height="174" 
		editable="false"
	 	horizontalCenter="-20" 
	 	verticalCenter="-3"
	 />
 
	<mx:Label 
		text="Calcul du precompte."
		fontFamily="Arial"
		fontWeight="bold"
		fontSize="13"
		color="#804000"
		enabled="true"
		horizontalCenter="-148"
		verticalCenter="-135"
	/>
 
</mx:Application>

I use a <mx:Script> tag at the start of my MXML document which allows me to insert code directly into the MXML file via a CDATA.

I create therefore 2 functions: calculate() and keyDown(). The first allows me to display in my TextArea the result of the pre-counted calculation function with the sum in the textfield (TextInput). The second will allow me to intercept an event if the user clicks ENTER when he has the focus on the textfield.

To intercept the onclick event of the Button component we must look at the <mx:Button> tag and especially the click=�calculate();� attribute. In this attribute I directly insert the code to call the calculate() method. Writing code in a click attribute of a Button component comes down to typing code in a function called upon on each click.

Similarly in the <mx:TextInput> tag I have added the keyDown attribute which allows me to call upon the keyDown() function defined in the <mx:Script> Tag. It is worth noting that the keyword ‘event’ in this attribute corresponds to the event sent to the function keyDown(e:KeyboardEvent).

You will notice that the components possess an id attribute which allows you to locate different occurrences of the components displayed in the code.

I would advise you to take some time to consult the different attributes contained in each tag of the MXML document. Don’t forget that you can select a word in the document and then do Help → Help In Language Reference (Shift + F2) to get direct help on a tag, attribute, etc. that you don’t understand in the AS3 or MXML code.

10 - Publishing the application

We just now need to publish the project. To do this there are many solutions but I prefer a simple right click on the AgessaCalculator.mxml file then choosing “Run Application�. You can also go by the main menu at the top of Flex2 with the Run menu and the following options: Run AgessaCalculator (CTRL + F11) or Debug AgessaCalculator (F11). If you like you can use the trace() in your code to get information in Flex 2’s console panel.

I am not going to give you all of the sources of the project as I think that this tutorial is detailed enough for you to create the application without any problems. The aim of this exercise is to create the MXML project step by step and not to do a copy paste ;)

You can see that it is fairly easy to start using MXML and AS3 just by knowing the basics of ActionScript and XML syntax. In my opinion the combined use of Flex2 and the future Flash9 for the creation of animations and visual applications is going to be pretty awesome!

I remind you that you can get an alpha version of Flash9 on Adobe’s labs (update of Flash 8 for the moment) which allows you to perform the publication of swf animations in FP9.

By EKAMELEON - ALCARAZ Marc (2006). You can find this tutorial and its comments on my blog.