Integrating Flash Coldfusion

I have been developing websites with ColdFusion for about 4 years and recently (at the time of writing, 21 days ago) looked into working with Macromedia Flash and combining the two products together. I researched whether it was possible and, if so, what was involved. All the documentation I read suggested such a project should be tried with CGI, Perl or PHP at the server end, although one or two sites suggested it should be possible with ColdFusion. I scoured the web for information and had very little success. Either people had successfully done it and didn?t tell how, or the information they gave was incorrect or just unhelpful.

I attempted to go it alone and see how far I got. I understood the basic mechanics involved and set out to work out the specifics. I decided to write a simple Flash application which would query a database on a server based on user-specified criteria and return the results to the Flash application.

The process started by learning about 'forms' in flash and moved onto passing the request to the server. This all seemed fairly straightforward and worked well the first time I tried. The problem came when I tried to get the information back from the server and into the Flash application.

During a few days when I was tearing my hair out (which is already a sparse commodity) I vowed that if I ever managed to get it working I would post the results and a brief tutorial on my site to ensure that other people didn?t hit the same problems I did. This is the result.

I have included three sets of demo files as part of this tutorial (download them all here...). The first deals with returning the data from the server and displaying one record. The second deals with returning and displaying multiple records. The third deals with checking that the server has returned the data before attempting to display it. Each demo builds progressively on the previous demo.

Each demo contains four files. These are as follows?

• flashtutx.cfm - Basic file which embeds the Flash movie
• flashtutx.swf - Flash movie which calls getresultsx.cfm and displays the results
• getresultsx.cfm - Cold Fusion file which queries the database
• flashtutx.fla - Flash source file for viewing frame actions etc.

Also included is a basic Access 97 database (flashtut.mdb) containing data for you to query.

In the .fla files we only need to concern ourselves with layer 1 as this contains all the relevant elements. Layer 2 simply contains the copyright information and the demo number.

Demo 1

Open the file 'flashtut1.fla'

This first demo consists of 13 frames. Frame one is the opening form which contains the user instructions, and text field and a button. Each text field in Flash has a variable name associated with it which contains the data held in the text field. The text field on frame 1 has a variable name of 'FindSurname' which is passed to the server when the user clicks on the 'Search' button. The first frame also has a frame action associated with it. In this case the action is 'Stop', which ensures that the movie waits on this frame until the user intervenes by pressing the 'Search' button or the 'Enter' key (see the instance properties of the search button in the flashtut1.fla file). When this happens the movie proceeds onto frame 2.

Frame 2 has a frame action associated with it called 'LoadVariables'. In the flashtut1.fla file double-click on frame 2 in the timeline and click on the 'Actions' tab. The action selected is 'Load variables into location', and the location entered is 'getresults1.cfm'. The 'Level' parameter is set to 0. This means that we want to return the results from the server into movie number 0 (Flash starts counting from 0) as we only have one movie involved in this demo. You?ll notice that the bottom parameter on the right asks us about what we want to do with the variables (in this case 'FindSurname') from the previous form and we have selected 'Send using POST'. When frame 2 is loaded the action associated with the frame sends the contents of the 'FindSurname' text field to the 'getresults1.cfm' file on the server. In turn this queries the database based on the information passed to it and returns the recordset to the Flash movie.

Frames 3 to 12 simply animate a text object which contains the words 'Loading Data from Server' and provide a short pause whilst the server talks to the Flash movie.

Frame 13 is the final frame in the movie and contains three text fields. These are named 'ID', 'Forename' and 'Surname'. These are the same names as the variables returned by the ColdFusion server when the file 'getresults1.cfm' is called. As the variable names are the same Flash automatically puts the contents of the variables into the text fields, effectively displaying the results for us.

So if we load the file and enter the name 'Jordan' and click on the 'Search' button, the final frame displays ID Num as '74', the Forename as 'Philip' and the Surname as 'Jordan' as this is the only record in the database which matches the surname 'Jordan'.

Now if we click on the Browser?s 'Refresh' button and reload the form we?ll try the search with a different name. This time enter the name 'Whitaker'. The results frame will display ID Num as '108', the Forename as 'Russell' and the Surname as 'Whitaker'. But if you look in the database you will see that there are two records which match the Surname we entered. In this demo the flash movie can only display the last record returned to it ? in this case 'Russell Whitaker'. To see the actual recordset returned from the server call the file 'getresults.cfm' in your browser with the following appended to it : ?FindSurname=Whitaker

The next demo will develop the principles used here into an application which can return and display multiple records from the database.

Demo 2

Open the file 'flashtut2.fla'

The movie used in this demo also consists of only 13 frames, but has additional elements and actions which enable the user to scroll through the recordset returned from the server.

The SQL query in the ColdFusion file getresults2.cfm is slightly different this time. Instead of asking for records where the Surname is the same as that entered by the user (as in Demo 1), it searches for all records where the Surname contains the data entered by the user. For example if I entered 'Smith' as the surname in Demo 1 the server would only return one record as there is only one person with the Surname 'Smith' in the database. However, entering 'Smith' into Demo 2 would return three records. This recordset would contain the Surnames 'Smith', 'Smithson' and 'Undersmith' as they all contain the word 'smith'.

Another subtle difference in the getresults2.cfm file from the first demo is that it loads the data into variables with different names. In demo 1 the 'Smith' example above would have resulted in 3 variables being returned. These would be Id, Forename and Surname and would contain only the data of the last record returned ? the first two records having been over-written by the next. In this demo we will be loading the data from record 1 into the variables 'Id1', 'Forename1' and 'Surname1', and the data from record 2 into 'Id2', 'Forename2' and 'Surname2' and so on. This ensures that the presentation can hold all the records returned from the server without any over-writing or variable contents. If that doesn?t make much sense at the moment don?t worry too much yet ? it should all become clear as you progress through this demo. Finally, an additional variable is returned called 'NumRecords' and contains the total number of records in the recordset.

Frame 1 still has the 'Stop' action associated to it as in demo 1, but this time it also as a 'Set Variable' action too. This sets the variable 'CurrentRecord' with an initial value of '1'. CurrentRecord is used to keep track of the record the user is viewing in the final frame.

In this demo frames 2 through 12 remain unchanged ? simply loading the data as before and playing the animation whilst the data loads.

Frame 13 is similar to that of the previous demo but now contains three additional elements and 4 frame actions. The three additional objects are a 'Next record' button to display the next record in the recordset, a 'Previous record' button and a text object which displays the number of the record we are currently viewing and the total number of records in the recordset.

The frame actions associated with Frame 13 all set variables which will be displayed on the form. Double-click on frame 13 in the timeline and click on the 'Actions' tab. You will see four 'Set Variable' actions in the list box. In demo 1 we didn?t need to tell the form to display the results on frame 1 as the variable names on the form were the same as those returned by the server (flash automatically displays variables of the same name in a text field). In this demo we need to manually set the variables as the variable names from the server and the text fields do not match. For the three data fields we need (ID, Forename and Surname) we must assign the data returned from the server.

As we are looking at the first record at this point we need to assign the results from the server (fields 'Id1', 'Forename1' and 'Surname1') into the text fields 'ID', 'Forename' and 'Surname'. This is achieved with three 'Set Variable' actions:

	Set Variable: id = id1
	Set Variable: forename = forename1
	Set Variable: surname = surname1

We also need to update the status message with the current record number (CurrentRecord, set in frame 1) and the total number of records in the recordset (numrecords, as returned from the server). We do this with another 'Set Variable' action:

	Set Variable: StatusMsg = 'Record ' & CurrentRecord & ' of ' & NumRecords

This combines the contents of the variables with the words 'Record' and 'of' to produce a status message which reads 'Record 1 of 3'.

If we were to run the movie now it would display the first record in a recordset of three. We now need to give the user the ability to scroll to the next record and previous records.

To do this the frame contains two buttons; 'Previous' and 'Next'. The buttons have very different actions assigned to them but with a subtle difference.

'Next' actions :

On (Release)
      If (currentrecord+1  <= numrecords)
            Set Variable: "currentrecord" = currentrecord+1
            Set Variable: "id" = eval("id"¤trecord)
            Set Variable: "forename" = eval("forename"¤trecord)
            Set Variable: "surname" = eval("surname"¤trecord)
            Set Variable: "StatusMsg" = "Record " & currentrecord &  " of " & numrecords
      End If
End On

'Previous' actions :

On (Release)
      If (currentrecord-1  >= 1)
            Set Variable: "currentrecord" = currentrecord-1
            Set Variable: "id" = eval("id"¤trecord)
            Set Variable: "forename" = eval("forename"¤trecord)
            Set Variable: "surname" = eval("surname"¤trecord)
            Set Variable: "StatusMsg" = "Record " & currentrecord &  " of " & numrecords
      End If
End On

The first line reads 'On (release)' and means 'when the user clicks the button and releases the mouse button'. The next line checks that there is another record to view before continuing. So if you were on the last record already and clicked on the 'Next' button, line 2 would stop the application from trying to load another record (and vice-versa for the 'Previous' button). Line 3 either increases the value of the 'CurrentRecord' variable or decreases it depending on which button you pressed.

Lines 4 through 6 are the same for each button. This is where it gets a bit complicated if you?re not used to programming, but I?ll see if I can explain. If you think back to the frame action from frame 13, we specifically set the text fields to 'Id1', 'Forename1' and 'Surname1'. In these circumstances we can?t say what record we want to look at as it depends on which buttons the user has pressed and how many times. So we need to look at the 'CurrentRecord' variable and use that in our statements.

When we updated the status message (above) we combined some text ('Record' and 'of') with the value of two variables ('numrecords' and 'CurrentRecord'). We need to do something similar here to assign the correct data to the text fields. The first statement we need to produce is :

	Set Variable: "id" = id#

(where # is the value of 'CurrentRecord')

In this case we need to use the 'Eval' function to combine the text 'id' and the value of the variable 'CurrentRecord'. We do this with the statement in line 4:

Set Variable: "id" = eval("id"¤trecord)

So, if the value of 'CurrentRecord' is 2 the resulting statement will be:

	Set Variable: "id" = id2

An English translation of the statement above would be something like:

'disregard whatever the contents of the variable Id are and replace them with the contents of the variable Id2'

So if the value of the variable 'Id' is '127', the statement would be translated as:

'set the variable Id with the value 127'

Looking at lines 5 and 6 you can see that the same thing happens but this time using the 'Forename' and 'Surname' variables. So, the value of 'CurrentRecord' is 2 and we are using the 'Smith' example from above, the results displayed in the movie would be Id = '127', Forename = 'Adrian' and Surname = 'Smithson'.

The final 'Set Variable' statement is simply a repeat of the earlier statement which updates the status message.

So, when a user clicks on the 'Next' button, the application checks that the user isn?t already looking at the last record, and then loads the data from the next record into the text field variables which are then displayed on the screen. If the user is already looking at the last record the application disregards the request.

And likewise, when a user clicks on the 'Previous' button, the application checks that the user isn?t already looking at the first record, and then loads the data from the previous record into the text field variables which are then displayed on the screen. If the user is already looking at the first record the application disregards the request.

It couldn?t be simpler :-)

Demo 3 will look at the problem which may arise when a large amount of data is returned, or you are requesting data from a slow server or over a slow link.

Demo 3

If we were accessing a large Corporate information system instead of the small Access file used in these demos, our Flash movie might behave in a strange way. It may arrive at the last frame of the movie and attempt to display the results without having any data to display. The same could happen if the server we are accessing or the network we are using is particularly slow. If the query sent to the database takes 30 seconds to run but the flash presentation arrives at the last frame in only 15 seconds, there isn?t any data to work with. So we need some way of checking that the data has loaded before trying to display it.

Open the file 'flashtut3.fla'?

The movie used in this demo has an additional two frames to the movie in the last demo and the ColdFusion file 'getresults3.cfm' returns one additional variable from the server.

As we scroll through the movie the first difference between this and the movie in demo 2 is the additional action on frame 2. Before we send the information to the server asking it to return a recordset, we set a variable called 'Done' with the value '0'. This is used later when we check if the server has returned its recordset.

The ColdFusion file 'getresults3.cfm' returns a variable called 'Done' with a value of '1' at the very end of the recordset. So we can check in our Flash application whether the recordset has finished loading before we attempt to display the results.

This movie contains two additional frames inserted at positions 13 and 14. Frame 13 now checks to see if the recordset has finished loading by check the value of the variable 'Done'. If the value is greater than or equal to 1 we can go to frame 15 and display the results. Otherwise the presentation will continue onto frame 14.

We know that if the data has loaded already that the application will skip frame 14. So we can assume that if frame 14 is ever reached we that the data isn?t ready for display yet. Double-click on frame 14 in the timeline and click on the 'Actions' tab. We have an action which says:

Go to and Play (3)

Which means that the application should return to frame 3 and continue to play. If you take a look at frame 3 you?ll see that this is directly after the frame which starts to load the data from the server, and is also the start of the 'Loading Data from Server' animation. The application continues through to frame 13 which again checks to see if the data has loaded before deciding where to go. Once again, if the data hasn?t finished loading the application returns to frame 3 again.

So effectively the user will continue to see the 'Loading Data from Server' message until the data has loaded. This is a much better solution to the problem of a slow network/server or a large among of data being transferred. Instead of the user seeing a blank form and wondering where the problem is, they will be presented with a useful message keeping them informed of the situation until the data can be displayed.

Resources

To further help in your quest to combine Flash and ColdFusion take a look at the 'DB Interaction' forum at www.were-here.com

The Were-here website is an excellent Flash resource with forums on many diverse Flash-related topics.

Epilogue

As I mentioned before I am very new to Flash. The terms I have mentioned in this tutorial might not be as clear as they could. I have written this and explained things as I understand them with my limited Flash knowledge but with considerable ColdFusion and Internet knowledge.

If you have any comments to make about this tutorial, either critical or complementary, please do so by email to flash@easyrew.com or at www.easyrew.com