Calling the New Function from the Flex Client

Now that we have added a new function to the server-side class, we can simply re-generate the application. This process will introspect the server-side class, and create the appropriate client-side code.

Re-generating the Application

So, go to ZoomFlex Generator option in the top menu. Select Package Compiler > gettingstarted package. Use the following details to compile:

Project Name	gettingstartedextended
Project Location	(accept default)
Template to use	(accept default)
Theme	(accept default)
Classes to compile	Select all classes
Action to take	Download project as a zip file

Save the resultant zip file to a location of your choice.

Go to Flex Builder and import the downloaded Flex project (File > Import > Flex Project > Archive > select the downloaded zip file)

At this stage, no user interface changes are visible to new project. This is because we've simply added a server-side function, and not a User Interface element like a new property.

However, you can easily confirm that the non-UI components of the project contain the new changes. For example, open if you open src > com > [yoursite] > controller > commands > CarsCommand.as. Search for the name of the function "getallcarsbyowner". You should see the logic that has been generated for the server-side function.

Understanding Data Flow in a ZoomFlex Application

Before we start customizing the application to use this newly created functionality, lets quickly go over how this will work.

The user clicks on a person in the People listing view.
The view will dispatch an event, along with the obj_uuid of the person clicked upon, that will reach the CarsCommand. The CarsCommand invokes the "getallcarsbyowner" function to handle this event.
The CarsCommand hands off the job of getting the results from the server to the CarsDelegate.
The CarsDelegate sends then invokes the getallcarsbyowner function to the server (via the built-in ZoomFlex gateway)
Once the results come back from the server, the CarsDelegate hands them back to the CarsCommand
The CarsCommand handles the results (in this case, a list of cars for a given owner) returned from the CarsDelegate and puts the results in the ModelLocator (a repository for holding data of this sort).
The variable containing the list of cars in ModelLocator is bound to the to a DataGrid component in the People listing view. As the list of cars is updated in the ModelLocator, the DataGrid in the view will automatically update itself due to Flex binding.

This is how almost all the actions are handled in a ZoomFlex application. As you might know, ZoomFlex structures the generated application in a Cairngorm Framework. Having the Cairngorm Diagram in front while you go through this would be helpful in visualizing the overall process.

Customizing Client-side Application

Armed with this knowledge and the generated application, now we customize our the generated client-side Flex code.

ZoomFlex has done the heavy-lifting in terms of creating the appropriate events, commands and delegates. We need to do the following to the generated application: a variable in the model, create a view and handle the results that come back from the server.

Adding to the ModelLocator

Add the following line of of code to the com > [yoursite] > model > ModelLocator.as. Add it in the block of variables that holds the Cars variables.

public var carsByOwner : ArrayCollection = null; // holds cars by a given owner

Adding to the View

Now we tweak the generated view for the People class. We change the com > [yoursite] > view > People > EditForm.mxml.

We will make two simple changes:

We add a new form item that will display a list of cars owned by the selected person.
We change the way form items are laid out -- from the absolute positioning of the Canvas tag, to preformatted-default positioning of the Form tag.

To accomplish this, replace the existing <mx:Canvas> tag completely with the following code. Make sure that you delete everything between the Canvas tag, including the starting and ending Canvas tags:

    <mx:Form width=" 100="" height="100%" enabled="{__model.PeopleIsSaveEnabled}" mousedown="if(! __model.PeopleIsSaveEnabled) handleAddClick();" >="">
       <mx:FormItem label="Name:">
            <mx:TextInput id = "labelForm" text = "{__model.PeopleSelectedItem.label}"/>
        </mx:FormItem>
        <mx:FormItem label="Cars owned:">
            <mx:DataGrid id = "carsowned" dataProvider = "{__model.carsByOwner}">
                <mx:columns>
                    <mx:DataGridColumn dataField="label" headerText="Cars"/>
                </mx:columns>
            </mx:DataGrid>
        </mx:FormItem>
    </mx:Form>

Notice that the DataGrid tag that we add is bound to the variable we setup in the ModelLocator.

Dispatching Event from the View

The next thing we need to do is to dispatch the event that will notify the command to retrieve cars by owners. This event needs to be dispatched when the user clicks on any of the existing list of persons in the listing.

This event will be added to com > [yoursite] > view > People > Listing.mxml.

First we import the event we need to dispatch. Add the following code after the existing "import" statements in the <mx:Script> block:

import com.[yoursite].controller.events.Cars.GetallcarsbyownerEvent;

Make sure that you replace [yoursite] with the name of your site.

Now locate the function called "onItemSelected()". This is the function that handles all actions that need to be performed when a user clicks on a person in the people listing. Add the following code inside the "if" block in the function.

dispatchEvent( new GetallcarsbyownerEvent(dgCars.selectedItem.obj_uuid));

As mentioned above, this event is dispatched each time a user clicks on a person in the listing.

So the code for the onItemSelected() function would look something like this:

    public function onItemSelected():void {

        if(dgPeople.selectedItem != null){ //only do this if an item is selected

            dispatchEvent( new PeopleEvent(PeopleEvent.EVENT_GET, dgPeople.selectedItem as PeopleVO) );

            dispatchEvent( new GetallcarsbyownerEvent(dgPeople.selectedItem.obj_uuid));

        }

    }

Customizing the Delegate to Handle Server-side Results

Once the above event is dispatched, it is intercepted by the MainController, which passes it to the CarsCommand. CarsCommand, in turn, passes the server-side process to CarsDelegate. Open com > [yoursite] > controller > delegates > CarsDelegate.as.

You'll notice that a function to make the server-side call has already been generated by the ZoomFlex generator. This function is, not surprisingly, called "getallcarsbyowner". It is the client-side representation of the server-side function.

Once the results come back from a call to this function, they are handled by another function in the Delegate called "onResults_getallcarsbyowner". Locate that function and change the function so that it looks like the code below.

    private function onResults_getallcarsbyowner(event:*):void {

        var list : ArrayCollection = new ArrayCollection();
        var vo   : CarsVO     = new CarsVO();

        // Note: We loop over the returned query and create an ArrayCollection of CarsVOs. This is not necessary, but a good practice as it "types" each object in the ArrayCollection.
        for each (var it:* in event.result) {
            vo             = copyFields2VO(new CarsVO(),it);
            list.addItem(vo);
        }

        event              = new ResultEvent(event.type,false,true,list);

        __rds.removeEventListener('getallcarsbyowner',onResults_getallcarsbyowner);

        notifyCaller(event);

    }

Once the this processing is complete, the results are passed back to the CarsCommand.

Customizing the Command to Handle Results from the Delegate

The last step is to customize the CarsCommand to handle the results returned by the delegate. In the case of this application, a function called "onResults_getallcarsbyowner" is invoked to handle the results. All that this functions needs to do in our case is simply assign the results returned from the delegate to the variable that we setup earlier in the ModelLocator. To accomplish this, simply change the code of this function to the following:

    private function onResults_getallcarsbyowner(event:*):void{

        __model.carsByOwner = event.result;

        notifyCaller(event);
    }

Now, as you know, the datagrid that populates the cars for the selected owner is bound to this variable, it will automatically change once the variable is changed by the command.

Testing the Application

Once you've made these changes and saved your files, run the application.

Go to the People tab and select a person. You should see all cars belonging to the person displayed in the view.

This concludes this tutorial that takes you through how to use the ZoomFlex Object Designer and the ZoomFlex Generator to create a Flex application, and how to customize them.

Useful Resources

The Cairngorm Diagram: A very useful process map that details how a Cairngorm application works.
Shado Object Framework: Documentation on how to work with the server-side Shado Object Framework.
Flex Documentation: Documentation for Flex from Adobe.
ColdFusion Documentation: Documentation for ColdFusion from Adobe.

Comments

There are no comments for this page as yet.

Add a comment