Navigator

Namespace: Wisej.Web.Ext.Navigator

Assembly: Wisej.Web.Ext.Navigator (4.1.0.0)

Manages the navigation between pages through deep linking. Pages are matched with a registered path that appears in the URL after the #.

C#
VB.NET

public sealed class Navigator

Public NotInheritable Class Navigator

The Navigator component matches registered routes and arguments with a Page in the application and automatically shows/hides (or creates and disposes) the page that matches the path.

This component is a "session singleton". Use it by addressing the class directly:

Navigator.Map("user/{id}", typeof(Views.UserPage));
Navigator.Navigate("user/16635");

If the path definition also specifies a pattern for arguments, the Navigator component extracts the parameters from the URL and makes them available in the Parameters collection.

Set the main view, or home page, either using the HomePage property or by registering a view with a "/" route.

The Navigator attaches to the application's hash, start and refresh events the first time any of its members is used in a session, and navigates to Hash when they occur.

Properties

Authenticated

Boolean: Returns or sets whether the current user is authenticated and can navigate the pages registered with the Navigator.

Setting this property has no effect on the page that is shown unless there is also a valid LoginPage assigned to the Navigator.

Changing the value navigates immediately: setting it to true navigates to the current Hash (the page originally requested) and setting it to false navigates to "/", which shows the LoginPage when assigned.

Example:

Authenticating the user from the login page:

private void buttonLogin_Click(object sender, EventArgs e)
{
    if (ValidateUser(this.textBoxUser.Text, this.textBoxPassword.Text))
        Navigator.Authenticated = true;
    else
        AlertBox.Show("Invalid user name or password.", MessageBoxIcon.Error);
}

CurrentPage

Page: Returns the page currently shown by the Navigator.

It's null when no route matches the current path or before the first navigation.

ExitPage

Page: Returns or sets the page to navigate to when the session is terminated. It can be the same as LoginPage.

The value is stored but it's currently not used by the Navigator.

HomePage

Page: Returns or sets the main (or home) page. Corresponds to the "/" or "" route.

Setting this property maps the "/" route to the page using Persist. Since routes are matched by prefix, the home page is also shown for paths that don't match any other route.

Example:

Setting the home page at startup:

static void Main()
{
    Navigator.HomePage = new MainPage();
    Navigator.Map("orders", typeof(OrdersPage));
}

LoginPage

Page: Returns or sets the page to show before navigating to any other page, unless Authenticated is set to true.

When the LoginPage is set, the Navigator will always show this page before navigating anywhere else (unless it's already authenticated).

In order to authenticate the user and navigate to the intended page, the LoginPage must set the Authenticated property to true. As soon as Authenticated is set to true, the Navigator hides the LoginPage (it's not disposed) and loads the intended destination page.

If the application sets Authenticated to false, the Navigator will automatically show the LoginPage again.

Example:

Protecting all the pages with a login page:

static void Main()
{
    Navigator.LoginPage = new LoginPage();
    Navigator.HomePage = new MainPage();
    Navigator.Map("reports", typeof(ReportsPage));
}

Parameters

NameValueCollection: Returns the parameters that have been extracted from the current URL.

The collection contains both the query string arguments (i.e. orders?year=2024) and the positional arguments declared in the route pattern (i.e. user/{id}). A new collection is created every time the Navigator navigates to a registered route.

Example:

Reading the arguments of the "user/{id}" route when the page is shown:

// Program.Main:
Navigator.Map("user/{id}", typeof(UserPage));

// UserPage:
private void UserPage_VisibleChanged(object sender, EventArgs e)
{
    if (this.Visible)
    {
        var id = Navigator.Parameters["id"];
        var tab = Navigator.Parameters["tab"];
        LoadUser(id, tab);
    }
}

Routes

NavigatorRouteCollection: Returns the collection of routes registered with the Navigator.

Use Map and Remove to add or remove routes.

Example:

Checking which page is registered for a route:

var entry = Navigator.Routes["user/"];
if (entry != null && entry.Page != null)
{
    AlertBox.Show("The user page is already loaded.");
}

Methods

Map(path, pageType, mode)

Maps the specified path to the pageType . The actual page instance is created the first time this route is used.

Parameter	Type	Description
path	String	Route that corresponds to the page. It can declare positional arguments in curly braces, i.e. "user/{id}".
pageType	Type	The page type to instantiate. It must derive from Page and have a public parameterless constructor.
mode	NavigatorPageMode	Whether the page should be disposed when the browser navigates to another page.

A leading "/" in path is ignored. Mapping a path that is already registered replaces the previous route.

Throws:

ArgumentNullException path or pageType is null.
ArgumentException pageType doesn't derive from Page.

Example:

Registering pages by type:

Navigator.Map("customers", typeof(CustomersPage));
Navigator.Map("customer/{id}", typeof(CustomerPage), NavigatorPageMode.Dispose);

// shows CustomerPage with Navigator.Parameters["id"] = "1042".
Navigator.Navigate("customer/1042");

Map(path, page, mode)

Maps the specified path to the page .

Parameter	Type	Description
path	String	Route that corresponds to the page. It can declare positional arguments in curly braces, i.e. "user/{id}".
page	Page	The page to show.
mode	NavigatorPageMode	Whether the page should be disposed when the browser navigates to another page.

When mode is Dispose the page instance is disposed when the browser navigates away and, since there is no type or callback to recreate it, the route won't show any page afterwards. Use Persist with page instances.

Throws:

ArgumentNullException path or page is null.

Example:

Registering an existing page instance:

var dashboard = new DashboardPage();
Navigator.Map("dashboard", dashboard);

Map(path, callback, mode)

Maps the specified path to the callback . The actual page instance is created the first time this route is used.

Parameter	Type	Description
path	String	Route that corresponds to the page. It can declare positional arguments in curly braces, i.e. "user/{id}".
callback	Func<Page>	Callback invoked to create the page when needed.
mode	NavigatorPageMode	Whether the page should be disposed when the browser navigates to another page.

With Dispose the callback is invoked again every time the route is used.

Throws:

ArgumentNullException path or callback is null.

Example:

Creating the page with a factory method:

Navigator.Map("invoices", () => new InvoicesPage(Application.Session["company"] as string), NavigatorPageMode.Dispose);

Navigate(path)

Navigates to the specified path .

Parameter	Type	Description
path	String	Route to navigate to, optionally followed by positional arguments and a query string, i.e. "user/16635" or "orders?year=2024".

The current page is hidden (and disposed when mapped with Dispose), then the page that matches path is created if necessary and shown. When a LoginPage is assigned and Authenticated is false, the login page is shown instead.

Fires CurrentPageChanged and ParametersChanged when applicable and finally updates Hash with path .

Throws:

ArgumentNullException path is null.

Example:

Navigating from a button:

private void buttonDetails_Click(object sender, EventArgs e)
{
    Navigator.Navigate("user/" + this.dataGridView1.CurrentRow.Cells["Id"].Value);
}

Remove(path)

Removes the route registered with the specified path .

Parameter	Type	Description
path	String	Route to remove from the navigation, as specified when calling `Map` but without the argument patterns (i.e. "user/" for "user/{id}").

The page associated with the route, if already created, is not hidden or disposed.

Throws:

ArgumentNullException path is null.

Example:

Removing a route when the user loses access to it:

Navigator.Remove("admin");

Properties​

Authenticated​

CurrentPage​

ExitPage​

HomePage​

LoginPage​

Parameters​

Routes​

Methods​

Map(path, pageType, mode)​

Map(path, page, mode)​

Map(path, callback, mode)​

Navigate(path)​

Remove(path)​

Events​

CurrentPageChanged​

ParametersChanged​

Properties

Authenticated

CurrentPage

ExitPage

HomePage

LoginPage

Parameters

Routes

Methods

Map(path, pageType, mode)

Map(path, page, mode)

Map(path, callback, mode)

Navigate(path)

Remove(path)

Events

CurrentPageChanged

ParametersChanged