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

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.