Macca Blog

My life experiences with code and design

Anatomy of the “Grid App” template in VS2012 for Windows 8 (C# XAML)

Posted on by Mark

In this post I thought I would take the opportunity to look through the sample project template within Visual Studio 2012 RTM called the “Grid App” template (seen below).

Visual Studio new project window highlighting the Grid App template

I am going to look at a whole heap of different aspects of this template as it has a great amount of useful information, tips, classes and best practices for Windows 8 Metro style apps.

Here is how this post will be broken down:

  1. Overview of what the app does
  2. Project structure
  3. Domain models and Sample Data
  4. Pages and Styles used
  5. App Startup and Resuming and the SuspensionManager
  6. Accessibility
  7. Whats Missing?
  8. Wrap Up

Overview of what the app does

This app is essentially a product -> category browsing application that allows the user to pan and scroll through various groups and items within those groups.

The data that Microsoft have used for this template is very generic and non-specific and I suspect that this is mainly done to keep the focus away from the actual information and to focus the developer on how to use the various classes/XAML/converters etc. that the template is designed for.

Blank Application Screen

Blank Application Screen – Start Screen

Blank App Screen -> Group Details Screen

Blank App Screen -> Group Details Screen

Blank App Screen 3 -> Item Details Screen

Blank App Screen 3 -> Item Details Screen

It has support for all kinds of Windows 8 features:

  • Scalable screen dimensions
  • “Snapped” view
  • Accessibility
  • AppBar support
  • Design time data for great Blend/VS2012 support
  • and more…

Project Structure

The project is broken down into the following structure:

Solution Overview

Solution Explorer view of the project template

 ‘Root’ Directory

App.xaml / App.xaml.cs – Standard App start up XAML and C#. Contains logic around start-up and storing app state on app suspending

BlankGridApplication_TemporaryKey.pfx – (Personal Information Exchange) Certificate file for building and signing the app.

GroupDetailPage.xaml / GroupDetailPage.xaml.cs  – Details page for the different Groups in the app

GroupedItemsPage.xaml / GroupedItemsPage.xaml.cs – Details page for the Items within the selected group

ItemDetailPage.xaml / ItemDetailPage.xaml.cs – Details page for an individual item

Package.appxmanifest – App manifest file identifying everything about what the app is and does (including application capabilities, packaging and tile information)

 ‘Assets’ Folder

This folder contains basic images used for the app, splash screen logos, some simple in app backgrounds, and so on… nothing exciting here.

‘Common’ Folder

This is a folder of particular interest. There are a number of very useful classes in here and they are very re-usable across apps and you should take some time to understand them and use them yourselves.

From the snippet in the ReadMe.txt:

The Common directory contains classes and XAML styles that simplify application development

BindableBase.cs

Base class used for inheritance with ViewModel’s INotifyPropertyChanged.

This class is great for use across the board, it has a method:

protected bool SetProperty<T>(ref T storage, T value, [CallerMemberName] String propertyName = null)
{
    if (object.Equals(storage, value)) return false;
 
    storage = value;
    this.OnPropertyChanged(propertyName);
    return true;
}

which allows you to simply the setting of a property which will take care of checking for changes and calling INPC. It can be invoked like this:

private string _title = string.Empty;
public string Title
{
    get { return this._title; }
    set { this.SetProperty(ref this._title, value); }
}

Notice that we are not setting the backing property, its done in the SetProperty method.

BooleanNegationConverter.cs

Basic converter to invert the value of a bound Boolean (true is false, false is true)

BooleanToVisibilityConverter.cs

The ultimate in converters!

LayoutAwarePage.cs

This is a great class that your Page’s should inherit from if they want to achieve certain aspects (pulled directly from the class doco):

  • Application view state to visual state mapping
  • GoBack, GoForward, and GoHome event handlers
  • Mouse and keyboard shortcuts for navigation
  • State management for navigation and process lifetime management
  • A default view model

ReadMe.txt

Derp!

RichTextColumns.cs

Custom control that inherits from Panel. This is a class that Microsoft have created for this app which essentially creates columns of content as per defined by the layout margins of the DataTemplate. For example the following creates a collection of 400-pixel wide columns spaced 50 pixels apart to contain arbitrary data-bound content:

    <RichTextColumns>
         <RichTextColumns.ColumnTemplate>
             <DataTemplate>
                 <RichTextBlockOverflow Width="400" Margin="50,0,0,0"/>
             </DataTemplate>
         </RichTextColumns.ColumnTemplate>
 
         <RichTextBlock Width="400">
             <Paragraph>
                 <Run Text="{Binding Content}"/>
             </Paragraph>
         </RichTextBlock>
     </RichTextColumns>

StandardStyles.xaml

This is such a great XAML file that contains a VAST number of different, commonly used styles. From RichTextBlocks to TestBlocks and Button styles.

There is also approximately 200 different AppBar button styles. Amazing!

There is a blog post here that has a nice app which demonstrates each one of these styles.

AppBar button styles

AppBar button styles

SuspensionManager.cs

The SuspensionManager is a class that is designed to be used to save and restore application state. Its a generified class that is used to store Serializable objects into the LocalFolder of the app. Its a great simplified class, but read and use it carefully.

‘DataModel’ Folder

SampleDataSource.cs – This class is used to define the different models (see below) and creates a static data source for the app to use.

Domain models and Sample Data

The sample data itself, is not complex. So I want to show you a class diagram below:

Class Diagram

Class Diagram

Its basically broken down into 3 main areas, the sample data, the different pages of the app (GroupDetailPage, GroupedItemsPage, ItemDetailPage and the base class LayoutAwarePage) and the various other helper classes, converters and app files.

Pages and Styles used

In this section I would like to go over each of the pages of the app and talk about the layout chosen for each of these pages.

GroupDetailPage

This is the default screen that loads when the app starts. Its broken down into 4 areas.

  1. The main GridView that contains the categories and items
  2. The main ListView (that is hidden by default) that is use also to show the group categories and items, however, this is the control used for the ‘snapped view’
  3. The title grid which contains the back button and the main title
  4. Lastly, the visual states that dictate the different view styles of FullScreenPortrait and Snapped. These are triggered when the user changes the state of the app.

GroupedItemsPage

This is actually very similar to the GroupDetailPage in its make-up, it contains the same 4 aspects, GridView for the key information, ListView for the snapped view, the title and the different visual view states.

However, it is focused to the selected group, in order to get to this page, you need to click/tap on a specific category. When this page loads, it checks the ‘navigationParameter’ in the LoadState method which gets a select group of items and sets them as the DataContext.

protected override void LoadState(Object navigationParameter, Dictionary<String, Object> pageState)
{
    // TODO: Create an appropriate data model for your problem domain to replace the sample data
    var sampleDataGroups = SampleDataSource.GetGroups((String)navigationParameter);
    this.DefaultViewModel["Groups"] = sampleDataGroups;
}

simple :)

ItemDetailPage

This uses a great new control in Windows 8 apps, the FlipView control which allows the user to move between items in a collection (see more details here on the FlipView control).

The FlipView control gets a collection of items from the data source filtered again by the ‘navigationParameter‘ and sets the DataContext.

App Startup and Resuming and the SuspensionManager

The SuspensionManager class is a helper class created by Microsoft and a part of most (if not all) of the templates in Visual Studio, that essentially writes session state to an xml file called _sessionState.xml and stored in the local storage of the app.

It achieves this by allowing the application to register their running frame with the manager, then page by page (initially implemented in the LayoutAwarePage) adding session state to the manager which is persisted to the XML file mentioned above.

I would recommend that you read and play with this, is its hard to explain in a simple paragraph. I might, in fact, write a separate blog post on it some other time (if requested :) ).

Accessibility

As a very nice part of Windows 8 applications (in fact .NET 4.5), there is a great deal of support for accessibility. This app template also makes use of these features.

The AutomationProperties (inside the Windows.UI.Xaml.Automation namespace) API for XAML makes different accessibility possible via assitive technology such as screen readers.

Whats missing?

When I set out to write this blog post, I certainly thought it would not be this long… there is a large shopping list of controls/best practices/APIs/etc. but one of the perhaps less obvious, but ultimately very important, components that was not used is the Localisation API which really should be part of each and every application and I would have thought that this template would take advantage of that (considering the investment in the Accessibility investment).

Wrap Up

This is my first blog post in a LONG time, I hope to get back into the blogging scene with windows 8 as I feel it really is such a big part of the future for consumers and corporate. It was more than I wanted to put up, but I just got carried away.

 

If you are reading this and have thoughts, I truly love feedback and improvements, please comment!

This entry was posted in .NET, C#, Featured, Windows 8, WinRT, XAML. Bookmark the permalink.

Leave a Comment

Your email address will not be published. Required fields are marked *


*