Click here to Skip to main content
15,867,568 members
Articles / Programming Languages / C# 4.0

Prism for Silverlight/MEF in Easy Samples. Part 2 - Prism Navigation

Rate me:
Please Sign up or sign in to vote.
4.98/5 (66 votes)
21 Mar 2011CPOL12 min read 210K   3.8K   79   77
Prism for Silverlight/MEF in Easy Samples tutorial. Part 2 - Prism Navigation

Download PrismTutorialSamples_PART2.zip - 285.46 KB

Introduction

This is a Part 2 of Prism for Silverlight/MEF in Easy Samples Tutorial. Part 1 can be accessed at Prism for Silverlight/MEF in Easy Samples. Part 1 - Prism Modules and Part 3 - at Prism for Silverlight/MEF in Easy Samples. Part 3 - Communication between the Modules

In this part, I cover Prism Region Navigation, which allows changing a view displayed or active within a Prism Region. (For region definition and samples look at the first part of this tutorial).

Region navigation is essential for properly using the "real estate" of the application by changing the views displayed at different locations within the application screen depending on the current state of the application.

Region Navigation functionality within Prism allows loading a view within a region based on the view's class name, passing navigation parameters, making decisions whether the view should be displayed or not, cancelling the navigation if needed and recording the navigation operations.

On top of the prerequisites listed for "Part 1" (C#, MEF and Silverlight), one also needs to understand the MVVM pattern for some of the samples in "Part 2".

Region Navigation Overview and Samples

Simple Region Navigation Sample

This sample's code is located under SimpleRegionNavigation.sln solution. It demonstrates basic navigation functionality. Module1 of the sample application has two views: Module1View1 and Module1View2. Both views are registered with "MyRegion1" region within the Module1Impl.Initialize method (view discovery is used to associate these views with the region):

public void Initialize()
{
    TheRegionManager.RegisterViewWithRegion
    (
        "MyRegion1",
        typeof(Module1View1)
    );

    TheRegionManager.RegisterViewWithRegion
    (
         "MyRegion1",
         typeof(Module1View2)
    );
}

Both views display a message (a TextBlock specifying the name of the view) and a button to switch to the other view. The foreground of Module1View1 is red, while the foreground of Module1View2 is green.

There are two ways to navigate to a view within a region:

  1. By using RegionManager's RequestNavigate method.
  2. By using Region's RequestNavigate method.
These two methods are very similar, except that RegionManager.RequestNavigate function requires region name as its first parameter, while Region's method does not require it.

To demonstrate both methods, Module1View1 navigates to Module1View2 using RegionManager.RequestNavigate function:

TheRegionManager.RequestNavigate
(
    "MyRegion1",
    new Uri("Module1View2", UriKind.Relative),
    PostNavigationCallback
);

while Module1View2 navigates to Module1View1 using Region.RequestNavigate:

_region1.RequestNavigate
(
    new Uri("Module1View1", UriKind.Relative),
    PostNavigationCallback
);

One can see that both methods require a relative Uri argument, whose string matches the name of the view we want to navigate to.

Both methods also need a post-navigation callback as their last argument. This is because some navigation implementations might be asynchronous so, if you want some code for sure to be executed after the end of the navigation you put it within the post-navigation callback. In our case we want to display a modular MessageBox stating whether the navigation was successful or not:

void PostNavigationCallback(NavigationResult navigationResult)
{
    if (navigationResult.Result == true)
        MessageBox.Show("Navigation Successful");
    else
        MessageBox.Show("Navigation Failed");
}

Many times, however, the post-navigation callback is not needed, and then the following simple lambda can be placed in its stead:

a => { }

Up to now we've covered the code behind for Module1View1 view located within Module1View1.xaml.cs file. Module1View2 functionality, however, is more complex. We can see, that Module1View2 class implements IConfirmNavigationRequest interface. IConfirmNavigationRequest extends INavigationAware interface.

INavigationAware interface has three methods:

bool IsNavigationTarget(NavigationContext navigationContext);
void OnNavigatedFrom(NavigationContext navigationContext);
void OnNavigatedTo(NavigationContext navigationContext);

IsNavigationTarget method allows the navigation target to declare that it does not want to be navigated to, by returning "false". This method is most useful with injected views as will be shown below.

OnNavigatedFrom method is called before one navigates away from a view. It allows doing any pre-navigation processing within the view that has been navigated from. In case of Module1View2 we show a message box:

public void OnNavigatedFrom(NavigationContext navigationContext)
{
    MessageBox.Show("We are within Module1View2.OnNavigatedFrom");
}

OnNavigatedTo method is called after one navigates to the view. It allows doing any post-navigation processing within the view that has been navigated to. In case of Module1View2 a message box is shown:

public void OnNavigatedTo(NavigationContext navigationContext)
{
    MessageBox.Show("We are within Module1View2.OnNavigatedTo");
}

The above methods IsNavigationTarget, OnNavigatedFrom and OnNavigatedTo are part of INavigationAware interface (which IConfirmNavigationRequest extends) and can be used if the view class implements INavigationAware only. The method ConfirmNavigationRequest, however, is only part of IConfirmNavigationRequest and in order to use it one needs to implement IConfirmNavigationRequest interface.

ConfirmNavigationRequest method is called before one navigates from the current view. It gives you a last chance to cancel the navigation. Its second argument is a delegate called "continuationCallback" that takes a Boolean value as its argument. Calling continuationCallback(true) will allow the navigation to continue, while calling continuationCallback(false) will cancel it.

Within Module1View2 we show a message box, asking whether the user wants to continue navigation or cancel it and the argument to "continuationCallback" is determined by whether the user pressed OK or Cancel button:

public void ConfirmNavigationRequest(NavigationContext navigationContext, Action<bool> continuationCallback)
{
    MessageBoxResult messageBoxResult =
        MessageBox.Show("Should Navigate from Current View?", "Navigate", MessageBoxButton.OKCancel);

    bool shouldNavigateFromCurrentView = messageBoxResult.HasFlag(MessageBoxResult.OK);

    continuationCallback(shouldNavigateFromCurrentView);
}

Even though we use a modular window that blocks the control flow until the user clicks a button, non-modular control can also be used to continue or cancel the navigation - we simply need to pass the "continuationCallback" parameter to it and based on the user action it should either call continuationCallback(true) or continuationCallback(false).

This is how the application looks when it is started:

Image 1

Once "Navigate to Next View" button is clicked, we get a popup indicating that we are inside Module1View2.OnNavigatedTo function. After OK is clicked, we are getting the post-navigate callback message indicating that the navigation has been successful. Once OK is clicked, the new view is shown on the screen:

Image 2

If we click "Navigate to Next View" button now, we'll hit the Module1View2.ConfirmNavigationRequest method first, which will show us a popup window asking whether to continue navigation or cancel it. If we press ok, navigation to Module1View1 continues successfully, otherwise it fails and we stay at Module1View2. (In case of successful navigation we get two more modular popups - one indicating that we are inside Module1View2.OnNavigatedFrom function and one informing us that the navigation was successful, while in case of a navigation failure we are informed of it by a message popup)

Exercise: create a similar demo (look at "Prism for Silverlight/MEF in Easy Samples Tutorial Part1" for instructions on how to create projects for Silverlight Prism application and modules and how to load the module into the application using the bootstrapper).

Exercise: create a similar demo with the two views located in different modules instead of them being within the same module. (Since several people had difficulty with this exercise, I added another sample illustrating navigation between two views located in different modules: NavigationBetweenTwoDifferentModules.zip).

Simple Navigation via the View Model

In the above example, Module1View2 view implements IConfirmNavigationRequest interface and because of that its functions IsNavigationTarget, OnNavigatedFrom, OnNavigatedTo and ConfirmNavigationRequest participate in the navigation process. A better way, however, is to make all the navigation decisions within the view model (if MVVM pattern is being followed). So, Prism provides a way for the view model to implement INavigationAware or IConfirmNavigationRequest interfaces (instead of the view).

The rule is the following: if the view implements one of INavigationAware or IConfirmNavigationRequest interfaces than the view's corresponding methods will be called during the navigation. If, however, the view does not implement it, but the view's DataContext does, then the corresponding functions of the DataContext will be involved as demonstrated by our sample under NavigationViaViewModel.sln solution.

Module1View1 is almost the same as in the previous sample (aside from the fact that it does not popup message windows).

Module1View2 does not implement IConfirmNavigationRequest. Instead, within the constructor, it sets its DataContext property to be a new object of View2Model type:

// we are setting the DataContext property of
// Module1View2 view
View2Model view2Model = new View2Model();
DataContext = view2Model;

View2Model is a non-visual (as a view model should be) class that implements IConfirmNavigationRequest:

public class View2Model : IConfirmNavigationRequest
{
    // we use this event to communicate to the view
    // that we are starting to navigate from it
    public event Func<bool> ShouldNavigateFromCurrentViewEvent;

    #region INavigationAware Members

    public bool IsNavigationTarget(NavigationContext navigationContext)
    {
        return true;
    }

    public void OnNavigatedTo(NavigationContext navigationContext)
    {

    }

    public void OnNavigatedFrom(NavigationContext navigationContext)
    {

    }

    #endregion

    #region IConfirmNavigationRequest Members

    public void ConfirmNavigationRequest(NavigationContext navigationContext, Action<bool> continuationCallback)
    {
        bool shouldNavigateFromCurrentViewFlag = false;

        if (ShouldNavigateFromCurrentViewEvent != null)
            shouldNavigateFromCurrentViewFlag = ShouldNavigateFromCurrentViewEvent();

        continuationCallback(shouldNavigateFromCurrentViewFlag);
    }

    #endregion
}

We use the view model's ShouldNavigateFromCurrentViewEvent event to inform the view that navigation has been started away from it. The view connects a handler to this event within the view's constructor:

view2Model.ShouldNavigateFromCurrentViewEvent +=
           new Func<bool>(view2Model_ShouldNavigateFromCurrentViewEvent);

Just like in the previous sample, View2Model.view2Model_ShouldNavigateFromCurrentViewEvent displays a modular popup window asking whether the user wants to continue or cancel the navigation. Then, depending on the user choice it returns a Boolean to the view model and the View2Model.ConfirmNavigationRequest's "continuationCallback" argument is called with the corresponding value specifying whether to continue or cancel the navigation.

Exercise: create a similar demo.

Navigation Parameters Sample

If a view or a view model implements INavigationAware or IConfirmNavigationRequest, interface, the navigation can pass parameters to these functions as part of the navigation Url. As I mentioned above, the Url should contain the name of the view class to which one wants to navigate. This name of the class can be followed by '?' character and key-value parameter pairs where the keys are separated from the values by '=' character and the pairs are separated from each other by '&' character.

NavigationParameters.sln solution contains a sample where the view Module1View1 navigates to itself but with different parameters.

Here is how the sample's window looks:

Image 3

One can enter any text into the text box above, then press the button "Copy via Navigation" and the text will be copied into the text block below.

The "Copy via Navigation" has the following callback:

void NextViewButton_Click(object sender, RoutedEventArgs e)
{
    if (TheTextToCopyTextBox.Text == null)
        TheTextToCopyTextBox.Text = "";

    // navigate passing the paramter "TheText"
    TheRegionManager.RequestNavigate
    (
        "MyRegion1",
        new Uri("Module1View1?TheText=" + TheTextToCopyTextBox.Text, UriKind.Relative),
        a => { }
    );
}

Note that the full Url will look like: "Module1View1?TheText=<text-to-copy>".

Module1View1 view implements INavigationAware interface, so, its own OnNavigatedTo function will be called at the end of the navigation process. Within this function we get the UriQuery dictionary from the navigationContext argument and from the UriQuery dictionary we get the value corresponging to "TheText" key as below:

public void OnNavigatedTo(NavigationContext navigationContext)
{
    TheCopiedTextTextBlock.Text = navigationContext.UriQuery["TheText"];
}

Of course, in reality, RequestNavigate and OnNavigatedTo functions can be in different views and even in different modules, and instead of a trivial task of copying text, other much more complex tasks requiring navigation parameters might be employed.

Exercise: Create a similar demo.

Using IsNavigationTarget Method for Navigating to Injected Views

In case of the view injection there can be multiple views of the same view type within an application. Navigating based on the Url containing the View class name only, will not work in that case, since all those views have the same view class. Prism employs bool INavigationAware.IsNavigationTarget(NavigationContext) method to specify which view to navigate to in such case.

When navigating to injected views, each of the region's views of the specified type has its INavigationAware.IsNavigationTarget method called until one of them returns "true" (or until all of them return "false"). The view whose INavigationAware.IsNavigationTarget method returns "true" will be navigated to.

The corresponding sample is located under InjectedViewNavigation.sln solution. Unlike in previous examples, the region control is represented by a ListBox in the application's Shell.xaml file:

XML
<ListBox HorizontalAlignment="Center"
         VerticalAlignment="Center"
         prism:RegionManager.RegionName="MyRegion1">
</ListBox>

so that it displays every view connected to the region and navigating to a view makes this view selected within the list box:

Image 4

The view is defined by Module1View1 class. It has ViewID property that uniquely specifies the view object. This class also has a static method CreateViews() which creates 5 views with different ViewIDs ranging from 1 to 5 and associates the created views with "MyRegion1" region:

public static void CreateViews(IRegionManager regionManager)
{
    IRegion region = regionManager.Regions["MyRegion1"];

    for (int i = 1; i <= MAX_VIEW_ID; i++)
    {
        Module1View1 view = new Module1View1 { ViewID = i };
        view.TheRegionManager = regionManager;
        region.Add(view);
    }
}

Each view has a button to navigate to the next view. The button click has the following event handler:

void NextViewButton_Click(object sender, RoutedEventArgs e)
{
    NextViewButton.IsEnabled = false;
    TheRegionManager.RequestNavigate
    (
        "MyRegion1",
        new Uri("Module1View1?ViewID=" + NextViewID, UriKind.Relative),
        a => { }
    );
}

As you can see, we navigate to the "Module1View1" view passing "ViewID" parameter set to point to a value returned by NextViewID property.

NextViewID returns the ViewID of the current view plus one unless it is the last view in the set - then it goes back to ViewID=1:

int NextViewID
{
    get
    {
        if (ViewID < Module1View1.MAX_VIEW_ID)
            return ViewID + 1;

        return 1;
    }
}

IsNavigationTarget method compares the "ViewID" parameter received as part of the Navigation Url to the ViewID property of the view. If they are the same, it returns true (this means we navigate to this view), if they are different, it returns false (the view is not navigated to):

public bool IsNavigationTarget(NavigationContext navigationContext)
{
    string viewIDString = navigationContext.UriQuery["ViewID"];

    int viewID = Int32.Parse(viewIDString);

    bool canNavigateToThisView = (viewID == ViewID);

    return canNavigateToThisView;
}

One can see that by pushing the view's "Navigate to Next View" button, we indeed switch to the next view. After changing NextViewID property to return every second view, we can see that every second view in the list gets selected. If we change the region control within Shell.xaml file of the application project to be a ContentControl instead of a ListBox the navigation will be displaying the navigated view instead of selecting it.

Exercise: Create a similar demo.

Undo-Redo Functionality Using Navigation Journal

Navigation functionality also includes undo-redo capabilities as shown in this sample. The sample is located under NavigationJournal.sln solution.

This sample is very similar to the previous one, only each injected view has two more buttons: "Back" button and "Forward" button. "Back" button allows undoing the last operation, while "Forward" - redoing the last undone operation:

Image 5

"Back" and "Forward" buttons are enabled only when the corresponding operations are possible.

Undo-redo functionality is available from RegionNavigationJournal, which in turn can be accessed via RegionNavigationService. We can get a reference to the navigation service from the navigationContext argument within OnNavigatedTo method:

public void OnNavigatedTo(NavigationContext navigationContext)
{
    // getting a reference to navigation service:
    if (_navigationService == null)
        _navigationService = navigationContext.NavigationService;

    ...
}

Here is how "Back" button hooks to the corresponding Undo functionality:

void BackButton_Click(object sender, RoutedEventArgs e)
{
    _navigationService.Journal.GoBack();

    ...
}

"Forward" button's handler is calling _navigationService.Journal.GoForward() method instead.

Button enabling/disabling functionality is based on _navigationService.Journal.CanGoBack and _navigationService.Journal.CanGoForward properties for "Back" and "Forward" buttons correspondingly. It seems that it is logical to add button enabling/disabling functionality to the body of OnNavigatedTo method (which is called on Undo-Redo), but unfortunately it is called before the navigation Journal state is updated, so that the CanGoBack and CanGoForward properties do not have the correct values yet. In order to get around this problem, I had to figure out which view is current based on the Uri property of the current entry within the Journal. We get the ViewID from the Uri and set IsEnabled properties on the "Back" and "Forward" buttons of the corresponding view:

void UpdateIfCurrentView()
 {
     if (_navigationService == null)
         return;

     string uriStr = _navigationService.Journal.CurrentEntry.Uri.OriginalString;

     int lastEqualIdx = uriStr.LastIndexOf('=');

     string viewIDStr = uriStr.Substring(lastEqualIdx + 1);

     int viewID = Int32.Parse(viewIDStr);

     if (viewID != this.ViewID)
         return;

     BackButton.IsEnabled = _navigationService.Journal.CanGoBack;
     ForwardButton.IsEnabled = _navigationService.Journal.CanGoForward;
 }

Method UpdateIfCurrentView is set as the static JournalUpdatedEvent event handler for each of the created views:

public Module1View1()
{
    InitializeComponent();

    ...

    JournalUpdatedEvent += UpdateIfCurrentView;

    ...

}

"Back" and "Forward" button click handlers call JournalUpdatedEvent after calling _navigationService.Journal.GoBack() or _navigationService.Journal.GoForward() methods:

void BackButton_Click(object sender, RoutedEventArgs e)
{
    _navigationService.Journal.GoBack();
    DisableButtons();

    JournalUpdatedEvent();
}

void ForwardButton_Click(object sender, RoutedEventArgs e)
{
    _navigationService.Journal.GoForward();

    DisableButtons();

    JournalUpdatedEvent();
}

Important Note: the journal undo/redo functionality works only within one region. If there are multiple regions each one of them will have their own undo/redo sequence.

Exercise: create a similar demo.

Conclusion

In part 2 of this tutorial I gave a detailed description of Prism's Navigation functionality in small and simple samples. I'd appreciate very much if you could vote for this article and leave a comment. I would love to hear your suggestions for improving and expanding the content of this tutorial.

History

Feb 15, 2011 - changed the code to use latest Prism dlls (which lead to significant changes in API: INavigationAwareWithVeto interface was replaced by IConfirmNavigationRequest, CanNavigateTo() was replaced by IsNavigationTarget() and method OnNavigatedFrom was added to INavigationAware interface. Hat tip to jh1111 for noticing that my API was out of date.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Architect AWebPros
United States United States
I am a software architect and a developer with great passion for new engineering solutions and finding and applying design patterns.

I am passionate about learning new ways of building software and sharing my knowledge with others.

I worked with many various languages including C#, Java and C++.

I fell in love with WPF (and later Silverlight) at first sight. After Microsoft killed Silverlight, I was distraught until I found Avalonia - a great multiplatform package for building UI on Windows, Linux, Mac as well as within browsers (using WASM) and for mobile platforms.

I have my Ph.D. from RPI.

here is my linkedin profile

Comments and Discussions

 
GeneralMy vote of 5 Pin
kaballo123-Jul-13 21:42
kaballo123-Jul-13 21:42 
GeneralRe: My vote of 5 Pin
Nick Polyak25-Aug-13 10:08
mvaNick Polyak25-Aug-13 10:08 
GeneralMy vote of 5 Pin
Elon Yakir8-Jun-13 21:28
Elon Yakir8-Jun-13 21:28 
GeneralRe: My vote of 5 Pin
Nick Polyak9-Jun-13 8:28
mvaNick Polyak9-Jun-13 8:28 
GeneralMy vote of 5 Pin
Conia_He27-May-13 18:14
Conia_He27-May-13 18:14 
GeneralRe: My vote of 5 Pin
Nick Polyak2-Jun-13 5:51
mvaNick Polyak2-Jun-13 5:51 
GeneralAwesome tutorial Pin
mskmeric16-Jun-12 10:19
mskmeric16-Jun-12 10:19 
GeneralRe: Awesome tutorial Pin
Nick Polyak9-Sep-12 7:45
mvaNick Polyak9-Sep-12 7:45 
QuestionGreat Tutotial Pin
darkzet25-Mar-12 15:57
darkzet25-Mar-12 15:57 
AnswerRe: Great Tutotial Pin
Nick Polyak26-Mar-12 13:46
mvaNick Polyak26-Mar-12 13:46 
QuestionLove it! Thank you so much. Pin
Nate Pirtz19-Feb-12 7:49
Nate Pirtz19-Feb-12 7:49 
AnswerRe: Love it! Thank you so much. Pin
Nick Polyak9-Mar-12 11:21
mvaNick Polyak9-Mar-12 11:21 
GeneralSuperb Tutorials Pin
Veerendranadh7-Jan-12 21:18
Veerendranadh7-Jan-12 21:18 
GeneralRe: Superb Tutorials Pin
Nick Polyak8-Jan-12 4:00
mvaNick Polyak8-Jan-12 4:00 
GeneralMy vote of 5 Pin
bing yu30-Dec-11 11:00
bing yu30-Dec-11 11:00 
GeneralRe: My vote of 5 Pin
Nick Polyak31-Dec-11 13:44
mvaNick Polyak31-Dec-11 13:44 
Question5 stars - this is how tutorials should be done Pin
nukenuts20-Nov-11 6:14
nukenuts20-Nov-11 6:14 
AnswerRe: 5 stars - this is how tutorials should be done Pin
Nick Polyak20-Nov-11 6:35
mvaNick Polyak20-Nov-11 6:35 
GeneralMy vote of 5 Pin
wrawson31-Oct-11 4:48
wrawson31-Oct-11 4:48 
GeneralRe: My vote of 5 Pin
Nick Polyak31-Oct-11 14:17
mvaNick Polyak31-Oct-11 14:17 
QuestionNavigation... [modified] Pin
kasunsm.kt14-Sep-11 19:38
kasunsm.kt14-Sep-11 19:38 
QuestionRe: Navigation... [modified] Pin
bing yu30-Dec-11 10:48
bing yu30-Dec-11 10:48 
AnswerRe: Navigation... [modified] Pin
Nick Polyak31-Dec-11 14:23
mvaNick Polyak31-Dec-11 14:23 
AnswerRe: Navigation... [modified] Pin
Nick Polyak31-Dec-11 14:20
mvaNick Polyak31-Dec-11 14:20 
GeneralRe: Navigation... [modified] Pin
bing yu3-Jan-12 4:24
bing yu3-Jan-12 4:24 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.