This project is read-only.
Change the way you write web apps with Navigation for ASP.NET. Dive into some sample code, take a trip through the quick start documentation or read my blog for the latest on all things Navigational.


Navigation MVC
Navigation Web Forms


Imagine we had an unruly collection of thingamabobs and wanted to build a web app for keeping track of them all. We'd probably start with a page that listed all our thingamabobs. We could then select an individual thingamabob to update its details.

To Navigation for ASP.NET, each of these pages is a state. We connect two states together using a transition and we group connected states together using a dialog. Our thingamabob app needs one dialog containing two states linked by one transition. This information goes into the FluentStateInfoConfig class in the App_Start folder.

The only difference in the configuration between MVC and Web Forms is the way we create the states.


An MVC State requires a route, a controller and an action.

    .Dialog("Thingamabob", new
        Listing = new MvcState("listing", "Thingamabob", "List"),
        Details = new MvcState("details", "Thingamabob", "Details")
    }, d => d.Listing)
        .Transition("Select", d => d.Listing, d => d.Details)

Web Forms

A Web Forms State requires a route and a page.

    .Dialog("Thingamabob", new
        Listing = new WebFormsState("listing", "~/Listing.aspx"),
        Details = new WebFormsState("details", "~/Details.aspx")
    }, d => d.Listing)
        .Transition("Select", d => d.Listing, d => d.Details)

Before .NET40 we have to enter our configuration in the StateInfo.config file.

<dialog key="Thingamabobs" intial="Listing">
    <state key="Listing" route="listing" page="~/Listing.aspx">
        <transition key="Select" to="Details"/>
    <state key="Details" route="details" page="~/Details.aspx"/>


Our app for cataloguing thingamabobs is coming along, but we can't yet navigate between the two pages. We need to move from the listing to the details when selecting a thingamabob. We need to return to the listing to select a different thingamabob. And, with our thingamabob collection numbered in the thousands, we need the ability to page through the list.

These three different types of navigation are forward, back and refresh. Navigation for ASP.NET provides a different method for each one. Each method comes in two flavours, one performs a redirect and the other returns a Url.

To navigate forward from the Listing to Details state we pass the 'key' attribute of the transition.

StateController.Navigate("Select"); //Redirect
var link = StateController.GetNavigationLink("Select"); //Url

To navigate back from the Details to the Listing state we pass the number of steps to go back.

StateController.NavigateBack(1); //Redirect
var link = StateController.GetNavigationBackLink(1); //Url

To refresh the Listing state we don't need any parameters.

StateController.Refresh(); //Redirect
var link = StateController.RefreshLink; //Url

There are some bespoke classes for MVC and Web Forms that make navigating even easier.


For each of the three navigation types there's an ActionResult class we can return from a Controller.

new NavigateResult("Select");
new NavigateBackResult(1);
new RefreshResult();

We can build links for each navigation type using HtmlHelper extension methods.

@Html.NavigationLink("text", "Select")
@Html.NavigationBackLink("text", 1)

Web Forms

In .NET 4.5 we can build links for each navigation type using ASP.NET HyperLink Controls.

<asp:HyperLink runat="server" NavigateUrl="{NavigationLink Select}"/>
<asp:HyperLink runat="server" NavigateUrl="{NavigationBackLink 1}"/>
<asp:HyperLink runat="server" NavigateUrl="{RefreshLink}"/>

Before .NET 4.5 we can use NavigationHyperLink Controls.

<nav:NavigationHyperLink runat="server" Action="Select"/>
<nav:NavigationHyperLink runat="server" Direction="Back" Distance="1" />
<nav:NavigationHyperLink runat="server" Direction="Refresh"/>

Data Passing

We're well on the way to the completion of a web app that'll bring order to our chaotic hoard of thingamabobs. The next piece of the puzzle is data. The listing needs to know the page number we're on and the details needs to know the id of the selected thingamabob.

We can pass strongly-typed data using Navigation for ASP.NET. The forward and refresh navigation methods accept a second parameter holding this data. Back navigation provides no such overload because it remembers the data needed.

To select the 10th Thingamabob from the list we pass an id of 10.

StateController.Navigate("Select", new NavigationData { { "id", 10 } });
var link = StateController.GetNavigationLink("Select", new NavigationData {{ "id", 10 }});

To move to the second page of Thingamabobs we pass the page number 2.

StateController.Refresh(new NavigationData { { "page", 2 } });
var link = StateController.GetRefreshLink(new NavigationData { { "page", 2 } });

The Navigation for ASP.NET context object gives access to this passed data.

int page = (int) StateContext.Data["page"];

There are some bespoke classes for MVC and Web Forms that make passing navigation data even easier.


We can pass data in the return from a Controller using the ActionResult classes.

new NavigateResult("Select", new NavigationData { { "id", 10 } });
new RefreshResult(new NavigationData { { "page", 2 } });

We can pass data in a view using the HtmlHelper extension methods.

@Html.NavigationLink("text", "Select", new NavigationData { { "id", 10 } })
@Html.RefreshLink("text", new NavigationData { { "page", 2 } })

A navigation data ValueProvider lets us access the passed data as parameters in Controller methods.

public Thingamabob GetDetails(int id)

Web Forms

In .NET 4.5 we can pass data using ASP.NET HyperLink Controls.

<asp:HyperLink runat="server" NavigateUrl="{NavigationLink Select, id?int=10}"/>
<asp:HyperLink runat="server" NavigateUrl="{RefreshLink page?int=2}"/>

Before 4.5 we can pass data using NavigationHyperLink Controls.

<nav:NavigationHyperLink runat="server" Action="Select" ToData="id?int=10"/>
<nav:NavigationHyperLink runat="server" Direction="Refresh" ToData="page?int=2"/>

In .NET 4.5 a navigation data ValueProvider lets us access the passed data as parameters in data bound methods.

public Thingamabob GetDetails([NavigationData] int id)


Our thingamabob collection is now at our fingertips but the web app needs a bit of Ajax pizzazz. Paging through the list would be smoother if we returned the next set of thingamabobs using Ajax. We mustn't lose the ability to bookmark pages and for search engines to see our thingamabobs.


With just a smattering of Navigation for ASP.NET UI code we can turn a normal request into an Ajax one. Code outside of the UI doesn't change because the navigation data is identical before and after. Navigation for ASP.NET uses HTML5 History to make Urls we can bookmark and keeps the original hyperlinks for search engine visibility.

With the addition of a panel and a script, Navigation for ASP.NET will turn a refresh navigation into an Ajax request.


We build the panel using an AjaxHelper extension method.

@Ajax.RefreshPanel("panel", "",
 		<!-- Content -->

We add the script from the Scripts folder.

<script src="~/Scripts/navigation.mvc.js"></script>

Web Forms

Before adding the panel and the script we must make each refresh navigation issue a post back.

<asp:HyperLink NavigateUrl="{RefreshPostBack page?int=2}"/>
<nav:NavigationHyperLink Direction="Refresh" PostBack="true" ToData="page?int=2"/>

The panel's an ASP.NET UpdatePanel that contains a HistoryNavigator Control.

<asp:UpdatePanel ID="panel" runat="server">
 			<!-- Content -->
		<nav:HistoryNavigator runat="server" />

We add the script to the ScriptManager as a ScriptReference.

<asp:ScriptReference Name="Navigation.HTML5History.js" Assembly="Navigation" />

Last edited Jan 15, 2015 at 10:31 AM by GrahamMendick, version 44