Create custom navigation scheme for Windows 8.1 Store application. Part 1.

Hello everybody, and welcome.

That's my first article here and with it I start a cycle of articles that describe some xaml and mvvm-related features for creating Store applications.

These articles are more practical than theoretical, and as they may seem not too deep and can sometimes be wrong at some points, please don't hesitate to contact me and give advice how to enhance the article or code.

In this tutorial series we'll use Caliburn.Micro Conductor, EventAggregator and some VisualState transitions to build simple, but nice and seamless navigation in Windows Store app. Sample also demonstrates some dependency injection issues. But mostly it's just a demo. Please, don't expect it to follow guidelines strictly.

Navigation scheme we build will include

• Title page that has links to other application pages
• Back button to navigate backwards
• Breadcrumb-styled navigation to navigate between hierarchically linked pages and sections
• Main area to display application pages
• Animated closeable overlay panel to display additional information

In the first part of the journey we'll

• create the project, wire it up
• make simple navigation 
• add a back button functionality

You can get full code for that tutorial on the bitbucket

Now, let's get started.

Creating basic navigation and the main page

We'll proceed with Windows Store Blank app template in Visual Studio 2013, leaving aside universal apps for the moment, as soon it is going to be replaced with universal apps for Windows 10.

Let's start with creating the solution with two projects - one for views and another for view models, getting Caliburn.Micro from Nuget and bootstrapping the application in App.xaml.cs. Instead of simple container I'll use Unity. To simplify type registering I'll use UnityContainerHelper class with some extension methods.

That's how our configure method finally looks, and because we have views and viewmodels splitted between two projects we need to configure type mappings here.

32. protected override void Configure()
33. {
34.     ConfigureTypeMappings();
35.  
36.     this.container = new UnityContainer();
37.     this.container.RegisterContainerControlled<IEventAggregator, EventAggregator>();
38.     this.container.RegisterPerResolve<ShellViewModel>();
39. }
40.  
41. private void ConfigureTypeMappings()
42. {
43.     var config = new TypeMappingConfiguration
44.     {
45.         DefaultSubNamespaceForViews = "Samples.CustomNavigation.Views",
46.         DefaultSubNamespaceForViewModels = "Samples.CustomNavigation.UILogic.ViewModels"
47.     };
48.  
49.     ViewLocator.ConfigureTypeMappings(config);
50.     ViewModelLocator.ConfigureTypeMappings(config);
51. }

Make sure that App class inherits from CaliburnApplication.

In the ShellView.xaml we'll create a static area that will be present on all pages where we place an improvised navigation menu and an area for displaying active page. Overlay panel will be added later. Menu is constructed dynamically in the ShellViewModel's ObservableCollection<NavigationMenuItem> NavigationMenuItems, so we just bind it.

In the Item template we bind button's Click event to the ViewModel's MenuItemClicked Action with NavigationMenuItem passed as a parameter with the help of Caliburn.Micro notation.

11. <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
12.     <Grid.RowDefinitions>
13.         <RowDefinition Height="Auto"/>
14.         <RowDefinition Height="*"/>
15.     </Grid.RowDefinitions>
16.     
17.     <!--Menu-->
18.     <ItemsControl ItemsSource="{Binding NavigationMenuItems}">
19.         <ItemsControl.ItemsPanel>
20.             <ItemsPanelTemplate>
21.                 <StackPanel Orientation="Horizontal"/>
22.             </ItemsPanelTemplate>
23.         </ItemsControl.ItemsPanel>
24.         
25.         <ItemsControl.ItemTemplate>
26.             <DataTemplate>
27.                 <Button micro:Message.Attach="[Event Click] = [Action MenuItemClicked($dataContext)]">
28.                     <Button.Content>
29.                         <TextBlock Text="{Binding Name}" Style="{StaticResource SubheaderTextBlockStyle}"/>
30.                     </Button.Content>
31.                 </Button>
32.             </DataTemplate>
33.         </ItemsControl.ItemTemplate>
34.         
35.     </ItemsControl>
36.     
37.     <!--Content panel-->
38.     <ContentControl Grid.Row="1" x:Name="ActiveItemViewModel"
39.                     HorizontalContentAlignment="Stretch"
40.                     VerticalContentAlignment="Stretch"
41.                     />
42.     
43.     <!--TODO Overlay panel-->
44.     
45. </Grid>

To be able to get navigation messages from other parts of the application we create custom NavigationEvent and handle it in the ShellViewModel. Let it have two parameters for now - Id, it will define what View we'll navigate to and string Parameter - it will contain some additional information for our view model being displayed. In a real application it can contain some other information that is related to out navigation logic.

9. public class NavigationEvent
10. {
11.     public string Parameter { get; set; }
12. }

For displayed pages we create corresponding views and viewmodels and we create a simple ViewModelFactory that we register in App.xaml.cs.

6. public class ViewModelFactory
7. {
8.     public IScreen GetViewModel(string id)
9.     {
10.         switch (id)
11.         {
12.             case "Active1":
13.                 return new Active1ViewModel();
14.             case "Active2":
15.                 return new Active2ViewModel();
16.             case "Home":
17.                 return new HomeViewModel();
18.             case "Overlay":
19.                 return new OverlayViewModel();
20.             default:
21.                 throw new ArgumentException("Invalid parameter");
22.         }
23.     }
24. }

To display several view models simultaneously we need ShellViewModel to inherit from Conductor<IScreen>.Collection.AllActive and have the following properties in the code:

53. public IScreen ActiveItemViewModel { get; set; }
54. public IScreen OverlayViewModel { get; set; }

Notice that ActiveItemViewModel property name is the same as x:Name of ContentControl in ShellView.xaml. This is important.

ShellViewModel with menu creation and both ways of handling navigation events - either from clicking the button on navigation menu or coming from event aggregator now looks like:

9. public class ShellViewModel :
10.     Conductor<IScreen>.Collection.AllActive,
11.     IHandle<NavigationEvent>
12. {
13.     private readonly IEventAggregator eventAggregator;
14.     private readonly ViewModelFactory viewModelFactory;
15.  
16.     public ShellViewModel(IEventAggregator eventAggregator, ViewModelFactory viewModelFactory)
17.     {
18.         this.eventAggregator = eventAggregator;
19.         this.viewModelFactory = viewModelFactory;
20.  
21.         NavigationMenuItems = new ObservableCollection<NavigationMenuItem>();
22.         this.eventAggregator.Subscribe(this);
23.     }
24.  
25.     protected override void OnActivate()
26.     {
27.         CreateNavigationMenu();
28.     }
29.  
30.     private void CreateNavigationMenu()
31.     {
32.         NavigationMenuItems.Add(new NavigationMenuItem()
33.         {
34.             Name = "Home Page",
35.             NavigationEvent = new NavigationEvent() { Parameter = "Home" }
36.         });
37.         
38.         NavigationMenuItems.Add(new NavigationMenuItem()
39.         {
40.             Name = "Content Page 1",
41.             NavigationEvent = new NavigationEvent() {Parameter = "Active1"}
42.         });
43.         
44.         NavigationMenuItems.Add(new NavigationMenuItem()
45.         {
46.             Name = "Content Page 2",
47.             NavigationEvent = new NavigationEvent() { Parameter = "Active2" }
48.         });
49.     }
50.  
51.     public ObservableCollection<NavigationMenuItem> NavigationMenuItems { get; set; }
52.  
53.     public IScreen ActiveItemViewModel { get; set; }
54.     public IScreen OverlayViewModel { get; set; }
55.  
56.     public void MenuItemClicked(NavigationMenuItem item)
57.     {
58.         NavigateTo(item.NavigationEvent);
59.     }
60.  
61.     public void Handle(NavigationEvent navEvent)
62.     {
63.         NavigateTo(navEvent);
64.     }
65.  
66.     private void NavigateTo(NavigationEvent navEvent)
67.     {
68.         var viewModel = this.viewModelFactory.GetViewModel(navEvent.Parameter);
69.         ActiveItemViewModel = viewModel;
70.     }
71. }

It's not perfect yet and navigation menu creation can be abstracted away, but for now it's fine.

Notice that here we also use PropertyChanged.Fody. It helps to reduce PropertyChanged notification boilerplate code as it adds it automatically during the compilation step. All you need is to install it from Nuget and modify FodyWeavers.xml to contain PropertyChanged event names.

2. <Weavers>
3.   <PropertyChanged EventInvokerNames="NotifyOfPropertyChange" />
4. </Weavers>

Adding back-button functionality

Now let's add a back-button to our ShellView. It will be invisible when we are on the home page and visible when we navigate to some other view.

29. <AppBarButton Icon="Back"
30.               Margin="10,0,10,-20"
31.               micro:Message.Attach="[Event Click] = [Action NavigateBack]"
32.               Visibility="{Binding IsBackButtonVisible, Converter={StaticResource BoolToVis}}"
33.               />

To make navigation functionality available we should add navigation stack to our ShellViewModel.
For simplicity we'll use it without any size constraints and clear it when we navigate to the home page

17. private readonly Stack<IScreen> navigationBackStack = new Stack<IScreen>();

We modify NavigateTo method to clear navigation stack when we are on the home page. In a real application NavigateTo can be further splitted to detect what view model is being activated and modify the behavior according to that.

77. private void NavigateTo(NavigationEvent navEvent)
78. {
79.     //pushing current view model to navigation stack
80.     this.navigationBackStack.Push(ActiveItemViewModel);
81.  
82.     var viewModel = this.viewModelFactory.GetViewModel(navEvent.Parameter);
83.  
84.     //clearing stack if we go to the home page
85.     if (viewModel is HomeViewModel)
86.     {
87.         this.navigationBackStack.Clear();
88.     }
89.  
90.     ActiveItemViewModel = viewModel;
91. }

And NavigateBack Method itself

85. private void NavigateTo(NavigationEvent navEvent)
86. {
87.     //pushing current view model to navigation stack
88.     this.navigationBackStack.Push(ActiveItemViewModel);
89.  
90.     var viewModel = this.viewModelFactory.GetViewModel(navEvent.Parameter);
91.  
92.     //clearing stack if we go to the home page
93.     if (viewModel is HomeViewModel)
94.     {
95.         this.navigationBackStack.Clear();
96.         IsBackButtonVisible = false;
97.     }
98.     else
99.     {
100.         IsBackButtonVisible = true;
101.     }
102.  
103.     ActiveItemViewModel = viewModel;
104. }

Now we have simple navigation in a Windows Store app, made with Caliburn.Micro.

You can get full code for that article on the bitbucket. Part 1 code stops on commit "Part 1 complete. Navigation and Back Button".

In the second part we'll add

• some async and spinners to indicate loading process
• overlay panel to slide from aside and slide away when closed

Thanks for reading! Until the next part.