Managing Browser History Using Client Script
As a page developer, you can manage browser history entries and provide logical navigation by using the ScriptManager and ScriptManagerProxy server controls. You can also manage browser history through client script. You can enable history support in the client through the ScriptManager control. This generates client objects that you can use to manage browser history.
A history point is a logical navigation point in the Web application that can be represented through state information. The state information can be used to restore the Web application to a previous state, either directly with state data or through an identifier to state information that is stored elsewhere.
History points are stored in the browser's history stack only as URLs. History state is managed as data in a query string or as a URL fragment value that is marked with the "#" character. Because of size restrictions on URLs, the state information that you create must be as small as possible.
The following example shows a URL that contains enough history point data to identify the state. From this, the application can re-create the page at that state.
http://MySamples/Ajax/Default.aspx#state=2
When a user clicks the browser's Back button, the browser navigates through previously-viewed URLs, which will include URLs that contain history-point state. Client code in the Web page detects that the URL contains history state data and raises the client Sys.Application.navigate event. You can handle the event to reset the application to the state whose information is contained in the parameter values that are passed to the event.
Note
To work with the example code in this topic, you will need Visual Studio 2008 Service Pack 1 or a later release.
Enabling Browser History Management
In order to use history management, you must enable it through the ScriptManager server control. By default, history support is not enabled. When history is enabled, it is implemented differently for each browser. For Internet Explorer, an iframe element is rendered to the client, which can cause an additional request to the server. The model is therefore an opt-in approach.
The following example shows how to enable history declaratively through the ScriptManager control.
<asp:ScriptManager runat="server" ID="ScriptManager1"
EnableHistory="true" />
Creating Browser History Points
To create a browser history point, you call the Sys.Application.addHistoryPoint method. This method lets you define the history entry, its title, and any state that is required. You can use the state data to re-create the state of the page when a subsequent history navigation event is raised.
When you add a history point, or when the page is navigated and contains history state in the URL, the Sys.Application.navigate event is raised. This provides an event in the client that notifies you that history state has changed. You can handle the navigate event to re-create objects by using state data or to perform other operations.
The following example shows how you can manage history points in client code.
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
<title>Microsoft ASP.NET 3.5</title>
<link href="../../include/qsstyle.css" type="text/css" rel="Stylesheet" />
<script type="text/javascript">
function page_init() {
Sys.Application.add_navigate(onStateChanged);
var cb1 = $get('clientButton1');
var cb2 = $get('clientButton2');
var cb3 = $get('clientButton3');
$addHandler(cb1, "click", clientClick);
cb1.dispose = function() { $clearHandlers(cb1); }
$addHandler(cb2, "click", clientClick);
cb2.dispose = function() { $clearHandlers(cb2); }
$addHandler(cb3, "click", clientClick);
cb3.dispose = function() { $clearHandlers(cb3); }
}
function onStateChanged(sender, e) {
// When the page is navigated, this event is raised.
var val = parseInt(e.get_state().s || '0');
Sys.Debug.trace("Navigated to state " + val);
$get("div2").innerHTML = val;
}
function clientClick(e) {
// Set a history point in client script.
var val = parseInt(e.target.value);
Sys.Application.addHistoryPoint({s: val}, "Click Button:" + val);
Sys.Debug.trace("History point added: " + val);
}
</script>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:ScriptManager runat="server" ID="ScriptManager1" EnablePartialRendering="false" EnableHistory="true" />
<script type="text/javascript">
Sys.Application.add_init(page_init);
</script>
<h2>
Microsoft ASP.NET 3.5: Managing Browser History with Client Script</h2>
<p />
<div id="Div1" class="new">
<p>
This sample shows:</p>
<ol>
<li>The <code>Sys.Application</code> object and the <code>navigate</code> event and <code>addHistoryPoint</code> method.</li>
<li>The <code>addHistoryPoint</code> method demonstrates addition of titles.</li>
</ol>
</div>
<p>
</p>
<h2>Example 1: Managing browser history in client script</h2>
<p>This example includes three buttons. The handler for each button's <code>click</code> event sets
navigation history points using the <code>Sys.Application</code> object. The script used here, makes use of the
<code>Sys.Debug</code> class to dump trace information to the TEXTAREA at the bottom of the page.
</p>
<p>When you click the buttons, and history points are added, you will be able to see the list of history entries and their titles in the
"Recent Pages" drop-down in Internet Explorer, for example.
</P>
<p>To see history in action, perform the following steps:</p>
<ol>
<li>Press <b>1</b>. See the trace output.</li>
<li>Press <b>3</b>. See the trace output.</li>
<li>Press <b>2</b>. See the trace output.</li>
<li>Press the browser's Back button. Notice that the page is refreshed with previous data and
that trace information shows this.</li>
</ol>
<div id="div2" class="box">0</div><p></p>
<input type="button" id="clientButton1" value="1" />
<input type="button" id="clientButton2" value="2" />
<input type="button" id="clientButton3" value="3" />
<br /><br />
<textarea id="TraceConsole" cols="40" rows="5"></textarea>
</div>
</form>
</body>
</html>