Introducing History Management

Using history management, the user can navigate through an application using the browser's back and forward buttons. For example, a user can click a tab in a TabNavigator or Accordion container and then move to the previous tab by clicking the back button in the browser.

Flex automatically supports history management for any navigator container without using any additional MXML or ActionScript tags. It is enabled by default for the Accordion and TabNavigator containers. If you want to turn history management off for these containers you simply specify the attribute historyManagementEnabled and set it to false, as follows:

<mx:TabNavigator historyManagementEnabled="false"> 

History management is disabled by default for the ViewStack container. You can turn history management on for the ViewStack container by specifying historyManagementEnabled and setting that attribute to true as follows:

<mx:ViewStack historyManagementEnabled="true"> 

When history management is turned on, as the user moves from state to state within the application, each navigation state is saved. When the browser's back or forward button is selected, the History Manager will load and display the next navigation state that was saved previously. Only the state of the actual navigator container is saved; if the navigator has any children, the states of these components are not saved, unless history management is enabled for that container.

History management actually saves each state of the application by using the Adobe Flash Player navigateToURL() function. This function loads an invisible HTML frame into the current browser window. All the states of the Flex application are encoded into the URL parameters for the invisible HTML frame. A SWF file called history.swf, which is located in the invisible frame, decodes the query parameters and sends the navigation state information back to the HistoryManager class in Flexwhere the saved data is displayed.

You can add history management to any custom component in which it is appropriate. For example, in the FlexGrocer application, you will add history management to the CategoryView component so the user can use the back and forward buttons in the browser to navigate between different food categories, as shown here:

There are six steps to implementing history management with a component that does not implement it by default:

1.	Specify that your component will implement the IHistoryManagerClient interface.
2.	Register the component with the HistoryManager class in Flex.
3.	Implement the loadState() method in the custom component.
4.	Implement the saveState() method in the custom component.
5.	Implement the toString() method in the custom component.
6.	Call the static methods of the HistoryManager class in Flex.

To implement the IHistoryManagerClient interface on a custom component, you add an implements property to the root node of your component and specify the interface name, in this case mx.managers.IHistoryManagerClient. Specifying that a component implements a specific interface is like making a contract with the compiler. You are guaranteeing that your custom component will implement every method required by the interface, in this case loadState(), saveState() and toString(). This contract tells the HistoryManager that it is safe to work with the component as the proper functionality is guaranteed to be in place.

To register a component with the HistoryManager class, you call the static register() method of the HistoryManager class and pass a reference to the component instance. This tells the HistoryManager that your component needs to know when the user navigates using the forward or back buttons on the browser. To fulfill your contract with the HistoryManager your component must implement three methods of the mx.managers.IHistoryManagerClient interface in your componentsaveState(), loadState() and toString() with the following signature:

public function saveState():Object public function loadState(state:Object):void public function toString():String 

The saveState() method returns an object that contains name-value pairs that represent the current navigational state of the component. These name-value pairs are limited by the maximum URL size supported by the user's browser, for example Internet Explorer only supports 2083 characters. Because the space available is limited, you should try to write the least amount of data possible.

The loadState() method of the component is activated when the user clicks the forward and the back buttons in the web browser. The HistoryManager class passes a parameter to this method, which is identical to the object created by the saveState() method. Components that use the history management functionality must also implement the toString() method, but there is a default implementation of this method in the UIComponent class, meaning that if the component descends from UIComponent, it already has a default toString() method. However, as you learned in previous lesson, it is still a good idea to write your own toString() method, specific to your class, as it helps significantly in debugging.

If you are using history management in a custom HTML page (one not generated by Flex Builder), you must manually set up that HTML to support history management. This code is written for you, if you are using Flex builder to automatically generate the HTML.

You must include this HTML at the top of the page:

<script language='javascript' charset='utf-8'   src='/books/3/280/1/html/2//flex/flex-internal?action=history_js'></script> 

You then need to add the historyURL and iconId parameters to the flashVars variable in JavaScript as shown:

[View full width]
document.write("flashvars = 'historyUrl= %2Fflex%2Fflex%2Dinternal%3Faction%3Dhistory%5F  html&Iconid= " + lc_id +"&versionChecked=true'"); 

Add the history iframe, as shown here:

<iframe src='/books/3/280/1/html/2//flex/flex-internal?action=history_html' name='_history'   frameborder='0' scrolling='no' width='22' height='0'></iframe>