7 April 2009

The Restaurant Finder application is a demo application that shows how to use the Adobe Flex SOAP web-service support for CRUD operations in a master-detail type application. The default state shows a list of all restaurants in the database. When you click a restaurant, the details about that restaurant and summaries of reviews appear. When you select a summary, the details of the review appear. You can add reviews to the review list. You can also filter the list of restaurants by restaurant type. This application is also accessible to users with disabilities. You can use the application with the keyboard alone, and the contents can be read by a screen reader. Since this application has a fairly linear flow of control, it was well suited to change into an accessible application.

There is also a second application, Recent Reviews, that shows how to use RESTful web services in addition to SOAP-based web services. This application displays the 10 most recent restaurant reviews. From the Recent Reviews application, click the restaurant name; the Restaurant Finder application opens with the restaurant selected. A small component like this could be a useful addition to a larger site like a portal.

Experience the application

To download and view the full source, right-click the Flex application and select View Source from the context menu.

File and folder descriptions

  • RestaurantFinder.mxml: Is the main application file for the Restaurant Finder application.
  • RecentReviews.mxml: Is the main application file for the Recent Reviews application.
  • /assets/ folder: Contains images embedded at compile time and a css file used to style the application.
  • /com/ folder: Contains ActionScript and MXML classes.
  • /data/images/ folder: Contains images loaded at runtime.

Setting up the project in Flex Builder 3

  1. Click the Experience the application link above to view the application.
  2. Right-click on the application and select View Source from the context menu.
  3. Click the link to Download Source in the lower-left corner of the window. This downloads a zipped archive of the project,
  4. Import the RestaurantFinderFlex3 project into your Flex Builder workspace by selecting File > Import > Flex Project from the main menu.
  5. Make sure the "Archive file" radio button is selected and press the Browse button to launch the Open dialog box.
  6. In the Open dialog box, navigate to the file and click the Open button to select the file and dismiss the dialog box.
  7. Click the Finish button to finish importing the project into your current workspace.

    Note: Three non-default settings were used in creating the project:

    • Accessibility was enabled by selecting Project > Properties > Flex Compiler and checking Generate accessible SWF file.
    • HTML wrapper files were not generated for the project by selecting Project > Properties > Flex Compiler and unchecking Generate HTML wrapper file. When you select a restaurant in the Recent Reviews application, the Restaurant Finder application is opened in a browser window with the restaurant selected that was selected in the Recent Reviews application. To achieve this, the selected restaurant is passed as a URL variable to the Restaurant Finder application when it is opened from the Recent Reviews application. The default HTML file was altered to pass the URL variable to the SWF using flashvars.
    • Custom launch configurations were created so that the proper HTML files could be opened instead of the SWF files when you run either the RestaurantFinder.mxml or RecentReviews.mxml files which is what happens by default if you do not have Flex Builder automatically creating HTML wrapper files. These were not retained, however, when the project was exported for release and need to be recreated by you.
  8. Run the application. Note that the SWF file is opened in the default SWF viewing application for your computer.
  9. Select Run > Run > Other.
  10. In the Create, manage, and run configurations dialog box, make sure the application file is set to RestaurantFinder.mxml.
  11. Uncheck the Use defaults check box under URL or path to launch.
  12. Change the Debug, Profile, and Run URLs from RestaurantFinder.swf to RestaurantFinder.html with the same paths.
  13. Click the Apply button.
  14. Click the new launch configuration button in the upper-left corner of the dialog box.
  15. Give the new configuration the name RecentReviews.
  16. Select the RestaurantFinderFlex3 project.
  17. Select the RecentReviews.mxml application file.
  18. Uncheck the Use defaults check box under URL or path to launch.
  19. Change the Debug, Profile, and Run URLs from RecentReviews.swf to RecentReviews .html with the same paths.
  20. Click the Apply button.
  21. Click the Run button. The Recent Reviews application should open in a browser window.
  22. Click the name of one of the restaurants. The Restaurant Finder application should open in a new browser window with that restaurant selected.

Installation and deployment instructions

By default, the two applications use Adobe hosted services. The Restaurant Finder application uses hosted SOAP services at the following URLs:

Note: The hosted web services are behind a load-balancer and the different computers behind the load balancer maintain their own copies of the database. Therefore, reviews that you add in one instance of the application may not appear the next time you run the application. If this happens, you can refresh the application in your browser to try to access the correct database instance.

The hosted Restful web service used by the Recent Reviews application has the following URL:

To use a local deployment of the services instead, you need to deploy the provided Java and JSP files to your server and then edit the appropriate AS and MXML files in the application. The Java and JSP files are located in the WEB-INF folder in the RestaurantFinderFlex3 project. You can use Ant to build a WAR file that contains everything you need or build the Java classes and then copy the RecentReviews.jsp and WEB-INF folder into an existing WAR. You will need to adjust your wsdl URLs according to the WAR file's context path and your servlet container's port. The source code for the SOAP services is in the WEB-INF/src folder and all services use a local HSQL DB located in the WEB-INF/db folder.

To change the location of the SOAP web services for the Restaurant Finder application, open the /com/adobesamples/restaurant/controller/ file, replace the URL in both of the lines that contain "ws.wsdl = ", and then recompile the application.

To change the location of the REST service for the Recent Reviews application, open RecentReviews.mxml, replace the url in the HTTPService, and then recompile the RecentReviews.mxml application.

Flex framework and architecture features

  • SOAP web services: The Restaurant Finder shows how simple it is to build CRUD applications on top of SOAP web services. Serialization and deserialization of SOAP requests and responses are automatically handled by Flex (though you'll see that we do convert some objects into strongly typed classes on our own). Developers interact with SOAP services in a simple remote procedure call (RPC) manner, dealing with objects, not SOAP packets, headers, and so on.
  • RESTful web services: The Recent Reviews application shows how easy it is to use an HTTPService to get data from the server. Although you could use the data directly, this application creates a strongly typed class that provides type safety in other parts of the application.
  • View states and transitions: The ReviewThumbnail class contains summary and detail views and illustrates how you can use states in components to edit in context. It also uses transitions to control the appearance of moving from one state to another.
  • Accessibility: This demo shows how to build an application that is accessible to users with disabilities; you can use the application with the keyboard alone and the contents can be read by a screen reader. For the standard accessible framework components, communicating with the screen reader is accomplished easily by setting a tooltip. The screen reader will automatically read the tooltip when the component receives focus. For components that have to be modified to be made accessible, screen reader messages can be controlled through accessibilityProperties or by creating an accessibilityImplementation. The use of accessibilityProperties is demonstrated in ReviewThumbnail and accessibilityImplementation is used for the custom accessible Labels, Images, and Text components. For keyboard access, the tabIndex property was used to control tab order for an application with a dynamic user interface. The ReviewThumbnail component demonstrates one approach to ensuring proper tab order when states introduce additional complexity. You can use data binding to assign to the tabIndex, which simplifies the task tremendously. In addition, in order to allow users to tab through all of the components, traditionally non-focusable components had to be made focusable. The application includes an accessible version of the Label, Image and Text classes, along with an AccImpl helper class that controls screen reader interactions. The techniques used for these classes can be extended for making other accessible components.
  • Custom Repeater component: The list of reviews does not use the standard Repeater component. The standard Repeater refreshes all of the children when its dataProvider changes. This behavior had a negative performance impact for this application. Instead, the application uses a custom repeater-like class, ThumbnailRepeater, which only creates the children when the whole list of reviews changes. When you add a review, only one new child is created, instead of all the children being recreated. By not using a standard Flex component, traditional list functionality had to be implemented. This included adding keyboard navigation between rows and taking that navigation into account for proper scrolling. Scrolling was implemented by keeping track of the current pane pixel range and adjusting verticalScrollPosition when the selected item was outside the range.
  • Loose-coupling of components: The entire application maintains loose coupling of components to maximize component reuse.
  • Centralizing services: This application includes a simple ServiceLocator class, which demonstrates one technique for centralizing your remote data access. This ServiceLocator class re-uses the same service objects from multiple components without passing them around. This is only one approach to this problem; for example, with more services, a different system might be appropriate.
  • RPC Responders: The Restaurant Finder application handles service results by using the Responder approach instead of listening for events. This allows finer-grained control over each response. This approach is also useful when using centralized services so that you don't necessarily hear events for calls that weren't related to your component.