Structured Navigation Using Page Functions!

One of the new features WPF has given us windows programmers is the “Page” as the supposed equivalent of the html web page..information can now flow from one page to another as in a website by linking one page to another via a hyperlink .This gives users the  familiar web experience(and looks much better than windows popping up with every click!!)..

Along with pages, WPF also introduces a concept known as Page Functions..but before i go there, lets examine WHY we need them!

Hyperlink driven navigation in pages has the following drawbacks

a) It is difficult to pass information between the host page and the calling page

b) In case the host page called a task page to do some work , its difficult for the host page to know if the work was actually completed or not

c) In some cases it is desired that the user should NOT be able to navigate back to the task page. For example once he has submitted the information he shouldn’t be allowed to go back using the Navigation service and change it. This is very difficult to achieve

The first 2 points above i.e. a and b can be achieved in the traditional page + hyperlink combination using Application scope properties to pass information between them, though not in a very structured manner. However it is very difficult to remove the task page reference from the history.

WPF has solved these issues by creating Page Functions.

Essentially, page functions enable a style of navigation that is analogous to functions in procedural languages, which typically involves the following:

• Calling a function.
• Passing parameters to the function.
• Performing processing from the function.
• Calling other functions from the function.
• Return results from the function to the calling code.
• Cleaning up.

Given below is the definition of a Page Function. To create a Page function you simple do a AddNewItemàPage Function into your solution.

PageFunction.xaml

<PageFunction

    xmlns=”http://schemas.microsoft.com/winfx/2006/xaml/presentation&#8221;

    xmlns:x=”http://schemas.microsoft.com/winfx/2006/xaml&#8221;

            xmlns:sys=”clr-namespace:System;assembly=mscorlib”

    x:Class=”CSharp.TaskPageFunction”

          x:TypeArguments=”sys:String”

    Title=”Task Page Function” WindowWidth=”250″ WindowHeight=”150″>

  <Grid Margin=”10″></Grid>

</PageFunction>

PageFunction.xaml.cs

       public partial class TaskPageFunction : PageFunction<String>

{

    public TaskPageFunction()

    {

        InitializeComponent();

    }

}

The declaration is pretty much similar to a page. However Page Function is a generic class and needs a declaration of the Type of the value it will return.This is set in the  x:TypeArguments=”sys:String” in the xaml configuration and correspondingly as <String> in the Page.xaml.cs file

You can create your own custom types and use your page function to return custom information (If you are interested leave me a comment and i can upload an example!).

Now that we know the concept of Page Function and how to define it. We’ll see how to create, call, pass values and get the results from a page function

Creation and calling and passing value: It is same as creating an instance of a Page and navigation to it

TaskPageFunction taskPageFunction = new TaskPageFunction()//Call an overloaded constructor if you want to pass information to it,

        this.NavigationService.Navigate(taskPageFunction);

        Getting return value from the task page

In order to pass values back to the Calling page, Task page calls a method called OnReturn(). OnReturn is a protected virtual method which will be called with an instance of Generic ReturnEventArgs of the type same as the Type arguments you had specified for the page function.

So whatever data you want to return will be sent to the OnReturn() function.

For example in the Page function definition we created above, on clicking a submit button you want to pass the text entered by the user into a textbox called “NameTextBox” the code will be as under

Public void SubmitClicked(sender object, RoutedEventAgrs args){OnReturn(new ReturnEventArgs<string>(this. NameTextBox.Text));} 

The OnReturn() method in turn fires the Return event of the task page which the calling class has to hook onto.

 

To summarize the following 3 parts of the code are needed to complete the navigation

//create the page function, hook onto its Return event and navigate to it

TaskPageFunction taskPageFunction = new TaskPageFunction()taskPageFunction.Return += taskPageFunction_Return; this.NavigationService.Navigate(taskPageFunction);

// the Page function will call ONReturn on completing its task

OnReturn(new ReturnEventArgs<string>(this. NameTextBox.Text));

The Calling page method delegated to receive the event will get called and will extract the information from the event args passed to it

void taskPageFunction_Return(object sender, ReturnEventArgs<string> e) {  MessageBox.Show(“Name  Is “+ e.Result}    

Removal of Page function ref from the Navigation history

Every PageFunction /Page has a property called as RemoveFromJournal .Setting it to true removes it from the navigation history after the page has been navigated away from.

      By default a Page function has RemoveFromJournal set to true. So it will be removed  from history once its OnReturn has been called.

 

Oh btw…this form of Navigation is called Structured Navigation in WPF Terminology!!

Enjoy!

Cennest