Okra Cookbook - Creating a Windows Store app

In this tutorial you will create a new Windows Store MVVM application using the Okra App Framework templates for Visual Studio. You will familiarise yourself with the project structure, then customise the branding and UI. In addition you will load recipe data from an included data source and use it to replace the placeholder content.

Creating a new MVVM Windows Store application

1. Start Visual Studio 2012 and download the Okra App Framework Visual Studio Extensions if you have not already installed these. Details on how to install the extensions are available here.
2. From the File > New project menu create a new Visual C# project named "OkraCookbook". Be sure to select the Okra Grid App (XAML) project template from the Visual C# / OkraAppFramework category.
New Project Dialog.png
3. Start debugging by pressing F5 and explore the application, clicking on the group headers and items to view the various pages provided by the template. You will note that the application is identical in behaviour to the default Visual Studio Grid App template.

Exploring the project template

You will notice the project template has added a number of folders and files to the solution, many of which will be familiar to you if you have used any of the standard Visual Studio Windows Store templates.

Project Structure.png

The folders include,
  • Assets - This contains the images used to brand the application.
  • Common - This contains a number of common files used for Windows Store XAML development including base classes, value converters and style resources.
  • Data - This contains a "SampleDataSource.cs" file with the data source used for the placeholder data when you run the application. In addition a "DesignDataSource.cs" file contains classes for generating design-time data to aid with designing the user interface of the application.
  • Pages - This folder contains a number of subfolders, one for each of the pages within the application (Home, GroupDetail & ItemDetail). Each of these contain a XAML page, a view-model and some design-time data.
  • App.xaml - This holds any application wide resources.
  • AppBootstrapper.cs - This is a simple bootstrapper to which we will add further services at a later stage.

If you open the Pages > Home folder and select the file "HomePage.xaml" you will see a typical XAML designed user interface. Note that because we have some design-time data available you can get a good idea of how the resulting user interface will be displayed.

If you open the "HomePage.xaml.cs" code-behind file you will see that very little logic is present compared to the standard Visual Studio templates. Only an ItemClick handler is included that forwards any click events onto the underlying view-model (this is required as Windows Store applications do not currently support behaviours). Also note the [PageExport("Home")] attribute applied to the class that tells the Okra App Framework that this is the home page of the application.

If you open the "HomeViewModel.cs" file you will see a number of items including,
  • A [ViewModelExport("Home")] attribute that tells the Okra App Framework that this is the view-model to use for the home page of the application. When the application is run this will be automatically associated with the respective XAML file.
  • A number of properties that are data-bound from the XAML page.
  • A NavigateToGroupDetailCommand property that allows the group header buttons to directly data-bind to the NavigateToGroupDetail method without requiring any code in the code-behind file.

If you open the "HomeDesignData.cs" file you find a simple class which derives from HomeViewModel. This data will be used in the Visual Studio designer at design-time to allow you to see how your application will look without requiring any real data (which may involve a call to a database or web service). In this case we simply set the Groups property to some sample data generated by the DesignDataSource class.

Customising the start page and branding

You will note that the home page currently is titled "OkraCookbook". We will change that to read "Okra Cookbook", as well as updating the branding images and text.

1. Open the "App.xaml" file
2. Change the string resource named "AppName" to,
<x:String x:Key="AppName">Okra Cookbook</x:String>

3. In the Visual Studio solution explorer, right-click the Assets folder and use Add > Existing Item to add the images from the Branding folder of the tutorial assets (downloadable from here), overwriting the existing files.
4. Open the "Package.appxmanifest" file and change the application's display name to "Okra Cookbook" and description to "Okra Cookbook Application"
5. Also select the Wide Logo item from the Visual Assets section and set this to "Assets\WideLogo.png".

Loading recipe data

Now the project will have the correct branding, splash screen and tile icon. However, we are still displaying the sample data provided with the project template. Next we will update the project to display recipe data.

1. Open the Data folder from the solution explorer and delete the "SampleDataSource.cs" and "DesignDataSource.cs" files.
2. Right-click the Data folder and use Add > Existing Item to add the files from the Data folder of the tutorial assets (downloadable from here). The items added are,
RecipeDataSource.cs - Contains the data models and data source for the recipe data. The RecipeDataSource class includes methods named LoadLocalDataAsync() and LoadRemoteDataAsync() that load recipe data from a local file or a Windows Azure web service respectively
DesignDataSource.cs - Contains a class that can generate sample data for display at design-time
Recipes.txt - A text file containing JSON formatted data for use by the RecipeDataSource class
3. Replace all references to sample data in "HomeViewModel.cs", "HomePage.xaml.cs", "GroupDetailViewModel.cs", "GroupDetailPage.xaml.cs" and "ItemDetailViewModel.cs" as follows (Note that if you press F6 to build the application any references you have missed will be easily located as build errors)
Replace SampleDataSource with RecipeDataSource
Replace SampleDataGroup with RecipeDataGroup
Replace SampleDataItem with RecipeDataItem
4. Add a new folder to the project named Images and copy the files from the Images folder of the tutorial assets (downloadable from here). This is easiest to accomplish by dragging the files from Windows Explorer and dropping them onto the newly created Images folder.
5. Next we need to load the recipe data at application start-up. This will need to be completed before the first page is displayed so open the "AppBootstrapper.cs" file.
6. Add the following using statements to the start of the file.
using OkraCookbook.Data;
using Windows.ApplicationModel.Activation;
using Windows.ApplicationModel.Core;

7. Add the following overridden method to the AppBootstrapper class
protected async override void OnActivated(CoreApplicationView sender, IActivatedEventArgs args)
    if (args.PreviousExecutionState != ApplicationExecutionState.Running)
        await RecipeDataSource.LoadLocalDataAsync();

    base.OnActivated(sender, args);

Last edited May 12, 2013 at 6:00 PM by AndyWilkinson, version 20


No comments yet.