580 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Figure 26-7 shows the properties for Update Company button. Figure 26-7: The properties of the Update Company button. Later on, you may want to come back and set some guides on your Stage to help you position these form elements and maybe reformat text styles, but for now, push on to ActionScript. Choose File ➪ Save from the Flash menu bar, and maybe take a little break. Can’t? Too excited? Okay — onto the final piece of the Flash Remoting puzzle: ActionScript! Building the ActionScript The ActionScript that you’re going to build can be placed in one frame for your convenience, then called from any other Flash object as needed. You can place code containing individual pieces of logic within specific objects in your Flash movie if you wish (which is useful when you are working with a team of other developers who have their own pieces of code), but keeping all your code in one place is probably the best way to start learning how to program with Flash MX. Select Frame 1 of the actions layer before proceeding so that your code is easy to find, as shown in Figure 26-8. Listing 26-2 shows the complete ActionScript for this application. Enter Listing 26-2 exactly as shown in Frame 1 of the actions layer. (Most of it is case sensitive, so treat all of it that way to be safe.) Then we can discuss it in detail. 30546228 ch26.F 1/30/03 12:14 PM Page 580 581 Chapter 26 ✦ Flash Remoting Services Figure 26-8: Enter all your ActionScript in this example into Frame 1 of the actions layer. Listing 26-2: The ActionScript used by the application #include “NetDebug.as” #include “NetServices.as” #include “DataGlue.as” gatewayURL = “http://localhost/flashservices/gateway”; gatewayConnection = NetServices.createGatewayConnection(gatewayURL); companyService = gatewayConnection.getService(“com.flashremoting.Company”, this); function listCompanies_Result(companyListResult) { DataGlue.BindFormatStrings(companyToShow_cb, companyListResult, “#CompanyName#”, “#CompanyID#”); status_txt.text = “”; } function getCompany() { companyService.GetCompany({ CompanyID:companyToShow_cb.getSelectedItem().data }); } Continued 30546228 ch26.F 1/30/03 12:14 PM Page 581 582 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Listing 26-2 (continued) function getCompany_Result(companyRecord) { companyName_txt.text = companyRecord.items[0].CompanyName; address_txt.text = companyRecord.items[0].Address; city_txt.text = companyRecord.items[0].City; state_txt.text = companyRecord.items[0].State; zipCode_txt.text = companyRecord.items[0].ZipCode; } function updateCompany() { companyService.updateCompany({ CompanyID:companyToShow_cb.getSelectedItem().data, CompanyName:companyName_txt.text, Address:address_txt.text, City:city_txt.text, State:state_txt.text, ZipCode:zipCode_txt.text }); } function updateCompany_Result() { companyService.ListCompanies(); } function updateCompany_Status() { status_txt.text = “An error occurred.”; } companyService.listCompanies(); stop(); Let’s take Listing 26-2 from the top and work our way down. #include “NetDebug.as” #include “NetServices.as” #include “DataGlue.as” These three include statements bring the ActionScript code from these script files into your script, so as you test and publish your Flash movie, the code from these external scripts isn’t left behind. Notice that include statements do not end in semicolons. NetDebug.as provides a very useful Flash debugger that you should absolutely love and rely on during Flash Remoting development. More on how to use it in the section “NetConnection Debugger.” This line of code should be removed before production deployment. NetServices.as provides extended Flash Remoting functionality and ease of use. Although it is technically not needed for Flash Remoting development per se, most developers we know use its extended methods as standard operating procedure (as do we). DataGlue.as provides data-binding routines for Flash UI components, such as the Choose Company combo box that you created in the section “Create the Company combo box,” 30546228 ch26.F 1/30/03 12:14 PM Page 582 583 Chapter 26 ✦ Flash Remoting Services earlier in this chapter. Its functions can be duplicated through a lot of extensive coding, so technically it is not absolutely necessary for Flash Remoting development, but trust us — you want to use DataGlue because, with it, you can bind a RecordSet object to a form control with a single function call, as follows: gatewayURL = “http://localhost/flashservices/gateway”; gatewayConnection = NetServices.createGatewayConnection(gatewayURL); If you are using ColdFusion MX Server with IIS or another Web server, your gatewayURL assign- ment is as shown. If your ColdFusion MX Server was installed with its own standalone Web server, you may need to address Port 8500 in the Flash Remoting Gateway URL, as follows: gatewayURL = “http://localhost:8500/flashservices/gateway”; Either way, this is the virtual Web address of your Flash Remoting Gateway. The gatewayConnection assignment creates an instance of the NetConnection object through which you instantiate instances of your ColdFusion components, as follows: companyService = gatewayConnection.getService(“com.flashremoting.Company”, this); Now you can call methods of the Company component through the companyService instance, as you soon see. As you learned in the section “How Flash Remoting Works,” earlier in this chapter, callback functions are named by appending _Result to the name of the original calling function, so listCompanies_Result() is the callback function for the ListCompanies() function in the Company ColdFusion component: function listCompanies_Result(companyListResult) { DataGlue.BindFormatStrings(companyToShow_cb, companyListResult, “#CompanyName#”, “#CompanyID#”); status_txt.text = “”; } The ColdFusion query object returned from the ListCompanies() ColdFusion component function is received by the listCompanies_Result ActionScript function as an ActionScript RecordSet object named companyListResult. Then DataGlue’s BindFormatStrings() function binds the companyToShow_cb combo box to the companyListResult RecordSet object, using the CompanyName column values as the display text in the combo box, and the CompanyID column values as their corresponding data values (similar to an HTML select menu), as follows: function getCompany() { companyService.GetCompany({ CompanyID:companyToShow_cb.getSelectedItem().data }); } function getCompany_Result(companyRecord) { companyName_txt.text = companyRecord.items[0].CompanyName; address_txt.text = companyRecord.items[0].Address; city_txt.text = companyRecord.items[0].City; state_txt.text = companyRecord.items[0].State; zipCode_txt.text = companyRecord.items[0].ZipCode; } 30546228 ch26.F 1/30/03 12:14 PM Page 583 584 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration The getCompany() ActionScript function, which is called whenever the user chooses a differ- ent company in the Choose Company combo box, simply calls the GetCompany() ColdFusion component function in companyService, which is an instance of the Company ColdFusion component defined in the Flash Remoting Gateway. The argument to the GetCompany() ColdFusion function is the data value of the selected item in the companyToShow_cb (Choose Company) combo box. We are using named argument syntax here, where the name of the argument is followed by a colon and then by the value of the argument. The callback function for getCompany() — getCompany_Result() — receives the returned RecordSet object containing a single record and internally refers to it as companyRecord. By using familiar dot notation, getCompany_Result() sets the values of the form fields in the Flash movie to those returned in the companyRecord object. Notice that you are setting the .text attribute of the object only, and not the entire object itself. In a similar vein, updateCompany also uses named argument notation (our favorite method for clarity of code) to send the text attributes of the entry fields and the data attribute of the combo box (the currently selected companyID) to the UpdateCompany() ColdFusion function of the Company component. The callback function simply recalls listCompanies() to update the combo box’s contents: function updateCompany() { companyService.updateCompany({ CompanyID:companyToShow_cb.getSelectedItem().data, CompanyName:companyName_txt.text, Address:address_txt.text, City:city_txt.text, State:state_txt.text, ZipCode:zipCode_txt.text }); } function updateCompany_Result() { companyService.listCompanies(); } function updateCompany_Status() { status_txt.text = “An error occurred.”; } Here you see something new. Another automatic callback function is called if the original call- ing function throws an error. This error callback is named by appending _Status to the name of the original calling function. Everything up to this point has either been establishing a connection, instantiating an object, or declaring functions that have yet to be called. But now you actually execute some code by calling the listCompanies() function of the companyServices instance of the Company ColdFusion component and then stopping the playhead by using the stop() action, which tells the Flash movie to stop playing. If this Flash movie contained multiple frames — as most of your production Flash movies will — and you don’t tell the playhead to stop, it would keep running the entire time that your Flash movie was open: companyService.listCompanies(); stop(); Choose File ➪ Save from the Flash menu bar, and you’re done. Now to test your new baby! 30546228 ch26.F 1/30/03 12:14 PM Page 584 585 Chapter 26 ✦ Flash Remoting Services Testing the application Choose Control ➪ Test Movie from the menu bar and see what happens. Most likely, you find that you have a coding typo somewhere or maybe forgot to enter an instance name for one or more of your form objects, or did or forgot something else that prevents your Flash Remoting application from working. Don’t worry — the NetConnection Debugger comes to your rescue! Finally, a truly useful (and cool) debugger! To use it, just choose Window ➪ NetConnection Debugger from the menu bar and then Control ➪ Test Movie from the Flash menu bar, and reposition and resize the debugger window so that you don’t obscure your view of the under- lying Flash Remoting application that you’re debugging. If you see an error in the debugger right away, select it in the left list box and inspect its details on the right. Correct the problem and then try again. You may need to choose Window ➪ NetConnection Debugger again before testing the movie. After you have all your initial errors debugged, your Flash Remoting application is ready to be put through the ringer. To test the error callback function, enter a very long value into the zip code field and then click the Update Company button. You should see a red error message in the status message box that you create in the section “Create the status message box,” ear- lier in this chapter. By the way, you can restrict the number of characters that the user can enter into an input field through the Maximum Characters attribute in the input field’s Properties palette. See how everything works together? Are you getting a “feel” for the system in general. Good! Now to go further into the details and also learn what not to do. Details and Caveats We really wanted you to get your feet wet in the preceding sections of this chapter with a very simple Flash Remoting application before we dump a bunch of details on you. Learning is so much easier if you strip away all the details and focus just on the big stuff to begin with, but you need to know these important details and caveats before you start deploying Flash Remoting applications in a production environment. Publishing your Flash movie To publish your Flash movie, click an unpopulated area of the Stage and then click the Publish button in the Properties palette. A Publish Settings dialog box appears for you to specify the quality and size settings that you want to use. The defaults do well for now, so just click the dialog box’s Publish button, click its OK button, and then open the Company.html file from the directory in which you saved your Company.fla Flash file. You now see your Flash Remoting application in live action! Right-click anywhere off the Flash movie portion of the Company.html Web page, and choose View ➪ Source from your browser’s menu bar. You can copy and paste this code, an example of which is shown in Listing 26-3, into your ColdFusion templates where you want to display the Flash movie. You can also open the Company.html file in your favorite editor. 30546228 ch26.F 1/30/03 12:14 PM Page 585 586 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Listing 26-3: Flash movie embedding code <OBJECT classid=”clsid:D27CDB6E-AE6D-11cf-96B8-444553540000” codebase=”http://download.macromedia.com/pub/shockwave/cabs/flash/ swflash.cab#version=6,0,0,0” WIDTH=”360” HEIGHT=”250” id=”Company” ALIGN=””> <PARAM NAME=movie VALUE=”Company.swf”> <PARAM NAME=quality VALUE=high> <PARAM NAME=bgcolor VALUE=#FFFFFF> <EMBED src=”Company.swf” quality=high bgcolor=#FFFFFF WIDTH=”360” HEIGHT=”250” NAME=”Company” ALIGN=”” TYPE=”application/x-shockwave-flash” PLUGINSPAGE=”http://www.macromedia.com/go/getflashplayer”> </EMBED> </OBJECT> The advanced publishing options of Flash movies are beyond the scope of this book, but this shows you enough to make everything work very well. For more details, please refer to the Flash MX Bible by Robert Reinhardt and Snow Dowd (Wiley) or to your Flash documentation. Using Flash Remoting with .cfm templates In preceding sections of this chapter, you see ColdFusion components used to provide data services to the Flash Remoting Gateway, but you are not limited to components alone. You can also use plain ColdFusion templates to provide data for Flash Remoting, but the mecha- nism for returning data is necessarily different, as you have no formal “return” of data from a standard ColdFusion template. To establish a Flash Remoting Gateway connection to a ColdFusion template, simply specify the directory containing the template as the service and use the file-name root of the tem- plate (that is, without the .cfm extension) as the name of the function that you’re calling. So if you have a ColdFusion template named GetCompanyList.cfm inside webroot/com/cfms, you can call it from a Flash Remoting application as follows: cfmService = gatewayConnection.getService(“com.cfms”, this); cfmService.GetCompanyList(); 30546228 ch26.F 1/30/03 12:14 PM Page 586 587 Chapter 26 ✦ Flash Remoting Services If you want to send parameters to a ColdFusion template, just set them positionally in an ActionScript array, as follows: Flash.Params = new Array(); Flash.Params[0] = 115; Flash.Params[1] = “Razzmatazz Industries”; Flash.Params[2] = “35 Bowling Way”; Flash.Params[3] = “Atlanta”; Flash.Params is received by ColdFusion as a structure named Flash that’s containing an array rather than as a plain array. You can access the parameters from within ColdFusion by using standard dot notation, as follows: Flash.Params[1] Flash.Params[2] Flash.Params[3] Flash.Params[4] Notice that an “index shift” occurs because ActionScript arrays are zero-based (that is, they start at index 0) whereas ColdFusion arrays are one-based (that is, they start at index 1). To send data from a ColdFusion template back to the Flash Remoting Gateway, you assign the return data to the Result variable in ColdFusion MX’s new Flash scope. If you have a ColdFusion template that creates a query object named myQuery that you want to return to the Flash Remoting Gateway, for example, assign it to Flash.Result, as follows: <cfset Flash.Result = myQuery> The Flash Remoting Gateway takes whatever is set in Flash.Result and routes it to the appropriate callback method in your Flash movie, just as it would if it received data back from a ColdFusion component function. Integrating Web services with Flash Remoting To make your Flash Remoting application work from a Web service rather than a ColdFusion component, just replace the webroot subdirectory path with the full URL to the Web service’s WSDL file, as follows: wsdlURL = “http://www.mydomain.com/webservices/company.cfc?wsdl”; companyService = gatewayConnection.getService(wsdlURL, this); Now you can call the Web service’s functions by using the same syntax you’re used to, as follows: companyService.listCompanies(); You can reference any WSDL file on any platform. Where ColdFusion MX uses the URL to a CFC with a wsdl parameter tacked on, some systems have precreated WSDL files as follows: wsdlURL = “http://www.yourdomain.com/ws/companysvc.wsdl”; companyService = gatewayConnection.getService(wsdlURL, this); Regardless of the target platform or how the WSDL file is generated, as long as you can point to a valid WSDL file, the Flash Remoting Gateway can use it. 30546228 ch26.F 1/30/03 12:14 PM Page 587 588 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Creating paged data displays If your Flash query returns thousands of records from ColdFusion, you probably want to start returning the first page of records to Flash as soon as they become available rather than wait for all of them. By setting the values of Flash.Pagesize in ColdFusion and calling RecordSet. setDeliveryMode() in ActionScript, you can make Flash Remoting handle large record sets in “pages.” ColdFusion controls the initial return of data by setting the value of Flash.Pagesize to the number of records to place in each “page,” as follows: <cfset Flash.Pagesize = 10> If the query returned by the function call contains more than Flash.Pagesize number of records, the RecordSet becomes “pageable” by Flash Remoting (i.e., you can view one page of rows at a time, rather than all of them at once), and the first Flash.Pagesize number of records to be returned from the query are immediately returned to Flash Remoting while the remaining records continue to arrive in the background. After ColdFusion makes its initial return to the Flash Remoting Gateway, the Flash movie must specify how the remainder of the data retrieval is to behave, and it does so through the RecordSet function setDeliveryMode(). setDeliveryMode() has the following three settings: ✦ recordSet.setDeliveryMode(“ondemand”): The default setting instructs the Gateway to stream more records as needed by the databound form control that requests them as, for example, a list box scrolls through its records. ✦ recordSet.setDeliveryMode(“page”, pageSize, pagesToPreFetch): This setting instructs the Gateway to prefetch a number of pages of a specified size. ✦ recordSet.setDeliveryMode(“fetchall”, recordsInEachGroup): This setting downloads a specific number of records in each group rather than a number of pages of a specific size. Your Flash movie can test the current status of record retrieval through the use of the follow- ing additional RecordSet functions: ✦ recordSet.getNumberAvailable(): This function returns the number of records that have already been returned to the Flash movie. ✦ recordSet.isFullyPopulated(): This function returns true if all records have been received by the Flash movie; otherwise, it returns false. Flash.Pagesize can control data returned from both standard ColdFusion templates and ColdFusion components. Return numeric 1 or 0 rather than Boolean literal Flash Remoting does a great job of data conversion between Flash and its remote platforms, but one conversion that it doesn’t make is from ColdFusion’s boolean literals True and False to Flash’s version of true and false. For this reason, rewrite your ColdFusion functions that normally return a Boolean value to instead return a numeric 1 or 0 and your Flash Remoting applications can cast these values to their Boolean equivalents. 30546228 ch26.F 1/30/03 12:14 PM Page 588 589 Chapter 26 ✦ Flash Remoting Services Securing Flash Remoting applications To secure access to your Flash Remoting applications, use the setCredentials() function of the NetConnection object to set the username and password that are passed through the Flash Remoting Gateway to ColdFusion MX. Suppose, for example, that you modify the con- nection code from Listing 26-2 as follows: gatewayURL = “http://localhost/flashservices/gateway”; gatewayConnection = NetServices.createGatewayConnection(gatewayURL); gatewayConnection.setCredentials(“lisa@churvis.com”, “cutiepie”); companyService = gatewayConnection.getService(“com.flashremoting.Company”, this); ColdFusion creates two structure keys named cflogin.name and cflogin.password to con- tain lisa@churvis.com and cutiepie, respectively. In your ColdFusion code, you can now retrieve the user record based on cflogin.name (which contains “lisa@churvis.com”) and, if it’s found, further test the retrieved password if it matches what was passed from Flash Remoting to cflogin.password (which contains “cutiepie”). If you get a complete match, you can then log in the Flash Remoting user by using ColdFusion MX’s standard secu- rity mechanism, for example, as follows: <cflogin> <cfloginuser name=”#cflogin.name#” password=”#cflogin.password#” roles=”#ValueList(rolesQuery.RoleCode)#”> </cflogin> rolesQuery is a ColdFusion query object with a RoleCode column that contains the names of the roles in which the authenticating user was granted membership. Now if a Flash Remoting application attempts to call a component function or Web service that is secured by using the roles attribute of CFFUNCTION, the function throws an error if the Flash user is not authorized to have access, and the error callback function ( _Status) is called instead of the standard callback function ( _Result). Summary In this chapter you learned how to create a complete Flash Remoting application and how to handle various details such as role-based user authentication and authorization. If you’re not a Flash developer, now’s the time to become one. Even if you’re the typical coder-type who can’t even draw a decent rectangle, you can team up with a designer-type who can, and the two of you can make beautiful music together. For further details on coding Flash Remoting applications, download and read the PDF enti- tled “Using Flash Remoting MX with ColdFusion MX” from www.Macromedia.com. This docu- ment is an update that completely replaces Chapter 29 in your Developing ColdFusion MX Applications with CFML book, which is part of the standard ColdFusion MX documentation set. Among other things, this PDF shows additional methods for passing complex variables between ActionScript and ColdFusion. We wish that we had more space to discuss Flash Remoting applications, as they are fast, scalable, relatively easy to create, and. most of all. cool, but to do justice to a deeper discus- sion of the topic would require its own book. Luckily, you will find such a book in Complete Flash Remoting by Joey Lott (Wiley). ✦✦✦ 30546228 ch26.F 1/30/03 12:14 PM Page 589 [...]... This may be your first observation of the WEB-INF directory, which CF MX installs automatically under CFusionMX/wwwroot Even if you place your code in another webroot, perhaps under IIS, there this CFusionMXCFusionMX/wwwroot/WEB-INF is still there 60 5 335 462 28 ch28.F 60 6 1/30/03 12:14 PM Page 60 6 Part V ✦ Integrating ColdFusion MX with Other Technologies You may not have the authority to place these... development staff overall ✦ ✦ ✦ 325 462 28 PP05.F 1/30/03 12:14 PM Page 597 P Integrating ColdFusion MX with Other Technologies A R T V ✦ ✦ ✦ ✦ In This Part Chapter 28 Integrating ColdFusion MX and Java Chapter 29 Integrating COM Chapter 30 Integrating ColdFusion MX with XML and WDDX Chapter 31 Communicating via Mail, FTP, and HTTP ✦ ✦ ✦ ✦ 325 462 28 PP05.F 1/30/03 12:14 PM Page 598 335 462 28 ch28.F 1/30/03 12:14... within ColdFusion itself 60 9 335 462 28 ch28.F 61 0 1/30/03 12:14 PM Page 61 0 Part V ✦ Integrating ColdFusion MX with Other Technologies Dozens of libraries come built into Java, and each of them is documented in the Java 2 Platform API Specification, at http://java.sun.com/j2se/1.3/docs/api/index.html Because the underlying Java Virtual Machine (JVM) for the current installation of ColdFusion MX is the... browser 61 3 335 462 28 ch28.F 61 4 1/30/03 12:14 PM Page 61 4 Part V ✦ Integrating ColdFusion MX with Other Technologies Caution Take great caution in editing the various XML configuration files in CF MX Sometimes, a mistake may prevent the server from starting Save a backup of any such file before changing it so that you can easily reverse the changes if needed Also, this change may not apply in the newer ColdFusion. .. the CF MX environment You can now do that In this book, we can’t discuss the hows and whys of creating JSP pages The focus is simply on how to use them within CF MX, assuming that you already know how to create them or find them written by others But here’s a simple example that you can try yourself just to see how things work 61 1 335 462 28 ch28.F 61 2 1/30/03 12:14 PM Page 61 2 Part V ✦ Integrating ColdFusion. .. ColdFusion MX with Other Technologies A JSP template can be placed in the same directory as your ColdFusion code (in CF MX Enterprise) Save the following code in a file called simple.jsp: 0) { selectData = CF.query({datasource:”CFMXBible”, sql:”SELECT CompanyID,... of SSAS is very limited, but it’s there if you need it 595 315 462 28 ch27.F 5 96 1/30/03 12:14 PM Page 5 96 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Summary In this chapter you learned how to make Flash Remoting applications with Server-Side ActionScript, and why SSAS is most likely not the way a professional ColdFusion developer would develop Flash Remoting applications... the following: CFusionMX/wwwroot/WEB-INF/taglib61.tld CFusionMX/wwwroot/WEB-INF/lib/caltag.jar You’re almost ready to proceed, but we should add that the documentation for some JSP custom tags discuss changing a file called web.xml Such a file is in the CFusionMX/wwwroot/ WEB-INF directory, but you generally don’t need to edit it to use JSP custom tags in CF MX Restart the CF MX Server After placing... Jakarta Taglibs project (at http://jakarta.apache.org/taglibs/) Many of the tags that you find in these libraries offer redundant features that CF already has 60 7 335 462 28 ch28.F 60 8 1/30/03 12:14 PM Page 60 8 Part V ✦ Integrating ColdFusion MX with Other Technologies Examples of useful JSP custom tags Although many available JSP custom tags may seem redundant to native features in CF, such tags still . Page 5 96 Integrating ColdFusion MX with Other Technologies ✦✦✦✦ In This Part Chapter 28 Integrating ColdFusion MX and Java Chapter 29 Integrating COM Chapter 30 Integrating ColdFusion MX with. Page 585 5 86 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Listing 26- 3: Flash movie embedding code <OBJECT classid=”clsid:D27CDB6E-AE6D-11cf-96B8-444553540000” codebase=”http://download.macromedia.com/pub/shockwave/cabs/flash/ swflash.cab#version =6, 0,0,0” WIDTH=” 360 ”. { companyService.GetCompany({ CompanyID:companyToShow_cb.getSelectedItem().data }); } Continued 305 462 28 ch 26. F 1/30/03 12:14 PM Page 581 582 Part IV ✦ ColdFusion MX Components, Web Services, and Flash Integration Listing 26- 2 (continued) function getCompany_Result(companyRecord)