The Basics

The ApplicationBar, ApplicationBarIconButton, and ApplicationBarMenuItem classes are actually system components with which our application is interoperating. ApplicationBarIconButton and ApplicationBarMenuItem also don’t support the ICommand. Normally you would just use an attached behavior on the Click event to execute a command but since the button and menu item doesn’t inherit from FrameworkElement behaviors aren’t going to work either.

The ApplicationBar is exposed as a property of the PhoneApplicationPage and the creation and population of it is easily accomplished in either XAML or code. The ApplicationBar exposes several properties that we may want to configure at runtime. Table 2-2 lists the properties of the ApplicationBar.

Create a new Windows Phone 8 application and call it ApplicationBarButtonMenu. Open the MainPage.xaml.cs file and add the code from Listing 2-1.

Listing 2-1. Defining an ApplicationBar in Code

// add this line right after the call to InitializeComponet()
// in the MainPage constructor
BuildApplicationBar();
 
private void BuildApplicationBar()
{
    ApplicationBar = new ApplicationBar();
 
    ApplicationBarIconButton appBarButton =
            new ApplicationBarIconButton(new Uri("/Assets/like.png", UriKind.Relative));
             
    appBarButton.Text = "like";
    ApplicationBar.Buttons.Add(appBarButton);
 
    appBarButton = new ApplicationBarIconButton(new Uri("/Assets/save.png", UriKind.Relative));
    appBarButton.Text = "save";
    ApplicationBar.Buttons.Add(appBarButton);
 
    // Create a new menu item with the localized string from AppResources.
    ApplicationBarMenuItem appBarMenuItem = new ApplicationBarMenuItem("advanced options");
    ApplicationBar.MenuItems.Add(appBarMenuItem);
 
}
 
void AdvancedOptionsClick(object sender, EventArgs e)
{
    MessageBox.Show("Advanced Options Clicked");
}

Comment out the call to BuildApplicationBar() in the MainPage constructor. Open MainPage.xaml in the editor and then add the XAML in Listing 2-2 to the area just above the layout grid.

Listing 2-2. Defining an ApplicationBar in XAML

<phone:PhoneApplicationPage.ApplicationBar>
        <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
            <shell:ApplicationBar.MenuItems>
                <shell:ApplicationBarMenuItem Click="AdvancedOptionsClick" Text="advanced options"/>
            </shell:ApplicationBar.MenuItems>
            <shell:ApplicationBarIconButton IconUri="/Assets/like.png " Text="like"/>
            <shell:ApplicationBarIconButton IconUri="/Assets/save.png" Text="save"/>
        </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>
 
<!--LayoutRoot is the root grid where all page content is placed-->
    <Grid x:Name="LayoutRoot" Background="Transparent">
    ...

View Model and Data-Binding Support

Ideally that logic that manages these property values would be encapsulated in a view model. Fortunately, the PhoneApplicationPage ultimately inherits from DependencyObject, which means we can create our own dependency properties. We can then bind these properties to properties of our view model, and in the PropertyChanged event we can update the corresponding property of our ApplicationBar.

We’ll work through adding functionality to enable us to control the IsMenuEnabled property from the view model. You can then copy the pattern to extend it to the other properties. You could also extend this technique to control properties of the buttons and menu items. I will leave it as an exercise for the reader.²

The first thing we need to do is create a view model for our page. Add a new folder to your project and name it ViewModels.

Add a new class to the ViewModels folder and name the class MainPageViewModel. Your view model class will need to implement support for property change notification. This is probably best defined in a base class that can be reused for all ViewModels. Add an IsApplicationBarVisible property to the view model. See Listing 2-3.

Listing 2-3. The MainPageViewModel Class

internal class MainPageViewModel : ViewModel
{
 
    // we'll use this to flip the visibility
    // one per second for demo purposes
    private DispatcherTimer timer;
 
    public MainPageViewModel()
    {
        timer = new DispatcherTimer();
        timer.Interval = new TimeSpan(0, 0, 1); // one second
        timer.Tick += (s, e) =>
        {
            IsApplicationBarVisible = !IsApplicationBarVisible;
        };
 
        timer.Start();
    }
 
    // default to visible...
    private bool isApplicationBarVisible = true;
    public bool IsApplicationBarVisible
    {
        get
        {
            return isApplicationBarVisible;
        }
        set
        {
            isApplicationBarVisible = value;
            RaisePropertyChanged();
        }
    }
 
}

Open up the MainPage.xaml.cs file and add the code is Listing 2-4 to setup a Model property that will delegate to the DataContext of the page. This allows us to access the view model in a strongly typed manner without having to cast it every time we need it.

Listing 2-4. Adding a Model Property to Our Page

// add this line in the constructor after the call
// to InitializeComponent()
Model = new MainPageViewModel;
 
private MainPageViewModel Model
{
    get
    {
        return (MainPageViewModel)DataContext;
    }
    set
    {
        DataContext = value;
    }
}

Now that we have a view model with a property of interest to our page, we need to implement a way to have the view respond to changes in that property without the view model “knowing” anything about the view. This is where dependency properties come in.

Add a DependencyProperty of type System.Boolean to the MainPage. Open the MainPage.xaml.cs file and add the code from Listing 2-5 to the code-behind.

Listing 2-5. Declaring a DependencyProperty

public static readonly DependencyProperty IsApplicationBarMenuEnabledProperty =
        DependencyProperty.Register("IsApplicationBarMenuEnabled",
                typeof(bool),
                typeof(MainPage),
                new PropertyMetadata(true, OnIsApplicationBarEnabledChanged));
 
private static void OnIsApplicationBarEnabledChanged(DependencyObject d,
        DependencyPropertyChangedEventArgs e)
{
    ((MainPage)(d)).OnIsApplicationBarEnabledChanged((bool)e.OldValue, (bool)e.NewValue);
}
 
private void OnIsApplicationBarEnabledChanged(bool oldValue, bool newValue)
{
    ApplicationBar.IsMenuEnabled = newValue;
}
 
public bool IsApplicationBarMenuEnabled
{
    // IMPORTANT: To maintain parity between setting a property in XAML
    // and procedural code, do not touch the getter and setter inside this dependency property!
    get
    {
        return (bool)GetValue(IsApplicationBarMenuEnabledProperty);
    }
    set
    {
        SetValue(IsApplicationBarMenuEnabledProperty, value);
    }
}

Make note of the static OnIsApplicationBarEnabledChanged method. Whenever a dependency property’s value changes, the property changed callback method that was declared with the PropertyMetaData is invoked, and the instance of the object whose property has changed is passed in as the first parameter. We simply cast the object to the correct type and then invoke the instance OnIsApplicationBarEnabledChanged method, passing it the old and new values extracted from the DependencyPropertyChangedEventArgs parameter. It is in this instance method that we can now simply set the IsMenuEnabled property of the ApplicationBar.

The only thing left for us to do now is to bind our new dependency property to the corresponding property of the view model. The code in Listing 2-6 demonstrates the creation of a data binding in code. Add it to the constructor of the MainPage.xaml.cs file.

Listing 2-6. Creating a Data Binding in Code

// Add this code right after the previous code
Binding menuEnabledBinding = new Binding("IsMenuEnabled");
SetBinding(IsApplicationBarMenuEnabledProperty, menuEnabledBinding);

Run the application and you should see that the visibility of the ApplicationBar changes at 1-second intervals.

Using Commands

Normally when working with buttons you would bind the Command property of the button to the ICommand exposed on your view model. Since ApplicationBarIconButton and ApplicationBarMenuItem do not expose a Command property that option isn’t available to us. The next option would be to use a Blend Attached Behavior to hook the Click event of the control but again we are blocked because ApplicationBarIconButton and ApplicationBarMenuItem don’t inherit from FrameworkElement. We’re going to have to use some code-behind but only just enough to get the job done.

The first thing we’ll need is an implementation of the ICommand interface to work with. Listing 2-7 shows a sample implementation of the interface.

Listing 2-7. A Sample Implementation of the ICommand Interface

public class RelayCommand : ICommand
{
    readonly Action<object> execute;
    readonly Predicate<object> canExecute;
 
    public RelayCommand(Action<object> execute) : this(execute, null)
    {
    }
    public RelayCommand(Action<object> execute, Predicate<object> canExecute)
    {
        if (execute == null)
            throw new ArgumentNullException("execute");
        this.execute = execute;
        this.canExecute = canExecute;
    }
    [DebuggerStepThrough]
    public bool CanExecute(object parameter)
    {
        return canExecute == null ? true : canExecute(parameter);
    }
    public void Execute(object parameter)
    {
        execute(parameter);
    }
 
    public event EventHandler CanExecuteChanged = delegate
    {
    };
 
    public void RaiseCanExecuteChanged()
    {
        CanExecuteChanged(this, EventArgs.Empty);
 
    }
}

We’ll create a command that executes when someone taps on the advanced options menu item. Add the code in Listing 2-8 to setup a command and the supporting methods in the MainPageViewModel.

Listing 2-8. Code for the Advanced Options Menu Item Command

// add the following line to the end of the MainPageViewModel
// constructor to initialize the command
AdvancedOptionsCommand =
        new RelayCommand(AdvancedOptionsCommandExecute,
                AdvancedOptionsCommandCanExecute);
 
private RelayCommand advancedOptionsCommand;
public RelayCommand AdvancedOptionsCommand
{
    get
    {
        return advancedOptionsCommand;
    }
    set
    {
        advancedOptionsCommand = value;
        RaisePropertyChanged();
    }
}
 
private bool AdvancedOptionsCommandCanExecute(object parameter)
{
    return true;
 
}
 
private void AdvancedOptionsCommandExecute(object parameter)
{
    // of course, in real life, you would never use
    // a MessageBox in your view model but it's ok
    // for our purposes here...
    MessageBox.Show("Advanced Options selected.");
 
}

The last thing to do is modify the Click event handler we added to the code-behind of the MainPage in Listing 2-1 so that it calls the CanExecute and Execute methods on the AdvancedOptionsCommand property of the Model. Listing 2-9 shows the new Click handler code. Oh, and you’ll also want to comment out the timer code in the MainPageViewModel constructor or you won’t be able to see the menu item long enough to be able to click on it.

Listing 2-9. Executing the Command from Code-Behind

void AdvancedOptionsClick(object sender, EventArgs e)
{
    if(Model.AdvancedOptionsCommand.CanExecute(null)
    {
        Model.AdvancedOptionsCommand.Execute(null);
    }
}

By using this approach we still have code that is easy to test, and our view and view model are still loosely coupled.

Basic Navigation

Open Visual Studio and create a new Windows Phone App and name it BasicNavigation. Open MainPage.xaml in the editor and locate the ContentPanel grid and add a StackPanel to it. Add a Button to the StackPanel and set its Content property to “Settings.” Add a second button and set its Content property to “About.” Double-click the “Settings” button in the designer to add an event handler to the button’s Click event. Do the same for the “About” button. Your ContentPanel for MainPage.xaml should look like Listing 2-10.

Listing 2-10. XAML for the ContentPanel in MainPage.xaml

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <StackPanel>
         <Button Content="Settings" Click="Button_Click_1"/>
         <Button Content="About" Click="Button_Click_2"/>
    </StackPanel>
</Grid>

Right-click on the BasicNavigation project and add a new Windows Phone Portrait Page and name it “About.” Add a second page and name this one “Settings.” Find the TextBlock elements in the TitlePanel section and give each page an appropriate name so you can distinguish between them when testing.

Listing 2-11. Example TitlePanel XAML for the Settings and About Pages

<StackPanel Grid.Row="0" Margin="12,17,0,28">
     <TextBlock Text="Widnows Phone 8 Recipes" Style="{StaticResource PhoneTextNormalStyle}"/>
     <TextBlock Text="about" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
</StackPanel>
 
<StackPanel Grid.Row="0" Margin="12,17,0,28">
     <TextBlock Text="Widnows Phone 8 Recipes" Style="{StaticResource PhoneTextNormalStyle}"/>
     <TextBlock Text="settings" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
</StackPanel>

The PhoneApplicationPage class exposes a read-only NavigationService property that is populated by the system with the NavigationService used to navigate to the current page. You pass a Uri to the Navigate method and the NavigationService takes care of instantiating and displaying an instance of the target page. Navigation is only supported to relative URIs that are fragments, or begin with ’/’, or which contain “;component/.” Listing 2-12 shows the code for the Settings button Click event handler. Use this example to add code for the About button that will navigate you to the About.xaml page.

Listing 2-12. Using the NavigationService to navigate to the Settings page

NavigationService.Navigate(new Uri("/Settings.xaml", UriKind.Relative));

Navigation Events

There are three main events in the lifecycle of a page navigation. You can access these events by overriding their corresponding virtual methods listed in Table 2-3. These events together allow you to do things such as load or save data, cancel the navigation, or preconfigure the UI.

Let’s add some code to our project that will exercise each of these methods. Open the AboutPage.xaml file in the editor and add a StackPanel containing a TextBlock and a CheckBox to the ContentPanel. Set the properties of the controls as shown in Listing 2-13.

Listing 2-13. CheckBox in the ContentPanel of AboutPage.xaml

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <StackPanel>
         <TextBlock
             HorizontalAlignment="Left"
             TextWrapping="Wrap"
             VerticalAlignment="Top"
             x:Name="instructionTextBlock"/>
         <CheckBox
             Content="I agree"
             HorizontalAlignment="Left"
             Margin="10,10,0,0"
             VerticalAlignment="Top"
             x:Name="confirmationCheckBox"/>
    </StackPanel>
</Grid>

Now we’ll override the OnNavigatedTo and OnNavigatingFrom methods. We’ll set the Text of the instructionsTextBlock in when we navigate to the page. When we are navigating away from the page, we’ll check to be sure that the user has checked the confirmationCheckBox and cancel the navigation if they haven’t. Before cancelling navigation, however, we need to ascertain whether or not the system will ignore the Cancel property of the NavigatingCancelEventArgs Add the code in Listing 2-14 to the code-behind in About.xaml.cs.

Listing 2-14. Code for OnNavigatedTo and OnNavigatingFrom

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    instructionTextBlock.Text = "Please check below to indicate you have seen this screen.";
}
 
protected override void OnNavigatingFrom(NavigatingCancelEventArgs e)
{
    if (!confirmationCheckBox.IsChecked ?? false)
    {
        if(e.IsCancelable)
        {
            MessageBox.Show("You must check the confirmation check box to proceed");
            e.Cancel = true;
        }
    }
}

The IsCancelable property will return false whenever the navigation destination is an external location. This includes other applications, launchers, and choosers. It will also return false if this is a backward navigation that is going to exit the application. You can always cancel backwards navigation no matter what by overriding the OnBackKeyPress method of the PhoneApplicationPage. This method is called when the hardware back button is pressed.

Passing Information

There are two main methods of passing information between pages during navigation. You can add one or more query parameters to the Uri that you pass to the NavigationService.Navigate method. You could pass an item identifier to a details page, for instance. The other option is to add a fragment to the Uri. The fragment is simply any text value added after the resource name and prefixed with a hash tag. Fragments are commonly used to indicate how the destination page should be displayed. Let’s modify our basic navigation application to demonstrate these techniques.

Fragments

To demonstrate a common use of a fragment we modify the About page to contain a Pivot control and use the fragment to control which PivotItem is displayed when we navigate to the page.

Open About.xaml in the editor and replace the entire contents of the LayoutRoot Grid with the XAML in Listing 2-15. Add an override of the OnFragmentNavigation method using the code from Listing 2-16. You’ll also want to modify the code in MainPage.xaml.cs and add “#contact” to the end of the Uri as shown in Listing 2-17.

Listing 2-15. XAML for the Modified About Page

<!--Pivot Control-->
<phone:Pivot x:Name=”aboutPivot” Title="WINDOWS PHONE 8 RECIPES">
    <!--Pivot item one-->
    <phone:PivotItem Header="privacy">
        <Grid/>
    </phone:PivotItem>
 
    <!--Pivot item two-->
    <phone:PivotItem Header="contact">
        <Grid/>
    </phone:PivotItem>
</phone:Pivot>

Listing 2-16. OnFragmentNavigation Override for About.xaml.cs

protected override void OnFragmentNavigation(FragmentNavigationEventArgs e)
{
    string frag = e.Fragment;
 
    switch (frag)
    {
        case "privacy":
 
            break;
        case "contact":
            aboutPivot.SelectedIndex = 1;
            break;
 
    }
}

Listing 2-17. Using the NavigationService to navigate to the About page

NavigationService.Navigate(new Uri("/About.xaml#contact", UriKind.Relative));

You’ll notice that the fragment has been conveniently parsed for us and is contained in the Fragment property of the FragmentNavigationEventArgs instance that is passed into the method. We just need to examine the fragment value and take the appropriate action. In this example, I’ve used it to automatically set the selected item of the Pivot control to the contact PivotItem.

QueryString Parameters

It is quite common to have a page with a list of items on it and be able to tap an item and navigate to an item details page. We need some method to tell the destination page which item we want to display. QueryString parameters are just the thing we need to accomplish this. Open up Visual Studio and create a new Windows Phone Databound App and name it MasterDetailNavigation. This template project is a good example of a master-detail navigation and also comes with sample data so this will save us a bunch of typing and let us get right into the details. This will also introduce you to the concept of an “Anchor” view model, which is a common pattern in Windows Phone 8 applications.

Take a look at the code in App.xaml.cs and notice that the App class exposes a static property of type MainViewModel that serves as the “Anchor.” The fact that the lifetime of this anchor view model is tied to the application’s lifetime and not to that of any particular page greatly simplifies our code. Data persistence, for example, can be handled centrally. A Windows Phone 8 application behaves more like a web application than a traditional, stateful desktop application. The lifetime of each PhoneApplicationPage is uncertain at best, and even the order in which pages are created can change depending on how they are navigated and whether the application is coming back from being tombstoned or not.

Open the MainPage.xaml.cs file and locate the MainLongListSelector_SelectionChanged method or look at Listing 2-18.

Listing 2-18. The MainLongListSelector_SelectionChanged Event Handler Method

private void MainLongListSelector_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    // If selected item is null (no selection) do nothing
    if (MainLongListSelector.SelectedItem == null)
        return;
 
    // Navigate to the new page
    NavigationService.Navigate(new Uri("/DetailsPage.xaml?selectedItem=" +
                      (MainLongListSelector.SelectedItem as ItemViewModel).ID, UriKind.Relative));
 
    // Reset selected item to null (no selection)
    MainLongListSelector.SelectedItem = null;
}

The MainLongListSeletor.SelectedItem is tested to see if there if the user has selected anything. The selected item is cast to an ItemViewModel and the ID property is concatenated into the Uri as a query string parameter added to the path to the details page. One advantage of QueryString parameters over the use of a fragment is that you can have as many parameters as you need, whereas you are limited to a single fragment.

Listing 2-19 shows the override of the OnNavigatedTo method in the DetailsPage.xaml.cs file. The ID of the selected item is retrieved from the NavigationContext.QueryString, converted to an integer, and then used to index into the Items property of the anchor view model.

Listing 2-19. Override of the OnNavigatedTo Method in DetailsPage.xaml.cs

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    if (DataContext == null)
    {
        string selectedIndex = "";
        if (NavigationContext.QueryString.TryGetValue("selectedItem", out selectedIndex))
        {
 
            int index = int.Parse(selectedIndex);
            DataContext = App.ViewModel.Items[index];
        }
    }
}

Basic Configuration

The LongListSelector is simple to use and you configure it the same as you would a ListBox when displaying a flat list. You simply set the ItemsSource property to any collection of items that implements IList, set the ItemTemplate with a DataTemplate and the rest just works. Listing 2-20 is the LongListSelector definition from the Windows Phone Data Bound App project template:

Listing 2-20. XAML for LongListSelector Basic Configuration

<phone:LongListSelector
    x:Name="MainLongListSelector"
    ItemsSource="{Binding Items}"
    <phone:LongListSelector.ItemTemplate>
        <DataTemplate>
          <StackPanel Margin="0,0,0,17">
               <TextBlock
                 Text="{Binding LineOne}"
                 Style="{StaticResource PhoneTextExtraLargeStyle}"/>
               <TextBlock
                 Text="{Binding LineTwo}"
                 Margin="12,-6,12,0"
                 Style="{StaticResource PhoneTextSubtleStyle}"/>
          </StackPanel>
        </DataTemplate>
    </phone:LongListSelector.ItemTemplate>
</phone:LongListSelector>

In fact, the LongListSelector is so similar in basic configuration to a ListBox that you can actually replace the phone:LongListSelector with ListBox and it will just work. Visually, you won’t even notice the difference. However, you won’t find the ListBox in the Visual Studio ToolBox. This was done to emphasize that the LongListSelector is now the default choice and to encourage its use when displaying lists of data. You can still use the ListBox if you want, but you must type it in directly in you XAML.

As mentioned earlier, you can set the ItemsSource to any collection of data that implements IList. The most common choice is the ObserveableCollection<T> . Since it derives from Collection<T> it has support for IList and adds support for INotifyCollectionChanged which allows any ItemsControl bound to it to automatically detect additions and deletions and update the UI accordingly.

Create a new Windows Phone Data Bound App and then open the MainViewModel.cs file in the editor. Notice how there is a hard-coded list of items being added to the Items property. While this gets the job done, it doesn’t scale particularly well. What if you wanted to try out your list with a thousand items? Listing 2-21 shows a neat trick using LINQ to quickly generate as many items as you want in just a couple of statements. The declarative nature of LINQ makes it a very powerful tool when it comes to data manipulation. We’ll revisit LINQ when we get to grouping data in a later section.

Listing 2-21. Sample test data using LINQ

var testItems = from number in Enumerable.Range(1, 1000)
                select new ItemViewModel
                {
                    ID = number.ToString(),
                    LineOne = "First Line " + number,
                    LineTwo = "Second Line " + number,
                    LineThree = "Third Line " + number
                };
Items = new ObservableCollection<ItemViewModel>(testItems);

For scenarios where you just want to get some data into the list and don’t need view models, data binding and collection change notification you can set the ItemsSource to the results of a LINQ statement by simply calling the ToList() extension method as shown in Listing 2-22.

Listing 2-22. Setting the ItemsSource to the Results of a LINQ Statement

var testItems = from number in Enumerable.Range(1, 1000)
                select new ItemViewModel
                {
                    ID = number.ToString(),
                    LineOne = "First Line " + number,
                    LineTwo = "Second Line " + number,
                    LineThree = "Third Line " + number
                };
MyLongListSelector.ItemsSource = testItems.ToList();

In the next section we’ll take a look at creating the various templates that define the look of the LongListSelector control.

Templating

The LongListSelector exposes several properties of type DataTemplate that define the look of the various parts of the control. Table 2-4 lists these properties.

Screen space is always at a premium on mobile devices so you need to be aware of how best to use that space when designing your pages. It will probably be a rare occasion when you need to use the ListHeader and ListFooter. Most likely your list will be hosted in a PhoneApplicationPage or PivotItem and the TitlePanel content of the page or the Title and Header information of the PivotItem should be enough of a description for your list. Figure 2-5 shows a screen shot from the TheLongListSelector sample project. Any additional information would just be redundant.

From the sample screenshot in Figure 2-5 you can also see that the GroupFooter would more than likely be redundant and add nothing to the display of information. The end of one group is quite effectively demarcated by the header of the next group.

As always when creating your UI you should follow the Modern UI desing guidelines. Listing 2-23 shows the definition of an ItemTemplate taken from the Chapter two sample code.

Listing 2-23. ItemTemplate Sample for LongListSelector

<DataTemplate x:Name="AlphaItemTemplate">
    <Grid Margin="0,0,0,17">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="128"/>
            <ColumnDefinition />
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>
        <Image
            Grid.Row="0"
            Grid.RowSpan="2"
            Source="{Binding FlagUri}"/>
        <TextBlock
            VerticalAlignment="Center"
            Grid.Column="1"
            Margin="6,0,0,0"
            Text="{Binding EnglishName}"
            Style="{StaticResource PhoneTextLargeStyle}"/>
        <TextBlock
            VerticalAlignment="Top"
            Grid.Column="1"
            Grid.Row="1"
            Margin="6,0,0,0"
            Text="{Binding LocalName}"
            Style="{StaticResource PhoneTextNormalStyle}"/>
    </Grid>
</DataTemplate>

The JumpListStyle is a little different and deserves some further investigation. The JumpListStyle property is of type Style and targets the LongListSelector control type. The alphabetic jump list is almost certainly the most common. Listing 2-24 shows the style for the alphabetic grouping sample in the sample code project.

Listing 2-24. Alphabetic Jump List Style

<Style x:Key="LongListSelectorJumpListGridStyle" TargetType="phone:LongListSelector">
    <Setter Property="GridCellSize"  Value="111,111"/>
    <Setter Property="LayoutMode" Value="Grid" />
    <Setter Property="Margin" Value="18,12,0,0"/>
    <Setter Property="ItemTemplate">
        <Setter.Value>
            <DataTemplate>
                <Border
                    Margin="6"
                    Background="{Binding Converter={StaticResource BackgroundConverter}}">
                    <TextBlock
                        Margin="6,0,0,0"
                        Text="{Binding Key}"
                        Style="{StaticResource JumpListAlphabetStyle}"/>
                </Border>
            </DataTemplate>
        </Setter.Value>
    </Setter>
</Style>

There are a couple of properties of note being set in the style. The first is the LayoutMode property. This property gets it value from the LongListSelectorLayoutMode enumeration and the valid values are Grid and List. The jump list items will be arranged in a WrapPanel when the LayoutMode is set to Grid and you must define a size for the cells in the GridCellSize. The values for the GridCellSize probably strike you as a bit odd. How did we arrive at the value of 111? Running the application shows that there are four letters per row in the alphabetic jump list so we’ll base our calculations on that assumption.

Refer back to the values in Table 2-1. You’ll recall that when setting the height or width of an element you do so using device independent pixels. The logical width of the screen then is always 480 device independent pixels. You’ll notice in the style that we are setting an 18-pixel margin on the left side of the jump list only. Assuming that we want to be left with a corresponding 18 pixel margin that would leave us with 480 - 36 = 444 pixels for our cells. The math from here is left as an exercise for the reader.³

Look back at Listing 2-24 and notice the reference to a static resource named “BackgroundConverter” in the binding for the Background of the Border in the ItemTemplate of the style. This resource is declared at the top of the resource section and is an instance of the JumpListItemBackgroundConverter. There is also a JumpListItemForegroundConverter. These are two value converters provided by the framework that will automatically determine the right colors based on the user’s preferences and return a SolidColorBrush.

Listing 2-25. Declaration of the Jump List Converters

<phone:JumpListItemBackgroundConverter x:Key="BackgroundConverter"/>
<phone:JumpListItemForegroundConverter x:Key="ForegroundConverter"/>

Shaping the Data

One of the most useful features of the LongListSelector is its ability to provide quick navigation through the list using grouping and the built-in “jump list.” Grouping controls that I’ve worked with usually have built-in support for grouping and displaying data with no shaping of the data required. They do this by making use of the HierarchicalDataTemplate. This is not the case with the LongListSelector and you need to shape the data yourself.

Each grouping of data needs two things: a property that serves as the group key and an enumerable list of items. While you could create your own type from scratch by implementing IList, IList<T>, IEnumerable<T>, and ICollection<T> along with INotifyCollectionChanged so that the addition and removal of items in the list can be observed by the LongListSelector control, that’s a lot of work. Fortunately for us, the framework already provides us with 99% of what we need in the form of the ObservableCollection<T> and we can simply subclass that. Adding a property to serve as the group key and some appropriate constructors finishes the implementation. Listing 2-26 shows the just such a class.

Listing 2-26. The ObservableLongListGroup Collection

public class ObservableLongListGroup<T> : ObservableCollection<T>
{
    public ObservableLongListGroup(IEnumerable<T> collection, string key)
        : base(collection)
    {
        this.Key = key;
    }
 
    public ObservableLongListGroup(List<T> list, string key)
        : base(list)
    {
        this.Key = key;
    }
 
    public string Key { get;  set; }
 
}
  

We’ll also use the ObservableCollection<T> to expose our groups on the view model using our ObservableLongListGroup as the generic type. You could create the groups and populate their items one at a time by iteratating over your main list of items, but there is a far more efficient and elegant way of grouping your data using LINQ. Listing 2-27 shows the properties and methods in the main view model of the sample application that creates two groupings. The first one is grouped by the first letter and the second is grouped by the country’s region.

Listing 2-27. Grouping the list of coutries using LINQ

public ObservableCollection<ObservableLongListGroup<Country>> CountriesByFirstLetter
{
    get;
    set;
}
 
public ObservableCollection<ObservableLongListGroup<Country>> CountriesByWorldRegion
{
    get;
    set;
}
 
private void PopulateGroupsByWorldRegion()
{
    var byWorldRegion = from country in Countries
                        group country by country.WorldRegion into groupedCountries
                        orderby groupedCountries.Key ascending
                        select new ObservableLongListGroup<Country>
                            (
                                        groupedCountries, groupedCountries.Key
                            );
 
            CountriesByWorldRegion = new ObservableCollection<ObservableLongListGroup<Country>>
                         (
                                    byWorldRegion
                         );
}
 
private void PopulateGroupsByFirstLetter()
{
    var byFirstLetter = from country in Countries
                        group country by country.EnglishName.Substring(0, 1).ToLower()
                        into groupedCountries
                        orderby groupedCountries.Key ascending
                        select new ObservableLongListGroup<Country>
                             (
                                  groupedCountries, groupedCountries.Key
                             );
 
    CountriesByFirstLetter = new ObservableCollection<ObservableLongListGroup<Country>>
                            (
                                  byFirstLetter
                            );
}

Now that we have our data we just need to bind the items to our LongListSelector as its ItemsSource and attach the required templates. In your GroupHeaderTemplate and JumpListStyle you can bind the Key property of the ObservableLongListGroup to a TextBlock to display the group. Listing 2-28 shows the templates from the sample application.

Listing 2-28. GroupHeaderTemplate and JumpListStyle from the Sample Application

<DataTemplate x:Name="AlphaGroupHeaderTemplate">
    <Border
        BorderThickness="1"
        Background="{Binding Converter={StaticResource BackgroundConverter}}"
        HorizontalAlignment="Left"
        Width="50">
        <TextBlock
            Foreground="{Binding Converter={StaticResource ForegroundConverter}}"
            Text="{Binding Key}"
            Style="{StaticResource LongListSelectorGroupHeaderStyle}"/>
        </Border>
</DataTemplate>
 
<Style x:Key="LongListSelectorJumpListGridStyle" TargetType="phone:LongListSelector">
    <Setter Property="GridCellSize"  Value="111,111"/>
    <Setter Property="LayoutMode" Value="Grid" />
    <Setter Property="Margin" Value="18,12,0,0"/>
    <Setter Property="ItemTemplate">
        <Setter.Value>
            <DataTemplate>
               <Border
                   Margin="6"
                   BorderThickness="1"
                   BorderBrush="{Binding Converter={StaticResource BackgroundConverter}}">
                   <TextBlock
                       Margin="6,0,0,0"
                       Text="{Binding Key}"
                       Style="{StaticResource JumpListAlphabetStyle}"/>
                   </Border>
            </DataTemplate>
        </Setter.Value>
    </Setter>
</Style>

Installation

The WPToolkit was previously provided as an MSI-based installer. The Visual Studio extension NuGet has become increasingly popular and just recently the NuGet Gallery surpassed 50 million downloads. The NuGet package manager is also included with Visual Studio 2012 right out of the box. Given this popularity many third-party toolkits and libraries are choosing NuGet as their installation and distribution channel. The WPToolkit is now hosted in the NuGet Gallery.

Once you have the most recent version, use the package manager to add the WPToolkit libraries to a new Windows Phone App.

Referencing the Controls

Once you have added the WPToolkit to your project you’ll notice a new reference to the Microsoft.Phone.Controls.Toolkit assembly. You need to define an XML namespace in your XAML so that you can use the controls in the toolkit. The samples available on http://phone.codeplex.com are quite comprehensive so we won’t go into any depth here. Listing 2-29 shows the namespace reference and a sample of the Rating control.

Listing 2-29. XML Namespace for the WPToolkit in XAML

<!-- add to the list of namespace declarations at the top of the XAML-->
xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"
 
        <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <Grid.RowDefinitions>
                <RowDefinition/>
                <RowDefinition/>
            </Grid.RowDefinitions>
            <toolkit:Rating
                Width="250"
                Height="50"
                x:Name="RatingControl"
                RatingItemCount="5"
                Value="3.5"
                ShowSelectionHelper="True"/>
            <TextBlock
                HorizontalAlignment="Center"
                Grid.Row="1"
                Style="{StaticResource PhoneTextTitle1Style}"
                Text="{Binding ElementName=RatingControl, Path=Value}"/>
 
        </Grid>