Interacting with FLEX
Objective.
Build a quick Flex application to illustrate how to easily use Tequila as a backend for RIA's.
Application functionality:
Displays a list of recipes that can be filtered by category
Target developers.
RIA developers, Flex developers.
While this tutorial can help anyone interacting with server data, it shows mostly Flex code.
Requisites.
Install Tequila framework
Generate basic application (Follow RAD Sunrise tutorial - 5min or less to complete-)
Basic understanding of FLEX
You can download a trial of flex at (http://www.adobe.com/go/flex_trial)
** We also recommend you adding some data into categories and recipes, you can do that in the web interface made in the RAD tutorial
Introduction.
After having followed the initial tutorial and generated your application, you have all that it's required to connect your data to a Flex application, write down this URL as we will use it.
All you need in flex it's a data source based on XML, this is a format that tequila provides by default on all generated pages.
All the following steps take place in FLEX builder.
Step 1. The model
1.1 Creating an AIR Project
Let's start by creating a new AIR project (Desktop)
File > New > Flex Project
Set a project name, i.e. TequilaRIA
Set Application Type: Desktop application (runs in Adoble AIR)
1.2 Defining the data model
Open the main file TequilaRIA.mxml. We will add two HTTPService to load the data and we will define some properties on the WindowedApplication component to customize look and feel.
Don't forget to replace YourURLHere marker, for the URL where you have your Tequila application running
Code:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()" layout="absolute" backgroundColor="#ffffff" width="250" height="400" horizontalScrollPolicy="off" horizontalGap="0" verticalGap="0" borderStyle="solid"> <mx:Script> import flash.net.*; private const TEQUILA_URL:String = 'YourURLHere/ index.php?rrt=xml&task='; </mx:Script> <mx:HTTPService id="RECdata" url="{TEQUILA_URL}recipes" showBusyCursor="true" /> <mx:HTTPService id="CATdata" url="{TEQUILA_URL}categories" showBusyCursor="true" /> </mx:WindowedApplication>
What's in this code:
Most defined properties set background, layout, scrolbars, font properties, etc.
mx:Script is the place where FLEX code is added
Notice the ampersand symbol is replaced for & this is required as XML/Flex have problems with the & symbol.
We define TEQUILA_URL as a constant to be able to use it for both HTTPServices
The section of Tequila URL highlighted in green is required by Tequila to identify:
rrt=xml, defines the response to be XML
task=, defines which task of the application to execute
Variables are indicated with keys around them { }, i.e. {TEQUILA_URL}
* If you define the URL straight into url property of the HTTPService, you might have issues with the & symbol
Step 2. Creating the Renderers.
2.1 Add renderers folder
First we will create a new folder renderers under src, here we will place a component to display data.
To do this:
Right click over src > New > Folder
2.2 Add the component
Right click over renderers folder > File > New > MXML Component
We name it recipesrenderer and we will base it on Canvas with a width of 250 and a height of 90
2.3 Define the component
We will assign some properties and 3 controls, 2 text and 1 textArea, so the code ends up like.
Final Code of recipesrenderer.mxml
<?xml version="1.0" encoding="utf-8"?> <mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="250" height="90" fontSize="9" horizontalScrollPolicy="off" verticalScrollPolicy="off" backgroundColor="#ffffff" borderColor="#94BAD2" borderSides="bottom" borderStyle="solid"> <mx:Text width="240" text="{data.I_TITLE}" fontSize="14" color="#C7231B" fontWeight="bold" x="0" y="1" textAlign="left" /> <mx:TextArea width="230" text="{data.I_DESCRIPTION}" y="23" maxChars="120" wordWrap="true" editable="false" textAlign="left" borderStyle="none" verticalScrollPolicy="off" horizontalScrollPolicy="off" /> <mx:Text width="230" text="{data.T_CATEGORIES_I_NAME}" y="72" fontSize="9" color="#294673" textAlign="left"/> </mx:Canvas>
What's this code:
If you read this code, even without knowing Flex, you will notice it's only XML data, with many display properties defined, the only bits of info that deserves attention are the highlighted ones, this ones are databindings and they relate the renderer with the data returned by Tequila. These names comes from the database definition.*
* Read How to examine Tequila XML datasource, (Next step) if you are not sure where this data is defined
Step 3 - Adding controls and Component integration
In this step we will go back to TequilaRIA.mxml add a combobox for categories and a TileList for recipes, to integrate the component we made on step 2, we will add it in the TileList as the itemRenderer.
Code:
<mx:ComboBox id="categories" dataProvider="{CATdata.lastResult.r.data.categories_VO}" labelField="I_NAME" width="150" height="20" change="loadrecipes(event);" x="75" y="5" selectedIndex="0" editable="false" enabled="true" /> <mx:TileList id="RECtile" dataProvider="{RECdata.lastResult.r.data.stdClass}" width="100%" height="380" itemRenderer="renderers.recipesrenderer" alternatingItemColors="[#ffffff, #ffffff]" selectionColor="#efefef" rollOverColor="#efefef" x="0" y="30" />
What's in this code:
renderers.recipesrenderer We add our custom renderer in the itemRenderer property of the TileList control to relate them.
change="loadrecipes(event);" Defines the function to call when combobox selection changes. * We will code this function on Step 4
LabelField, The XML property we display in the combo box.
{databindings} We use them to set the dataProvider property to the correct branch of the XML tree:
CATdata. It's the name of the HTTPService that loads categories
lastResult. It's the Flex property that contains the latest loaded data
r. It's the top of the Tequila tree (Short for results)
data. Top of the data tree (Other info is returned in the tree like amount of data, pages, etc)
categories_VO. It's the node that matches 1 category.
Notice. In order to set the right path for the data provide it's quite useful to examine the data returned by Tequila.
How to examine Tequila XML datasource
In order to view the XML tree structure and the data available on each call, you can simply open the URL in your favorite browser, the whole tree will display, i.e.
yourlocalurl/index.php?task=categories&rrt=xml
yourlocalurl/index.php?task=recipes&rrt=xml
Step 4 - Application Logic with ActionScript
Finally we will code a little bit to integrate this structure that we have defined in the MXML documents. As we already added a script area we will simply add the code (yellow required and a new property to the main window to auto call a method.
Final code for TequilaRIA.mxml
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()" layout="absolute" backgroundColor="#ffffff" width="250" height="400" horizontalScrollPolicy="off" horizontalGap="0" verticalGap="0" borderStyle="solid"> <mx:Script> import flash.net.*; private const TEQUILA_URL:String = 'YourURLHere/ index.php?rrt=xml&task=';
private function init():void { RECdata.send(); CATdata.send(); } private function loadrecipes(event:Event):void { var params:Object = new Object(); params.searchby = 'I_IDCATEGORY'; params.id = event.target.selectedItem.I_IDCATEGORY; RECdata.send(params); } </mx:Script> <mx:HTTPService id="RECdata" url="{TEQUILA_URL}recipes" showBusyCursor="true" /> <mx:HTTPService id="CATdata" url="{TEQUILA_URL}categories" showBusyCursor="true" /> <mx:ComboBox id="categories" dataProvider="{CATdata.lastResult.r.data.categories_VO}" labelField="I_NAME" width="150" height="20" change="loadrecipes(event);" x="75" y="5" selectedIndex="0" editable="false" enabled="true" /> <mx:TileList id="RECtile" dataProvider="{RECdata.lastResult.r.data.stdClass}" width="100%" height="380" itemRenderer="renderers.recipesrenderer" alternatingItemColors="[#ffffff, #ffffff]" selectionColor="#efefef" rollOverColor="#efefef" x="0" y="30"/> </mx:WindowedApplication>
What's in this code:
creationComplete="init()" It's a new property of windowedApplication that runs the function init()
function init(). This function simply call the send method of both HTTPService objects.
function loadRecipes This function creates a parameter object to pass to the server to filter the data and makes a new data request
searchby. Tequila parameter to specify the field to searchby
id. Data to search for
Step 5 - Export Release Build
This is the end of the tutorial, you should have a nice recipes viewer, you can execute and debug from Flex builder or you can pack as a multiplatform .air file, Project > Export Release Build and follow the simple steps of the assistant.
Hope you enjoyed connecting your Flex application with Tequila!
Acknowledgments.
This tutorial is based on Edgar Parada tutorial on consuming Twitter data, check it out, it comes with screen captures and useful information.