Views are instances of the Silverlight Navigation Page class defined in the System. Windows.Controls.Navigation namespace. The Silverlight tools include a template for a blank page deriving from the navigation:Page class, a class which is essentially a UserControl that has been beefed up to support navigation.

Right-click the Views folder, and select Add New Item. In the Add New Item dialog, select the Silverlight Page template, and name the file CustomerDetail.xaml. Figure 15.5 shows the Add New Item dialog with the correct selections.

Figure 15.5. The Add New Item dialog with the Silverlight Page template selected. This is the template to be used for views in a Silverlight navigation application. I may have more templates than you; I've installed some add-ins.

After you've added the new page, you need to provide a way for the end user to find it. In a regular desktop application, this may be a menu or toolbar. For this navigation application, you'll use a HyperlinkButton.

In this template, navigation to individual pages is accomplished by HyperlinkButton instances on MainPage.xaml. The pages themselves are loaded in the navigation: Frame element named ContentFrame.

On MainPage.xaml is a Border named LinksBorder. This is the navigation menu that appears at upper right. The default XAML for this area is shown in listing 15.1.

Example 15.1. LinksBorder showing navigation menu

This Border contains the top menu navigation structure for the application. It's a simple StackPanel of elements: HyperlinkButton instances separated by vertical lines (narrow rectangles).

Note that I removed the x:Name from the divider rectangle, because it's not needed. The names in the HyperlinkButton instances also aren't needed, but I gave them meaningful names to help with the discussion here, and in case you decide to do something with them in code. In your own project, you can remove the names if you'd like.

To add your own page to the navigation structure, you need to follow this pattern and add a divider rectangle (optional, but recommended) and a HyperlinkButton pointing to your page. Place this markup in the XAML in the spot indicated in the previous listing:

<Rectangle Style="{StaticResource DividerStyle}" />

<HyperlinkButton x:Name="CustomerDetailLink"
                 Style="{StaticResource LinkStyle}"
                 NavigateUri="/CustomerDetail"
                 TargetName="ContentFrame"
                 Content="customer" />

When copying and pasting from the other links, I left the divider alone but changed a couple properties of the HyperlinkButton. The first is the x:Name property, which is optional because it's not used in any code, binding, or animation in the default template. The second is the Content. This is what will be displayed on the menu bar. You could easily use images rather than text if you'd like. You're also free to change the LinkStyle resource to modify the appearance. The final property is the NavigateUri. That needed to be changed to point to the newly added page.

You may have noticed that the URI for the page is set to /CustomerDetail, when the actual page is stored in /Views/CustomerDetail.xaml. This is handled by the URI mapper, which we'll cover later in this chapter.

Although it isn't unique to the navigation API, one other nice feature of the navigation application is its ability to be easily styled or themed.

The Page class includes four navigation-related virtual functions. Override these when you want to perform an action on a specific navigation step. Table 15.1 lists the functions of each.

These four events were implemented as virtual functions to eliminate the requirement of hooking up event handlers, potentially keeping pages around longer than intended.

You'll use the OnFragmentNavigation when you want to respond to subnavigation within the current page. This is a powerful but seldom-used capability similar in intent to hashtag or fragment navigation on HTML pages.

A good place for page cleanup code, or persisting to a backup cache, is the OnNavigatedFrom method. This is fired when the page is no longer the active page, so it's too late to use to prompt the user for saving. Use the OnNavigatingFrom method when you need to prompt the user.

The OnNavigatingFrom method provides a facility for informing the user that the page is about to be navigated away from. The method signature allows for canceling the navigation, typically in response to a prompt to the user.

Finally, the OnNavigatedTo method is the one most commonly used in navigation pages. This is typically used for any data loading or data-cache retrieval, as well as any page setup. Because pages can themselves be cached, this is the place to check the state of that page cache and perform any operations necessary to make the page available to the user.

The source of the event information is the NavigationService class, which also has several other useful properties and methods.

Silverlight navigation applications load content pages into frames. In our walkthrough of the Navigation Application template in section 15.2, you saw that the HyperlinkButton in the MainPage.xaml file invokes navigation for you. Although using a HyperlinkButton is an easy way to get content into a frame, it's not the only way. Take for example

ContentFrame.Navigate(new Uri("/CustomerDetail", UriKind.Relative));

If the page /CustomerDetail maps to a valid page via the in-force URI mapping, this example will navigate to that page. You could put this type of code in a button or any sort of other handler in the application. The ability to navigate using code means you're not stuck with using HyperlinkControls for your application navigation: you can use traditional menus, ListBoxes, Buttons, or pretty much anything you'd like

When working with navigation pages, you typically don't navigate to pages using a full filename such as CustomerDetail.xaml. Instead, you map friendly URIs to these absolute URIs. This is done through a property on the Frame class.

The Frame class exposes a property named UriMapper of type UriMapperBase. This is responsible for translating real application URIs into something more user-friendly. The default implementation is a class containing a collection of UriMapping objects. Table 15.5 shows the members of the UriMapper class.

The UriMapper property of the frame class is read/write. Should you desire, you can create your own UriMapper implementation, using your own scheme for mapping URIs. To do so, inherit from UriMapperBase and provide the required functionality in the MapUri function.

In the example at the beginning of this chapter, you saw how the mapper automatically translated /CustomerDetail into /Views/CustomerDetail.xaml. The default UriMapper class exposes the UriMappings collection. Here's the full XAML for the mapping:

<navigation:Frame.UriMapper>
  <uriMapper:UriMapper>
    <uriMapper:UriMapping Uri=""
                          MappedUri="/Views/Home.xaml"/>
    <uriMapper:UriMapping Uri="/{pageName}"
                          MappedUri="/Views/{pageName}.xaml"/>
  </uriMapper:UriMapper>
</navigation:Frame.UriMapper>

Given this mapping, and assuming an application URI of http://myapp.com/app.aspx, when the user visits http://myapp.com/app.aspx#/CustomerDetail, the second mapping will come into play and map to http://myapp.com/app.aspx#/Views/CustomerDetail.xaml. Also note the hashtag in both cases; the mapping only comes into play with that fragment.

This mapping XAML fragment sits inside the navigation:Frame element and provides the two mappings required for the URLs you'd normally use: no page and a specific page. Maps are read top-down and complete when the first match is hit. If you want to pass parameters to your page, you can get more complex and include support for query string values.

A common pattern in web applications is to pass parameters to a page using the query string. The query string is the set of delimited name/value pairs after the question mark in a URL. For example:

http://myapp.com/app.aspx?customer=1234

In this case, the query string would produce two name/value pairs: customer with a value of 27 and invoice with a value of 2506.

That works well for passing parameters to an actual HTML page, but how does it fit in with the hashtag approach used with Silverlight navigation? How do you pass parameters to internal Silverlight pages? In a Silverlight application, much as we've gotten used to elsewhere on the Web, you may want something a little friendlier:

http://myapp.com/app.aspx#/CustomerDetail/1234

In this case, when you have mapping set up, Silverlight will load the CustomerDetail page and pass in a parameter of 1234. How is that parameter passed in? It's entirely up to you and how you do the mapping. For example, let's say you want 1234 to map to a CustomerID query string variable. You provide a map that looks like this:

<uriMapper:UriMapping Uri="/CustomerDetail/{CustomerID}"
        MappedUri="/Views/CustomerDetail.xaml?CustomerID={CustomerID}" />

That map needs to appear near the top, preferably after the Home mapping, in order to be hit. Remember, the maps are evaluated top-down, and the first match is the only one that will be executed.

Retrieving the parameter from within the Page is super simple. The NavigationContext object on the property of the same name in the Page class includes a QueryString property that may be used to retrieve the parameters passed into the page. It's an IDictionary of strings, so no parsing is required; use the name/value pairs as they're provided:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
  if (NavigationContext.QueryString.ContainsKey("CustomerID"))
  {
    string id = NavigationContext.QueryString["CustomerID"];

    if (!string.IsNullOrWhiteSpace(id))
        LoadCustomerDetails(id);
  }
}

This example shows how easy it is to grab the ID from the query string passed into the page. Although I left them out for brevity here, you'll want to have all your query string key names in constants or an enum.

This approach enables you to provide meaningful deep links into data-oriented Silverlight applications, pulling up the appropriate records or other state. Back when I worked primarily with Windows Forms in the .NET 1 and 1.1 days, this was a feature many customers asked for: "How can I email a link to a specific page in the application?" We had all sorts of strange solutions involving custom URI schemes and more. I'm glad to see it's much simpler now.

When you have a data-oriented application, that typically means individual pages cause some sort of database transaction and web service call to run when you load them. The query string parameter may contain a record ID used to load some data. When the user is bouncing back and forth between pages in the application, you don't necessarily want to take a service or database hit on each page; that's where caching comes into play.

Normally, when you navigate to a page using the navigation framework, you'll get a new instance of that page. This includes times when you click the Back button to get to that page. In order for Silverlight to cache that page, you need to enable caching at the page level using the NavigationCacheMode property. Table 15.6 shows the three possible values for page caching.

The cache mode is specific to the URI in use. When using parameters, each unique URI, including the query string, results in a new cached page if caching is turned on. Given the way parameters usually affect the data on the page, this is a desirable effect. If you want to avoid this, you can cancel the navigation using code in the Navigating event or by overriding the OnNavigatingFrom function on the Page.

Typically, you'll set the page's cache mode in the constructor. Cached pages will still receive the navigation events, so you may do any page-loading work inside the OnNavigatedTo override.

The page cache is handled at the Frame level, so it makes sense for that to be the location of the cache settings.

The Frame instance is responsible for any caching of pages it loads. It uses a simple in-memory structure keyed by the URI of the page to be cached. By default, the size of this cache is set to 10 pages, but you can change that by setting the Frame.CacheSize property in either markup or code. Recall that this limit doesn't include pages that require cache, only pages that enable it.

Logically, the cache is a queue: new pages are added to one end, and old pages fall off the other. The cache itself is opaque; you don't have direct access to it and can't manually manipulate the pages contained within. If you need that level of cache control, you can consider creating your own custom INavigationContentLoader and bypassing the built-in cache.

Caching is a powerful way to improve the performance of your application. Using the built-in page cache takes the guesswork out of dealing with individual page instances in a navigation application.

So far, you've seen a number of pages being loaded (and cached) using straightforward URIs. Those pages all existed in the currently executing assembly. It's rare for an application of any complexity to have all of its user interface contained within the main assembly.

For the last topic of this section, we'll cover how to navigate to pages contained in other assemblies.

Regardless of the download mechanism, the navigation approach remains the same when you have the assembly available to Silverlight. Silverlight uses a specialized form of URI to reference the page. You may have seen this when loading resource files. For example, to get to CustomerList.xaml in a Views folder in the assembly CustomerModule, the URI looks like this:

/CustomerModule;component/Views/CustomerList.xaml

That says to load the CustomerModule component and look in the Views folder for a file named CustomerList.xaml. You could use this syntax as is, but it's much nicer to integrate it with the URI mapper. First, let's modify the project to include a new assembly with the CustomerList page so you can try this out.

To the existing solution, add a new Silverlight Class Library project named Customer-Module. In that project, create a new Views folder. In the Views folder, add a new Silverlight page named CustomerList.xaml. Feel free to remove the default Class1.cs class that came along for the ride.

The XAML for the CustomerList file is short:

<Grid x:Name="LayoutRoot">
    <TextBlock Text="Customer List Page from Assembly" />
</Grid>

The next step is to reference this assembly from the main Silverlight application. First, build the solution. Then, right-click the Silverlight app and choose Add Reference. From the Projects tab, select the newly added CustomerModule assembly.

At this point, you have everything needed for a page in a separate assembly, included in the main .xap file. The next step is to build the URI mapping rule.

Unless you have a specific pattern to the URIs in your external assemblies, you'll need to create individual mapping rules for them. This alone can be a good reason to group pages by a common name prefix (such as Customer) and partition them into assemblies based on those names.

In this case, you'll add a specific URI mapping as the first rule in the URI mapper in MainPage.xaml. The rule looks like this:

<uriMapper:UriMapping Uri="/CustomerList"
        MappedUri="/CustomerModule;component/Views/CustomerList.xaml" />

When the mapping is in place, all you have to do is add some navigation controls on-page.

Still in MainPage.xaml, locate the LinksBorder where you previously added the Customer menu item. Right under the CustomerDetailLink, add the following XAML:

<Rectangle Style="{StaticResource DividerStyle}" />

<HyperlinkButton x:Name="CustomerListLink"
                 Style="{StaticResource LinkStyle}"

                 NavigateUri="/CustomerList"
                 TargetName="ContentFrame"
                 Content="customer list" />

When you run the application and click the Customer List menu option, you'll see something like figure 15.7. With the mapped URI, the fact that the page isn't in the main assembly is completely transparent to the user. Not only is this generally a good practice, but it'll make any further refactoring easier, as you can keep the URIs the same regardless of which assembly the pages live in.

Navigation in Silverlight is based primarily around Pages, Frames, and URIs. Individual pages have unique URIs and are loaded by those URIs into frames in the application. Frames provide a location to host pages, as well as a common interface to the navigation facilities offered by the NavigationService class and services such as the URI mapper. Both frames and pages participate in caching to help improve application performance. Finally, pages can be loaded from resources inside the executing assembly, or from external assemblies resolved at compile time or runtime.

So far, everything you've done has been for in-browser applications, where you have the browser's navigation UI and history journal to rely on. Out-of-browser applications obviously can't take advantage of these things. Luckily, the Silverlight navigation framework has taken this scenario into consideration and provided everything you need to have proper out-of-browser navigation.

Figure 15.7. The navigation application with a customer list page loaded from an external assembly

The application needs, at a minimum, a Back button and a Forward button. For this, you'll use the metro theme (Windows Phone 7 and Zune) icons from http://metro.windowswiki.info/. From that set, drag both the back.png and next.png black icons into the project's Assets folder. When they're in place, modify MainPage.xaml to add the XAML in listing 15.3 right before the closing Grid tag at the bottom of the file.

Example 15.3. The Back and Forward buttons on MainPage.xaml

The XAML in listing 15.3 adds two buttons: a Back button and a Forward button. The style resource (resources are covered in chapter 23) creates a button that has no real appearance other than its content. When you run the application, the UI displays the two new buttons at upper left on the main page, as shown in figure 15.9.

Figure 15.9. The new navigation buttons appear at upper left in the user interface.

The new UI looks pretty good. With the buttons in place, you'll need to wire them up to the content frame to make navigation happen.

In the button-click event handlers for the two new navigation buttons, you'll place some code similar to what you wrote in listing 15.2 earlier in this chapter. This time, though, you'll use the Frame class directly rather than the NavigationService class. Listing 15.4 shows the code-behind for the MainPage.xaml page.

private void BackButton_Click(object sender, RoutedEventArgs e)
{
  if (ContentFrame.CanGoBack)

    ContentFrame.GoBack();
}

private void ForwardButton_Click(object sender, RoutedEventArgs e)
{
  if (ContentFrame.CanGoForward)
    ContentFrame.GoForward();
}

With this code in place, you can use either the browser buttons or the custom navigation buttons to move backward and forward through the journal. There's currently no visual cue indicating whether either navigation option is available, though. You can do this using binding, because the CanGoBack and CanGoForward properties of the Frame class are implemented as dependency properties. As you learned in chapter 11, you can use element binding to get to the properties on ContentFrame, as shown here:

<Button x:Name="BackButton"
        IsEnabled="{Binding CanGoBack, ElementName=ContentFrame}"
...
</Button>
<Button x:Name="ForwardButton"
        IsEnabled="{Binding CanGoForward, ElementName=ContentFrame}"
...
</Button>

With that in place, you'll see the Forward and Back buttons ghost out when the function isn't available. Note how the buttons are in sync with the browser navigation buttons. Now, let's try it without the browser.

The next step is to turn the application into an out-of-browser application. Chapter 5 covered out-of-browser applications in detail; if you haven't yet read that, you may wish to take a brief detour over there now.

Right-click the main application project, select Properties, and select the Enable Running Application Out of the Browser check box on the Silverlight tab. Next, on the Debug tab, select Out-of-browser Application as the start action. Finally, set the NavigationExample project as the startup project by right-clicking the project and selecting Set as Start-up Project.

With those steps complete, run the application. The result will look something like figure 15.10.

One other important option relates to custom navigation: controlling who owns the journal.

The Frame class includes a property named JournalOwnership. This property lets you decide who should own the history journal. In a top-level navigation frame in an in-browser application, the default is to let the browser own the journal. In an out-of-browser application, the default is to let the frame own the journal. Table 15.7 shows the three possible values of the JournalOwnership property.

Figure 15.10. The navigation application running out-of-browser, with custom navigation controls

Given the defaults, leaving journal ownership at the default value will be sufficient for most cases, including your out-of-browser application. For out-of-browser applications, it wouldn't hurt to set the journal ownership to OwnsJournal, but other than a short decision tree, you're not really saving any code.

There was a time when a series of dialogs could be considered the main user interface for a number of applications. Not any more. Pages are the main way you present content to users. But dialogs still have their place for presenting important information to the user, such as error messages or details, or for gathering discrete bits of information such as filenames.

In addition to the page-navigation approach you've seen so far, Silverlight has support for two discrete types of dialogs: in-application floating windows with simulated modality, and system dialogs.

A ChildWindow is typically displayed from code rather than included as an inline element in XAML. To facilitate this, the control has several members that handle showing, closing, reporting results, and allowing cancellation. Table 15.8 lists those members and their related functions.

The typical way to use a ChildWindow is to call the Open method from code and then to take some action based on the dialog result available during the Closed event. Listing 15.6 shows this process in more detail.

Example 15.6. Displaying a Childwindow and capturing the DialogResult

The example shows how to display a ChildWindow and handle the three possible DialogResult values set when the user closes the window. Note that this example also uses a lambda expression to create the event handler. This is a shortcut way to create a delegate inline in your code rather than create a separate event handler function. In this example, s is the variable that contains the sender, and ea is the variable that contains the event arguments. The code to display the window could also have been written like this:

ChildWindow dialog = new MyDialog();
dialog.Closed += new EventHandler(dialog_Closed);
dialog.Show();

Of course, in that instance, you'd need to create a separate function named dialog_Closed that had the event handler logic in it. Either way is valid.

Note also that you do a true/false/else check on the DialogResult value. This is because the DialogResult is a nullable boolean type, and it's not usually sufficient to check for true or false. Nullable booleans also don't allow you to write code like this:

if (dialog.DialogResult)     { ... }

You'll get a compile-time error unless you cast the value to a regular bool. For that reason, you check explicitly against true, false, and the null (default) value.

When you ran the code in listing 15.6, you probably noticed that the content behind the window was overlaid with a gray rectangle. The color and opacity of the overlay are a couple of the knobs you can tweak to customize the way the ChildWindow looks.

Like almost everything else in Silverlight, you can do some basic customization of a ChildWindow to change things such as background and overlay colors without messing around with the control template. Some of those properties specific to ChildWindow are listed in table 15.9.

The ChildWindow provides the capability to create any in-application dialog that you need. Two other types of dialogs are more operating system–specific in their display and use: the OpenFileDialog and the SaveFileDialog.

To give your users the opportunity to select a file or multiple files, you must instantiate an instance of the OpenFileDialog class from procedural code; you can't create an OpenFileDialog from XAML. After it's created, you can use several properties to customize the selection experience. These properties and their descriptions are provided in table 15.10.

As this table shows, you have flexibility in customizing the selection experience, but you don't have complete control over the dialog box. For instance, you can't dictate the appearance of the dialogs. Instead, the dialogs use the user's OS to determine the general look of the dialog box. By using the values in table 15.10, you can guide the selection experience, as shown in figure 15.12.

The following is the code to achieve this:

OpenFileDialog openFileDialog = new OpenFileDialog();
openFileDialog.Filter =
  "Text files (*.txt)|*.txt|Xml Files (*.xml)|*.xml";
bool? fileWasSelected = openFileDialog.ShowDialog();

This example shows an OpenFileDialog box that enables a user to select a text or XML file. You can accomplish this by appropriately setting the Filter property of the OpenFileDialog object. The dialog is then launched by calling the ShowDialog method. The code for a SaveFileDialog is similar. Unlike the ChildWindow-type dialog shown in the previous section, this method is a blocking call that prevents the execution of any additional code until the user exits the dialog. After the user exits the dialog, the ShowDialog method returns a nullable bool that signals the end of a user's interaction with the dialog. The code then continues executing, giving you the opportunity to retrieve and analyze the results.

Figure 15.12. Guiding the selection using filter properties

When a user exits the dialog, the ShowDialog method returns a nullable bool value. This value will be false if the user chose to close out of or cancel the dialog. If the user clicked the OK button, a true value will be returned. After the value is returned, you can access the file(s) that the user selected.

The file(s) selected within an OpenFileDialog are available through the File and Files properties. The SaveFileDialog, because it only supports a single file, has only the File property. These properties will be null if a user left the OpenFileDialog without clicking the OK button, so you should check the value returned from the ShowDialog method before attempting to retrieve the selected file(s). Here's an example:

bool? fileWasSelected = openFileDialog.ShowDialog();
if (fileWasSelected == true)
{
  FileInfo fileInfo = openFileDialog.File;
  StreamReader reader = fileInfo.OpenText();
}

From this example, you can see that after a user opens the dialog box, you can get the selected file through the File property. If the Multiselect property had been set to true, the Files property would have been more applicable. Either way, if a user hadn't selected a file, both those property values would have been null. If a file or multiple files had been selected, you could have retrieved the details of each file through the FileInfo object.

The SaveFileDialog, because it only supports a single file, has a helper method to use for opening the file. The code for a SaveFileDialog looks like this:

bool? fileWasSelected = saveFileDialog.ShowDialog();
if (fileWasSelected == true)
{
  Stream stream = saveFileDialog.OpenFile();
}

If you wish to retrieve the name of the file entered or selected by the user, use the SaveFieldDialog.SafeFileName string property.

The FileInfo class provides a special bridge from the local filesystem to the security sandbox in which Silverlight runs. This class is specifically designed for use with the OpenFileDialog and SaveFileDialog. This object provides two methods that allow you to read the contents of a file—OpenRead and OpenText-and one method that may be used in the case of the SaveFileDialog to write to the file-OpenWrite.

The OpenRead method is designed to handle binary file scenarios. This method returns a read-only System.IO.Stream object, which is well-suited for handling bytes of information. Similarly, the OpenWrite method returns a write-only stream, but only if called on a FileInfo object returned from the SaveFileDialog. Alternatively, the OpenText method is better suited for reading text-related files. This method returns a basic System.IO.StreamReader, as shown here:

FileInfo fileInfo = openFileDialog.File;
StreamReader reader = fileInfo.OpenText();
myTextBlock.Text = reader.ReadToEnd();

As this example shows, working with a text file in Silverlight is incredibly trivial. It's just as easy to work with a binary file. The key to either approach is to understand working with streams of data. This topic is a general concept in .NET development that's beyond the scope of this book.

The OpenFileDialog provides a way to ask a user for a file to open. The SaveFileDialog provides a way to ask for a filename for saving a file. The Popup element and ChildWindow control provide another way to prompt your users. These options help Silverlight deliver a richer experience than you can easily get with HTML. In addition, other controls that haven't been covered also help provide a rich experience.