About deep linking

One of the benefits of an application built with Flex is that it 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 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 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 JavaScript enabled. Deep linking does not work with the standalone Adobe® Flash® Player or Adobe AIR™.

How deep linking works

Deep linking relies on communication between the browser and the 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 BrowserManagerclass. 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 application and write it back to the browser.

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 HTML wrapper requires that the following files be deployed with your application:

  • 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 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®Flash® Builder™, the history.css, history.js, and historyFrame.html files are located in the flash_builder_install/sdks/4.6.0/templates/swfobject/history directory.

For the SDK, the files are located in the sdk_install/templates/swfobject/history directory.

Flash 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 Flash Builder

  1. Select Project > Properties.

  2. Select the Flex Compiler option.

  3. Select the "Enable integration with browser navigation" option.