One of the benefits of a Flex application is that the application can smoothly transition from state to state without having to fetch a new page from the server and refresh the browser. By avoiding the constant refreshing of pages, the end-user's experience is more fluid and continuous. In addition, the load on the server is greatly reduced because it need only return the application once, rather than a new page every time the user changes views.

However one of the advantages of a browser's page-oriented model is that an application's navigational state is usually clearly coupled to a URL. Thus, when the state of an application changes, the user can usually do the following:

• Bookmark the URL to get back to that state in the application
• Email the URL to a friend
• Use the Back and Forward buttons to navigate to recently visited application states

Losing the ability to couple a browser-managed URL to a specific state of an application can be a fairly big drawback when creating applications. Deep linking adds URL-mapping or "bookmarking" capabilities to Flex applications. At the high level, deep linking lets you do the following:

• Update the URL when the application state changes. This also generates a new entry in the browser's history.
• Read in values from the URL to change the state of the application. For example, a bookmark could load the application at a particular state.
• Recognize when the URL in the browser's address bar has changed. If the user clicks the Forward or Back button, or changes the URL in the address bar, the Flex application is notified and can react to the change.

What states of your application are bookmarkable will vary by application, but possibilities include a login page, a product page, a search result page, or a drill down view into data.

Deep linking only works with certain browsers. The following browsers support deep linking:

• Microsoft Internet Explorer version 6 or later
• FireFox for Windows and Macintosh
• Safari for Macintosh

In addition to requiring these browsers, deep linking requires that the client browser also has scripting enabled. Deep linking does not work with the standalone Adobe® Flash® Player or Adobe AIR™.

When writing an application that uses deep linking, you cannot use the HistoryManager class, as described in Using the HistoryManager. The deep linking functionality automatically sets the application's historyManagementEnabled property to false.

How deep linking works

Deep linking relies on communication between the browser and the Flex application. The communication is bidirectional: if a change occurs in the application, the browser must be notified, and if a change in the browser occurs, then the application must be notified. This communication is handled by the BrowserManager class. This class uses methods in the HTML wrapper's JavaScript to handle events, update the browser's address bar, and call other methods. Another class, URLUtil, is provided to make it easier to parse the URL as you read it in your Flex application and write it back to the browser.

Deep linking relies on the JavaScript and SWF files that are used by Flex's history management feature. History management and deep linking cannot coexist in the same application. As a result, you must disable history management when using deep linking. If you do not disable history management, the BrowserManager will do it for you when you initialize this class's Singleton.

To use deep linking, you write ActionScript that sets and gets portions of the URL to determine which state the application is in. These portions are called fragments, and occur after the pound sign ("#") in the URL. In the following example, view=1 is the fragment:

http://my.domain.com#view=1

If the user navigates to a new view in your application, you update the URL and set view=2 in the URL fragment. If the user then clicks the browser's Back button, the BrowserManager is notified of the event, and gives you a chance to change the application's state in respond to the URL fragment changing back to view=1.

You typically use the methods of the URLUtil class to parse the URL. This class provides methods for detecting the server name, port number, and protocol of a URL. In addition, you can use the objectToString() method to convert an ActionScript object to a String that you then append to the end of a URL. Alternatively, you can convert any number of name/value pairs on a query string into an object by using the URLUtil class's stringToObject() method. This lets you then manipulate the fragment more easily in your application logic.

Deploying applications that use deep linking

To use deep linking, your wrapper requires the following history management files:

• history.css
• history.js
• historyFrame.html

You must include the history.js and history.css files in your wrapper. The following example imports the JS and CSS files:

<!--  BEGIN Browser History required section -->
<link rel="stylesheet" type="text/css" href="history/history.css"/>
<script src="history/history.js" language="javascript"></script>
<!--  END Browser History required section -->

You must also deploy the historyFrame.html file with your Flex application. This file must be located in the /history sub-directory; its location is relative to your deployed application SWF file's location.

For Adobe®Flex® Builder™, the history.css, history.js, and historyFrame.html files are located in the following directories:

• flex_builder_install/3.0.0/templates/client-side-detection-with-history/history
• flex_builder_install/3.0.0/templates/express-installation-with-history/history
• flex_builder_install/3.0.0/templates/no-player-detection-with-history/history

For the SDK, the files are located in the same sub-directories under the sdk_install/templates directory.

Flex Builder generates the history.css, history.js, and historyFrame.html files in your project's output directory if you enable deep linking in your project.

Enable deep linking in Flex Builder

1. Select Project > Properties.
2. Select the Flex Compiler option.
3. Select the "Enable integration with browser navigation" option.

If you use the multiple SDK feature in Flex Builder and change the SDK from 3 to 2.0.1, Flex Builder generates a different set of files for history management support. For more information, see Using multiple SDKs in Flex Builder.

About the HistoryManager

The Flex History Manager lets users navigate through a Flex application by using the web browser's back and forward navigation commands. For example, a user can navigate through several Accordion container panes in a Flex application, and then click the browser's Back button to return the application to its previous states.

You cannot use the HistoryManager and the BrowserManager in the same application because the two are incompatible. For more information about using the HistoryManager, see Using the HistoryManager.