Guasax Flex Framework

After guasax presentation, we are going to start a series of tutorials showing different features provided by guasax when we are programming Flex/Apollo applications.

In this first tutorial, we’ll show the HelloWorld sample. Although this is a silly example we’ll be able to introduce a series of items necessaries to prepare any of our future guasax projects.
In the end of the tutorial you can find all necessaries resources to download the source code and view it online because viewSource option is enabled.

Setting up the environment

According to the programming environment, we can use both FlexBuilder 2.0.1 standalone and Eclipse WTP + Flex Builder Plugin. Personally I recommend and encourage you to use the second option. Some time ago, we published an article (in Spanish) about all you need to install it. It will be very useful for next examples and for FDS usage.

Creating the project

If you want, you can follow this tutorial downloading the source code and then importing it in your programming environment.
You can download it here..

Once the project has been integrated into Flex Builder, or when creating a new project, we have to realize three things:

1.- Put the GuasaxLibrary.swc library into the flex build path.
2.- Copy the locale directory which includes the messages file into the root project directory.
3.- Update the compilation options to read the messages file from the appropiated directory.
described also here

If we start from the above code we will have this solved, except for some absolute paths taken by FlexBuilder that can be fixed editing the project properties and updating the Flex Build path -> Library path.

Our main application file

In this example, we have the minimum number of files to carry on the hello world function.
First of all, there is the main MXML file in which we declare the necessary interface code to invoke the function from a button. From the function which manages the click event we will invoke the method through guasax. Also, in the “creationComplete” application event we will initialize the framework reading our components configuration file in the container.

Here we can see the MXML code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
	creationComplete="init()"  
	viewSourceURL="srcview/index.html">
	<mx:Script>
		<![CDATA[
			import conf.Constants;
			import es.guasax.container.GuasaxContainer;
			import es.guasax.samples.helloworld.bo.HelloWorldBO;
			import mx.controls.Alert;
 
			public function init():void{
				 var helloWorldBO : HelloWorldBO;	
                                             // deprecated
				//GuasaxContainer.getInstance().parseConfFile(xmlfile);
                                             //UPDATE - you can pass the xml configuration file directly
				GuasaxContainer.getInstance().parseConfFile("/conf/guasax-conf.xml",onLoadComplete);
			}
                                  public function onLoadComplete():void{
                                           //do something
                                  }
 
 
 
			public function sayHello():void{
				try{
					var params:Array = null;
					GuasaxContainer.getInstance().
						executeAction(Constants.SAY_HELLO_ACTION, params);
				}catch(error:Error){
					Alert.show("An error occurred");
				}
			}
		]]>
	</mx:Script>
 
           <!-- Configuration file for guasax -->
           <!-- UPDATE 0.9.3.a , you can remove this line now-->
	<!-- <mx:XML id="xmlfile" format="e4x|xml" source="/conf/guasax-conf.xml" /> -->	
 
	<mx:Panel x="179" y="44" width="340" height="200"  
		title="Hello World Guasax Sample" fontSize="10" 
		horizontalAlign="center" verticalAlign="middle">
		<mx:Button label="Say Hello! press me" click="sayHello()"/>
	</mx:Panel>
</mx:Application>

Configuring our actions in XML

Once we know what actions we want to invoke, we have to declare them grouped in a xml file. The structure of the configuration file seems like this:

1
2
3
4
5
6

<guasax version="0.9" description="Guasax Flex Framework">
	<component id="helloworld" className="es.guasax.samples.helloworld.bo.HelloWorldBO" enabled="true">
		<action id="sayHello"      method="sayHello"      roles="*">
		</action>
	</component>
</guasax>

In this example we only have a component with a single action. In the component definition we also have to provide it an unique identifier and a class qualified name which is going to implement the methods that are going to be called. Inside a component we declare the actions. In this example we have a single action with an identifier equals to “sayHello” which identifies the real method name to invoke when the action is fired. In this case the identifier and the name of the action are equals but it’s not a “must”. There are a series of actions and components attributes which we will introduce you in future examples.

Creating the business logic. The BO

As we have said above, the actions are invoked in a concrete component, represented by a class called Business Object, in which we delegate operations like treatment, access and data transformation inside our application. Exactly the same from that kind of classes, we will connect with FDS if it’s necessary. So, we have in guasax a class called ServiceLocator to help us to achieve it.

We could say that HelloWorldBO is like a POJO (Plain Old Java Object) in Java. In other words, a non intrusive class which doesn’t have to implement any interface or to extend any class, being totally decoupled from an execution environment or framework. It’s totally reusable everywhere outside guasax.

1
2
3
4
5
6
7
8
9
10
11
12
13

package es.guasax.samples.helloworld.bo
{
	import mx.controls.Alert;
	import es.guasax.view.ViewLocator;
 
	public class HelloWorldBO
	{
		public function sayHello():void{
			Alert.show("Hello World!, the guasax way :)");
 
		}
	}
}

In this class we only declare the sayHello method as you can see above. This name matches with method=”sayHello” attribute indicated in the XML configuration file.

Invoking the action

We always have to realize for any action invokation that it’s going to be through a framework which, as we will see in next examples, will provide us with more ways to invoke a method of our business logic. We have some ways to carry on an action invokation, depending on the desired behaviour during the execution.

In this example, we simply call an action, being able to pass an IN params array if necessary. When click event happens, guasax container passes the identifier (a String) of the action to be executed to executionAction method and the params array (null if no params). In this case we pass null because there are no params to pass.

If there were params it will be passed as an array in the provided order.

1
2
3
4
5
6
7
8
9

public function sayHello():void{
	try{
  	  var params:Array = null;
	  GuasaxContainer.getInstance().
		executeAction(Constants.SAY_HELLO_ACTION, params);
	}catch(error:Error){
		Alert.show("An error occurred");
	}
}

If we need to get the returned value from the executing BO method, we will always receive a ResponseActionVO object which has a getResult() method to retrieve the real object returned in the BO method. For example:

1
2
3
4
5
6
7
8
9
10

public function sayHello():void{
	try{
  	  var params:Array = null;
  var responseVO: ResponseActionVO =   GuasaxContainer.getInstance().
			executeAction(Constants.SAY_HELLO_ACTION, params);
	  var result:Object = responseVO.getResult();
	}catch(error:Error){
		Alert.show("An error occurred");
	}
}

In the method execution we only show an Alert message, but we will tipically modify our application model, call remote services,etc.

In the next example we will see

- Introduction of ModelLocator in guasax
- How to decouple view from business logic
- Introduction of ViewLocator. How to redirect to a concrete view after an action execution

Links, resources and code

- Link to the example HelloWorld online with viewSource option enabled
- Download here the ‘ready to import in Flex Builder project’ source code
- Link to googlecode, SVN, wiki, etc.
- Link to guasas blog

We hope you have found interesting. In next chapters we will dive into differents functions provided by guasax to develop your logic in Flex/Apollo projects