Part 18 Navigating Between Pages [AbsoluteBeginnersSeriesForWindowsPhone8_files]

When someone clicks the microphone icon in our app bar, we want to take them to a

new page where we can allow them to record a custom sound. To do this, we need to

create a second page in our app, and then navigate from the MainPage.xaml to that

new page. Navigation in Windows Phone Apps is similar to navigating from one web

page to another. In this lesson, we'll learn about the Navigation API and, even though

our needs are simple in this particular app, we'll find out the Navigation API capabilities

with regards to how the Windows Phone 8 operating system re-hydrates apps shut

down due to memory constraints.

Our game plan in this lesson ...

1.  Revisit the Databound Project template to observe how it navigated from the main page to the details page.

2.  Discuss the classes required for navigation in the Windows Phone 8 API.

3.  Implement the code necessary to navigate from our main page to a new page that we'l use to record a custom sound. 

1. Revisiting the Databound Project template to learn about navigation

If you'll recall a few lessons ago when we looked at the Databound Project Template,

we saw how tapping one of the list items ...

... navigates to another page containing more details about the given item:

In addition to the MainPage.xaml, the project template also has a second page called

DetailsPage.xaml:

In the MainPage.xaml.cs file, in the MainLongListSelector_SelectionChanged event

handler method, we see the code required to enable this. Focus on lines 47-50:

The NavigationService class is used to simply navigate from one XAML page to

another. However, it has a larger role in more complex scenarios. Since it is solely

responsible for navigation between XAML pages, it also allows you to inspect the

navigation history (called the "back stack"), remove entries from the back stack, and

then observe the effect that these changes have on the navigation through the app.

To learn about some of the advanced functionality of the NavigationService() class,

check out this article on MSDN:

http://msdn.microsoft.com/en-

us/library/windowsphone/develop/hh394012(v=vs.105).aspx

However in our case, we merely need to navigate from the MainPage.xaml to a new

page. We don't need to worry about alternate back page scenarios, passing values

between the pages, or the like. Therefore, this other article on MSDN describes the

process we'll use in general terms, in case you want to do a little additional research:

http://msdn.microsoft.com/en-

us/library/windowsphone/develop/ff626521(v=vs.105).aspx

Most of the simple navigation scenario is accomplished using the the Navigate() method in the code example.

Notice the Uri that is used as an input parameter to the Navigate() method. The Uri

object represents a Uniform Resource Indicator, similar to a URL but has more utility

and as more far reaching. The Uri has two basic parts—a string that represents a

location, and a UriKind that should be used to interpret the location string.

Let's start by parsing through the string ... you'll notice that it is part string literal, part

dynamic value that retrieves its value from the current selected item in the

LongListSelector. They are appended together with the plus + operator:

"/DetailsPage.xaml?selectedItem=" + MainLongListSelector.SelectedItem as

ItemViewModel).ID

The first part of the literal string should be obvious—it is the XAML page we want to

navigate to. Everything after that—i.e., after the question mark ? character—is a query

string. You've undoubtedly seen a query string before, even if you didn't know what it

was called. A query string is a means of sending additional information along with the

intended page to be loaded. I said you've undoubtedly seen this before because it is

one of two or three primary ways of sending additional data between stateless web

pages and is used ubiquitously on the World Wide Web.

If you look at a search for the name "Clint Rutkas" on Bing.com, the navigation bar in

your web browser will look like this:

http://www.bing.com/search?q=clint+rutkas&go=&qs=n&form=QBLH&pq=clint+rutkas&s

c=8-9&sp=-1&sk=  

It's simply a clever way of passing information from one web page that's intended to be

interpreted and processed by another web page.

In the code example we're examining, when someone taps an item in the

LongListSelector we want to send the ID for the item that was selected from the

MainPage.xaml to the DetailsPage.xaml ... the ? separates the page name from the

query string portion of the URL. The query string is in the form of a name / value pair.

For example:

selectedItem=3

... the selectedItem is the name of the pair, and everything after the equals character is

the value of the pair.

Two name / value pairs are separated by an & ampersand character. We'll see this

used later in this series to send geo-positional latitude and longitude from one page to

another ... it will look like this:

?latitude=41.8986&longitude= 87.6230

This is how you are able to pass multiple values in one string. Clever.

The second constructor argument for the new Uri takes an enumeration of type UriKind.

There are three possible values:

·      UriKind.Relative 

·      UriKind.Absolute 

·      UriKind.RelativeOrAbsolute

In regards to the differences between the first two, check out this page:

http://msdn.microsoft.com/en-us/library/system.urikind(v=vs.95).aspx

... which says the following:

"Absolute URIs are characterized by a complete reference to the resource (example:

http://www.contoso.com/index.html), while a relative Uri depends on a previously

defined base URI (example: /index.html)."

In our case, a relative Uri would be "relative to the project's structure". When we prefix

the UriString with a forward-slash character / we're specifying the root of the project's

deployment package. That should correspond with what we see in the Solution Explorer

... the DetailsPage.xaml is in the root of the project folder. When the project is deployed,

those two .xaml files will both be in the root of the package like we saw when we

opened up the PetSounds.xap file as a zipped file.

But what about the UriKind.RelativeOrAbsolute? That's a bit trickier. The best I can

figure out is that we're simply asking the runtime to figure it out for itself. It will attempt to

clean up the UriString we provide and figure out where resources are. I think we could

switch that to UriKind.Relative and it would work, too.

Once the NavigationService loads the new page, the DetailsPage.xaml, an event called

OnNavigatedTo() fires. Notice its code:

In line 31, the NavigationContext.QueryString.TryGetValue("selectedItem") will retrieve

the value of the name / value pair in the query string as an out parameter if the

parameter name exists. Next, that selectedItem value is used to load the correct item

from the data model, and set it as the DataContext for the DetailsPage.xaml so that the

various TextBlock controls can bind to it (line 35).

Now that we have seen a full-fledged navigation example at work, we're better prepared

to tackle this in our own project.

2. Create the RecordAudio.xaml Page

Let's begin by creating that new page we want to navigate to:

1.  Make sure you're in the C# file templates section 

2.  Select "Windows Phone Portrait Page" 

3.  Rename to: RecordAudio.xaml 

4.  Click the Add button

Back in the MainPage.xaml page, we'll revisit the event handler method stub we created several lessons ago called RecordAudioClick():

3. Implement the code to navigate to the new page

I'll replace the exception (intended to be a reminder) with the following line of code:

Hopefully, this version will be dramatically simplified when compared to the hairy

example we saw earlier. We create a new Uri object with a simple address to our new

RecordAudio.xaml page, and use the UriKind.RelativeOrAbsolute enum value.

Now, let's test that line of code by running the app and clicking the microphone icon in

the app bar:

... if all goes well, we should see a default page template like so:

Great! We'll need to revisit this notion later in this series of lessons with a slightly more

complex example in which we pass data between the pages. 

Recap

To recap, the big take away from this lesson is how to navigate between XAML pages

using the NavigationService. We learned what a Uri object is, how to specify a page

location and even pass parameters between pages, what the UriKind enumeration

options mean, and so on.

Part 17 Introducing the Coding4Fun Toolkit [AbsoluteBeginnersSeriesForWindowsPhone8_files]

Source Code:  http://aka.ms/absbeginnerdevwp8

Recording a custom sound in our app would be difficult to code by hand. Fortunately,

your friends at Coding4Fun, and Clint Rutkas specifically, have created a Toolkit for

Windows Phone that hides the complexity behind easy to use programmatic interfaces.

If you're not familiar with Coding4Fun, it's a Channel9 site that engages in geeky cool

projects, not your standard business apps ... they usually use hardware like the Kinect

as the interface for controlling things such as boxing robots and even a Ford Mustang

that was heavily modified with Microsoft technology ... just to prove that it could be

done.

http://channel9.msdn.com/coding4fun

Clint is usually in the center of these projects and he is the author and curator of the

Coding4Fun Toolkit.

By using this package in our project, we get some additional tools we can utilize in our

apps such as a little "About This App" message box (the AboutPrompt) suited for

Windows Phone development. In this lesson, I'll demonstrate how to install the

Coding4Fun Toolkit package into our app using NuGet. Once we install it, we'll use it to

implement the AboutPrompt.

In this short lesson, our game plan is to:

1.  Use NuGet to install the Coding4Fun Toolkit package into our solution. 

2.  Snoop around and see what it added. 

3.  Add an AboutPrompt to our app.

Update to series: Being sure we have the newest version of NuGet.

With a fresh install of Visual Studio 2012, we’ll need to update NuGet to get some of the

newer packages such as the Coding4Fun Toolkit.  It is a super easy process and can

be done in a few clicks.

1.  Go to the Tools Menu –> Extensions and Updates

2.  Go to the Update Tab –> Visual Studio Gallery

3.  Click Update

4.  Restart Visual Studio

1. Install the Coding4Fun Package

There are many ways to get to the NuGet package manager ... this time we'll right-click

on the References folder and select "Manage NuGet Packages ...":

This will open up the Manage NuGet Packages Dialog:

1.  In the Search box, search for: "Coding4Fun". 

2.  Click the Install button next to the "Coding4Fun Toolkit - Complete" package ... Clint split up the Coding4Fun toolkit into sub-packages so that developers can just pick and choose the parts they want in their project. However, for simplicity—and because we'l use a few different parts and want to familiarize ourselves with the package, we'l  choose to install the Complete version.

After a few moments, you'll see green checkmarks next to the packages that were

installed:

... and you can click the Close button that in dialog to close it.

Now, in the Solution Explorer, you can see new References that were added:

... also, a new folder called Toolkit.Content and a ReadMe.Coding4Fun.Toolkit.txt file

were added:

Opening the ReadMe.Coding4Fun.Toolkit.txt file, we can see versioning information

(what changed) and migration notes:

2. Employing the AboutPrompt

We'll take the simple step of adding an AboutPrompt to the app. When the user selects

the "About" menu option, we want to display a popup:

We're missing a using statement, so use the hover-over-the-blue-dash-technique to add

the appropriate using statement to the code file:

Once we've resolved the reference to the AboutPrompt class, we'll call it's Show()

method. There are many overloaded versions of this method, but we'll pass in the

following information ...

... which produces the following results:

It's quick and simple and for this particular app, we probably need nothing more fancy.

Leveraging open source (or even commercial) packages is a great way to add features

quickly to your development projects. The whole .NET community on CodePlex is built

on sharing packages, components, templates and so on to help each other quickly

implement features. You can save yourself a lot of time during your career by spending

a few hours exploring the work of others before going off and writing your own.

Alternatively, use the search box on the NuGet Package Manager to find similar

packages and evaluate the strengths and weaknesses of each one relative to the needs of your project.

Recap

To recap, in this lesson we leveraged the Coding4Fun Toolkit to add one small feature

now as well as one large feature later in this series. We learned how to add packages to

our app using the NuGet Package Manager dialog, how to read the description of the

package to learn more, and how packages can be subdivided to minimize unnecessary

references and complexity in our projects.

Part 16 Working with the pplication Bar [AbsoluteBeginnersSeriesForWindowsPhone8_files]

Source Code:  http://aka.ms/absbeginnerdevwp8

Our app works great as a simple SoundBoard, but we want to push the envelop and

enable custom sounds—sounds that the user can record and re-use. This will require a

few changes to our app ... in this lesson, we'll add an Application Bar with a Record

button. When the user clicks it, we'll navigate the user to a new XAML page where they

can record new custom sounds.

You've probably seen an application bar before, even if you didn't realize what it's name

was. Application bars appear at the bottom of the viewable area for your app and can

contain a number of icons as well as an ellipsis which, when tapped, reveals text below

the icon, and possibly a menu of additional options. We'll see it at work before the end

of this lesson.

Here's our game plan for this lesson:

1.  The project template already creates some boiler plate code for an application bar. We'l un-comment out their code and revise it to display an application bar with a record button and a menu option. 

2.  We'l  work with the AppResources.resx so that the text on our new application bar can be localized in the future. 

3.  We'l  clean up some unused files ... the old data model should go. 

4.  We'l  wire up and create event handler method stubs for the application bar button and menu option. In subsequent lessons, we'l  flesh out the functionality in the event handler methods. 

1. Enable the boilerplate BuildLocalizedApplicationBar() method

In the MainPage.xaml.cs, the MainPage() constructor has a commented out line of code

calling the BuildLocalizedApplicationBar(). I'll un-comment that line of code out:

... and then un-comment out the actual method further down on the code page:

By un-commenting out these lines of code, we've added a simple application bar to our

app.

2. Modifying our Application Bar Button and Text

Obviously, we'll want to change the image that is referenced in line 67 (above) to

reference the microphone.png file in the Assets\AppBar folder:

So, I'll make this change:

... and I'll run the app. This reveals the app bar with the microphone icon and the ellipsis

which, when tapped, reveals a menu option titled "Menu Option":

Below the microphone icon, the word "add" appears. Let's change both of these. 

First, the title of our method, "BuildLocalizedApplicationBar", suggests that this

Application Bar retrieves it's textual values from the AppResources.resx, so let's open

that file:

... and make the following changes:

1.  I add a property named AppBarAbout and set its value to About 

2.  I add a property named AppBarRecord and set its value to Record 

3.  I add a property to AppBarSave and set its value to Save

Also, I remove any properties I no longer need, including:

·      AppBarButtonText 

·      AppBarMenuItemText 

·      SampleProperty

... and I save this file.

Next, I'll need to re-write some of the BuildLocalizedApplicationBar() to utilize the

settings added in the AppResources.resx file:

1.  I re-write the creation of the "Record" button 

2.  I re-write the creation of the "About" menu option 

3.  I add them both to the Application Bar

3. Removing the old data model

When I attempt to run the app, I see that I may have been too hasty in deleting the

"SampleProperty" from the AppResources.resx:

I find that the source of the problem is code that I don't even use anymore ... i.e., the

OLD data model code:

I can kill two birds with one stone by deleting the old data model classes. I select

ItemViewModel.cs and MainViewModel.cs, right-click, select Delete from the context

menu. That cleans up the code base removing unnecessary code and removes the

errant reference to the nonexistent entry in the AppResources.resx:

One of my favorite authors says that you stay organized to stay productive. Keep your

work area clean, like a sushi chef. Though I comment out code I don't think I'll need

anymore, I also want to comb through the code once a day to keep the codebase

pristine. When I open someone else's code and I look at it, I automatically assume it's

all being used. Sometimes, however, there are classes or methods no longer called.

This adds friction and confusion. When I'm not recording videos and actually writing

code, I rely on a third-party tool called ReSharper ... it will analyze your code and find

unused classes and methods, it can locate duplicate code and recommend changes

and a thousand other improvements to your code. I highly recommend it.

At any rate, when we run the app this time we can see that the app bar looks has the

text we would expect:

4. Responding to the Click event of the App Bar's Record button

Finally in this lesson, we want to wire up the click event handler methods to our new

button and menu items:

I add line 69 which, as we learned in the lesson on Events, will add the

RecordAudioClick method in its list of methods that will be triggered by the click event of the Record button. To create a method stub, use the technique we learned in the Event lesson—hover your mouse cursor over the blue dash under the letter R in

RecordAudioClick to reveal a menu, and choose the "Generate method stub ..." menu

option:

This will create a method stub for the event handler, complete with a reminder that the

method is not yet implemented by throwing an exception:

We'll repeat this process for the "about" menu option. In line 75 (below) I associate a

method event handler called AboutClick to the click event of the menu option:

... and I use the technique described earlier to create a method stub for

RecordAudioClick() (lines 86 through 89). 

Recap

To recap, the big take away is how to create a new application bar, application bar icon, and application bar menu option. We used templated code and the AppResources.resx and wired up event handler method stubs, which we'll fully implement out in the coming lessons.