Andy On WPF, Windows 8 and Beyond

Windows Store MVVM Templates for Visual Studio

2013-05-12T21:31:00.000+01:00

If you have ever tried to create a Windows Store application using the MVVM pattern then you will probably have found that the Visual Studio project and item templates are a bit cumbersome. I often find myself adding a new page to my projects using one of the default templates, only to need to rewrite it to follow the MVVM pattern before I can even start adding application specific logic. What if there was a way to take advantage of the selection of project and page templates provided by Visual Studio, but have them produce fully MVVM compliant code?

Well today I’d like to announce the release of a free extension for Visual Studio 2012 (including the Express editions for Windows 8) that provides just that. It is based upon the open source Okra App Framework, and provides almost all of the Visual Studio Windows Store templates in an MVVM friendly manner.

Installing the Extension

The “Windows Store MVVM Templates for the Okra App Framework” extension is available for download from the Visual Studio Gallery, or available directly in the Visual Studio Extensions and Updates manager (the recommended method). Instructions for installing via Visual Studio are available at the Downloading the Okra App Framework page in the Okra App Framework documentation.

What Templates are Provided?

There are two types of template included, project templates and item templates. The project templates are designed to get you started with a new application and provide exactly the same behaviour as the default Visual Studio templates (but written following the MVVM pattern).

Okra Basic App - A single-page Okra App Framework project with no predefined controls or layout.
Okra Grid App - A three-page Okra App Framework project that navigates among grouped items arranged in a grid. Dedicated pages display group and item details.
Okra Split App - A two-page Okra App Framework project that navigates among grouped items. The first page allows group selection while the second displays an item list alongside details for the selected item.

Also included are a number of item templates that allow you to add new pages to any existing Okra App Framework based application, whether created using the project templates or not.

Basic Page (MVVM)
Split Page (MVVM)
Items Page (MVVM)
Item Detail Page (MVVM)
Grouped Items Page (MVVM)
Group Detail Page (MVVM)
Search Contract (MVVM)
Share Target Contract (MVVM)
Settings Pane (MVVM)

What do the MVVM Pages Look Like?

All the page templates (and each of the pages in the project templates) include the following files,

A XAML file containing the UI design, as well as an associated code-behind file. Since we are following the MVVM pattern this code-behind file contains very little logic.
A view-model that contains the properties and logic for the page.
In addition a file for design-time data is provided. This allows you to easily layout complex user interfaces in the designer with a visual representation of how the resulting page will look.

Summary

As I have discussed the new “Windows Store MVVM Templates for the Okra App Framework” make it quick and easy to implement pages following the MVVM pattern for use in Windows Store applications. The behaviour of all the templates has been designed to be identical to the default Visual Studio templates, with the added benefit of clean separation of code, unit testability and design-time data.

Improvements in Version 0.9.6 of the Okra App Framework

2013-03-24T16:44:00.000Z

To start off I would like to announce that I have just pushed a minor fix for the Okra App Framework NuGet packages with the version number v0.9.6.1. This fixes an issue with the NuGet packaging and contains the same code base as the recent v0.9.6 release. If you have previously updated to v0.9.6 via NuGet I would recommend you update to the new packages. Anyone who has downloaded the source code releases of v0.9.6 do not need to make any changes.

Following that brief announcement I would like to use the rest of this post to discuss a couple of changes that were made with the recent v0.9.6 release of the Okra App Framework to support more advanced activation and navigation scenarios. The good news is that these changes should not affect any existing code, however you may wish to implement these changes to take full advantage of future features within Okra.

Activation of Applications via the OkraApplication class

In previous releases of the Okra App Framework the recommended way of initializing your application was to create an AppBootstrapper class that derived from OkraBootstrapper. This would then be initialized from your App.xaml.cs file’s constructor,

sealed partial class App : Application

    public App()

        this.InitializeComponent();

        // *** NB: THIS CODE IS NOT RECOMMENDED! ***

        AppBootstrapper bootstrapper = new AppBootstrapper();

        bootstrapper.Initialize();

Whilst this will continue to work for existing applications based on the Okra App Framework, this approach does not support certain types of activation, in particular the recently introduced share target support.

Instead the recent release has introduced an OkraApplication class that should be used to derive your App class from. The AppBootstrapper is still required and needs no further changes, however the OkraApplication class will ensure that all activation events are recognised.

The changes that you should make are:

Change your App.xaml.cs class to read,

sealed partial class App : OkraApplication

    public App()

        : base(new AppBootstrapper())

        this.InitializeComponent();

Change the type of your App.xaml definition to be derived from OkraApplication (NB: Only the changes are shown in the code snippet below),

<okra:OkraApplication

...

    xmlns:okra="using:Okra">

...

</okra:OkraApplication>

Introduction of INavigationContext

The second feature I will discuss is the introduction of the INavigationContext interface. This is designed to allow more consistent navigation code, better code reuse and better support for more advanced navigation scenarios (such as those discussed here and here).

In previous releases of the Okra App Framework you would support navigation from you view-model by importing an INavigationManager. For example,

public class MyViewModel : NotifyPropertyChangedBase

    // *** NB: NO LONGER RECOMMENDED ***

    [Import]

    INavigationManager NavigationManager { get; set; }

...

If you were writing a settings pane then INavigationManager would be replaced with ISettingsPaneManager, and in other cases (such as file pickers or in multiple navigation applications) you may have a number of simultaneous navigation stacks of the same type to choose from.

With the v0.9.6 release of the Okra App Framework this has all been consolidated into a single INavigationContext interface. This can be imported via your view-models constructor and will return the correct navigation manager for the current page’s context,

public class MyViewModel : NotifyPropertyChangedBase

    INavigationBase NavigationManager { get; private set; }

    [ImportingConstructor]

    public MyViewModel(INavigationContext context)

        this.NavigationManager = context.GetCurrent();

...

The advantage of this approach is that you can use the same code in any of the cases mentioned above, and even reuse the same view-model definition between different contexts.

Summary

In this post I have discussed a couple of improvements in the latest release of the Okra App Framework. Whilst existing code should continue to work using the old mechanisms, I would recommend that you adapt your code to take advantage of the benefits described above.

Version 0.9.6 of the Okra App Framework is available from the Okra CodePlex site and via NuGet (v0.9.6.1).

Okra App Framework v0.9.6 Released

2013-03-21T22:16:00.001Z

The latest update to the Okra App Framework has just been released and is available from the Okra CodePlex site and via NuGet.

New Features in This Release

Support for the share charm (more information on these in a future post),

View-model centric share source support – by implementing ISharable on view-models they can automatically provide context specific sharing of data with other applications.
MVVM based share target support – implement a share target to accept data from other applications via a specified view/view-model.
Helper methods for task based asynchronous data sharing.

New OkraApplication base class that will allow the framework to handle more advanced activation events in the future (more on this in a future post).
Introduction of an INavigationContext that can be imported into views and view-models (more on this in a future post).
The INavigationBase interface now has an additional CanNavigateTo(…) method that allows consumers to determine if a named page is available without performing the navigation.
Refactoring of state persistence into the NavigationBase abstract class to allow reuse of this logic in custom navigation scenarios.
Additional events are raised,

upon navigation between pages (on INavigationBase)
upon flyout opening/closing (on ISettingsPaneManager)

All exceptions on application start-up should now be injected back into the application and not lost.

Breaking Changes

There are a small number of breaking changes in this release of the framework, however most of these are unlikely to apply to users of the framework (they are mostly under-the-hood interface changes that would only be applicable in advanced scenarios).

The only important change is,

The default OkraBootstrapper base class no longer implements the SearchManager property. If you are using the Okra search functionality then you should simply add the following code to your application bootstrapper.

[Import]

public ISearchManager SearchManager { get; set; }

For reference the other breaking changes are,

The SearchManager implementation now includes a default search page name (specified in the SpecialPageNames class). Since search is now opt-in this should not cause problems for existing code.

Removal of the obsolete SetupNavigationManager() method from OkraBootstrapper – this code can simply be placed in the SetupServices() method instead.

This IViewFactory now accepts an INavigationContext when creating pages. This should be injected during the composition process (handled automatically by the default MEF implementation).

Additional methods/properties to the INavigationBase, IViewFactory and ISettingsPaneManager interfaces. These will need to be added to any custom implementations.

Creating Authentic Looking Settings Panes with SettingsChrome

2013-02-04T21:52:00.001Z

In my last post I described how the Okra App Framework allows you easily add multi-page settings panes to your Windows Store applications using the MVVM pattern.

However, the built in Windows 8 applications have a very distinctive style of settings pane and many Windows Store applications will want to recreate this style. To aid with this the Okra App Framework provides a SettingsChrome control to recreate the standard UI chrome.

Using the SettingsChrome control

If you remember from previously, you define the UI for an Okra App Framework settings pane using a standard UserControl with the PageExportAttribute applied to it.

[PageExport("MySettings")]

public sealed partial class MySettingsPage : UserControl

...

In the XAML we can add the Okra SettingsChrome control as the first child element (this can be done either manually in the XAML or added in the designer). SettingsChrome is a content control, and anything that you add inside it will be displayed within the content region of the settings pane. Also you may wish to set the width of the UserControl to define the size of the resulting settings pane.

<UserControl

...

    xmlns:ui="using:Okra.UI"

    Width="346">

    <ui:SettingsChrome Title="Sample"

        Logo="ms-appx:///Assets/SmallLogo.png"

        BackButtonCommand="{Binding ...}"

        HeaderBackgroundBrush="{StaticResource ...}"

        HeaderForegroundBrush="{StaticResource ...}">

        <!-- Insert settings pane content here -->

    </ui:SettingsChrome>

</UserControl>

There are a number of properties that you can set on SettingsChrome,

“Title” – This property allows you to set the text that is displayed at the top of the settings pane

“Logo” – This should point to an image resource to use as the application logo in the top-right corner of the settings pane

“BackButtonCommand” – This can be bound to a relevant command on the view-model and will be called whenever the user clicks on the settings pane back button

“HeaderBackgroundBrush” – This allows you to set the background colour for the settings pane header. Generally this will be a static resource set to the same colour used for application tile background

“HeaderForegroundBrush” – This allows you to set the foreground colour for the settings pane header

Summary

To summarise, the Okra App Framework allows you to easily recreate the standard settings pane UI within your own application by simply adding a SettingsChrome control into the pane’s XAML.

A sample application demonstrating the use of SettingsChrome, as well as how to define a settings pane using MVVM is available from the Okra CodePlex downloads page.

Settings Panes and the Okra App Framework

2012-12-17T22:03:00.001Z

In this post (the first of two) I will describe how you can use the Okra App Framework to add custom settings panes to your Windows Store application, in particular taking advantage of the MVVM pattern. In my following post I will show you how to easily design a settings UI consistent with the built-in Windows applications.

In Windows 8, application settings are available from any page of a running application by using the settings charm. This brings up a system-provided list of the available settings entry points, with application specific settings at the top (followed by the Windows provided “Permissions” and “Rate and review” items). If the user selects one of these application specified entry points it is the responsibility of the running application to provide the resulting settings UI.

Defining a Settings Pane with the Okra App Framework

The Okra App Framework makes it simple to add custom settings panes, following the same pattern as any other page within an Okra based application. The framework takes care of displaying the correct UI and providing a dedicated navigation stack within the settings pane.

Any element may be used to define the settings UI, however a UserControl is most commonly used. This is tagged with a page name using the PageExport attribute in the code-behind file.

[PageExport("MySettings")]

public sealed partial class MySettingsPage : UserControl

...

If using the MVVM pattern, the view-model is similarly defined and attributed with the ViewModelExport attribute.

[ViewModelExport("MySettings")]

class MySettingsViewModel : ...

...

This is all that is required to define an MVVM based settings pane.

Displaying the Settings Pane

Whenever a user opens the settings pane, the currently running application is notified via the ‘SettingsPane.CommandsRequested’ event and asked to return the settings to display. In Okra based applications the recommended place to register for this event is in the SetupServices() method of the application bootstrapper. In the event handler you can add any number of settings commands in the order they are desired.

The Okra App Framework provides an ISettingsManager interface and default implementation to handle the resulting navigation to a settings pane. By calling the ‘NavigateTo(…)’ method the settings UI will be displayed in a slide-in pane at the edge of the screen.

public interface ISettingsPaneManager : INavigationBase

    void ShowSettingsPane();

public interface INavigationBase

    bool CanGoBack { get; }

    INavigationEntry CurrentPage { get; }

    event EventHandler CanGoBackChanged;

    void GoBack();

    void NavigateTo(string pageName);

    void NavigateTo(string pageName, object arguments);

To make this even easier, the Okra App Framework provides a helper extension method on any INavigationBase instance named ‘GetNavigateToSettingsCommand(…)’ which takes as arguments the name to display to the user, and the page name we defined in the previous section. Therefore a typical bootstrapper will look as follows,

public class AppBootstrapper : OkraBootstrapper{    // *** Imported Properties ***     [Import]    public ISettingsPaneManager SettingsPaneManager { get; set; }     // *** Overriden Base Methods ***     protected override void SetupServices()    {        // Register with Windows to display items in the settings pane         SettingsPane.GetForCurrentView().CommandsRequested += SettingsPane_CommandsRequested;    }     // *** Private Methods ***     void SettingsPane_CommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)    {        // Add each settings item in the order you wish them to appear         args.Request.ApplicationCommands.Add(SettingsPaneManager.GetNavigateToSettingsCommand("Settings", "MySettings"));     }}

Navigation Within the Settings Pane

Whilst in many cases a custom settings pane will self contained, multi-page settings are possible. Consider an “Accounts” setting where a link takes you to a further “Add account” settings page. This is fully supported in the Okra App Framework by calling the ISettingsPaneManager.NavigateTo(…) and .GoBack() methods to navigate between sections. In addition, calling ‘GoBack()’ on the first page in the navigation stack will redisplay the system provided settings list.

Summary

To summarise, the Okra App Framework makes adding settings panes to your application simple. The steps are,

Create a UserControl with the desired UI and set the PageExport attribute.
Optionally add a view-model attributed with the ViewModelExport attribute.
In the application bootstrapper register for the SettingsPane.CommandsRequested event and use the GetNavigateToSettingsCommand(…) extension method to return a SettingsCommand.

A sample application demonstrating custom settings panes is available from the Okra CodePlex downloads.

Of course it is up to you to provide a suitable UI for the displayed settings pane. In my next post I will describe how to use Okra’s SettingsChrome to present a UI consistent with the standard Windows experience.

Okra App Framework v0.9.5 Released

2012-11-04T13:06:00.001Z

The latest update to the Okra App Framework has just been released and is available from the Okra CodePlex site and via NuGet.

New Features in This Release

Settings support

The framework now includes support for the Windows 8 settings charm. Custom application settings panes can be defined using the MVVM pattern and Okra will handle the wiring required to show the settings pane – I will write about this in detail in an upcoming blog post.
A SettingsChrome control is included to allow developers to easily match the settings UI of the default Windows 8 applications

The NavigationManager class has now been refactored to derive from a NavigationBase class with the base functionality. This allows the creation of custom navigation managers (for example the SettingsPaneManager)
Updated to support MEF v1.0.16
Minor improvements and bug fixes

App Search and the Okra App Framework

2012-10-29T21:50:00.001Z

One advantage of the Okra App Framework over other MVVM-based application frameworks is that it is designed from the ground up to work great with Windows 8. Over the next few versions this will become more evident as features are added to support the various Windows 8 system contracts – search, settings, sharing, etc.

In this post I will describe how the Okra App Framework makes it easy to add search to your application using the same MVVM principles that you are using for the rest of your application.

The Search Contract in Windows 8

When developing Windows Store applications many developers will want to take advantage of the Windows 8 search charm. This allows users to search across all applications from a single, consistent entry point. In order to add search functionality you would generally override the OnSearchActivated(…) method in the App.xaml.cs code-behind. In fact the standard Visual Studio search page template will add the code required to do this. For a great Windows Store application however you would want to,

Fully follow the Windows search design guidelines (available here)
Preserve the existing application state and correctly handle back navigation from the search page
Navigate to a suitable page (normally the application home page) if an empty search is performed
Improve performance by attaching to the SearchPane.QuerySubmitted event where possible
You may also want to implement the search page using the MVVM pattern

By simply using the Okra App Framework search manager it will take care of these requirements.

Adding Search to Your Application with the Okra App Framework

The Okra App Framework provides a search manager to handle the process of activating search in your application. This is represented by the ISearchManager interface,

public interface ISearchManager

    string SearchPageName { get; set; }

By default the SearchPageName property is set to null, and Okra will not handle search activation. To opt-in to the search integration you should set the page name for search in your application’s bootstrapper SetupServices() method.

public class AppBootstrapper : OkraBootstrapper

    protected override void SetupServices()

        SearchManager.SearchPageName = "Search";

By adding this single line your application has been enabled for search, and a page named “Search” will be navigated to when the user performs a search within your application (note that you will also need to declare that your application supports search in the application manifest).

Defining Your Search Page

Because search uses the standard Okra page discovery mechanisms you define your search page and view-model as you would any other page within your application,

[PageExport("Search")]

public sealed partial class SearchPage : LayoutAwarePage

...

[ViewModelExport("Search")]

public class SearchViewModel : NotifyPropertyChangedBase, ISearchPage

...

One thing to note is that the search view model implements the ISearchPage interface (this could also be implemented by the page if you are not using the MVVM pattern),

public interface ISearchPage

    void PerformQuery(string queryText, string language);

This method will be called whenever the page should show a new set of search results. In this method you provide the application logic to perform the search operation and display the results to the user. Note that this may be called multiple times for a single page as the user performs subsequent searches and you should refresh the content with the new results.

Summary

In the above discussion I have shown how the Okra App Framework makes it simple to implement search functionality in applications based on the MVVM pattern.

A sample search application is available from the Okra CodePlex downloads section. This is based on the Visual Studio search template, but modified to correctly implement the MVVM pattern.

Convention Based Page Discovery With The Okra App Framework

2012-09-05T22:11:00.001+01:00

One of the key features of the Okra App Framework for developing Windows 8 apps is the navigation framework with its support for the MVVM pattern. By default pages and view-models are marked with attributes so that the framework can locate them. In this post I will describe how you can enable an alternative convention based approach.

The Default Attribute Based Approach

When using the Okra App Framework navigation support all pages are represented by a page name. So that the framework can locate the associated pages and view-models these are normally attributed with either the PageExportAttribute or ViewModelExportAttribute respectively (for more information see my previous post). For example for a page named “Foo” the classes would be attributed as,

[PageExport("Foo")]

public sealed partial class FooPage : LayoutAwarePage

...

[ViewModelExport("Foo")]

public class FooViewModel

...

A Convention Based Approach

Often however there will be a common naming pattern throughout the application. In the example above all pages are named XxxPage and view-models named XxxViewModel, where “Xxx” is the associated page name. In a convention based approach you no longer need to apply attributes to classes. Instead they are automatically discovered based on a common naming system.

Since the standard Okra bootstrapper uses MEF for composition (for example when using the Okra.MEF NuGet package), we can use the MEF convention based discovery. To enable this we need to add the following code to the application bootstrapper,

public class AppBootstrapper : OkraBootstrapper{    ...     // *** Overriden base methods ***     protected override ContainerConfiguration GetContainerConfiguration()    {        ConventionBuilder conventionBuilder = new ConventionBuilder();         conventionBuilder.ForTypesMatching(type => type.FullName.EndsWith("Page"))                         .Export(builder => builder.AsContractType<object>()                                                   .AsContractName("OkraPage")                                                   .AddMetadata("PageName", type => type.Name.Substring(0, type.Name.Length - 4)));         conventionBuilder.ForTypesMatching(type => type.FullName.EndsWith("ViewModel"))                         .Export(builder => builder.AsContractType<object>()                                                   .AsContractName("OkraViewModel")                                                   .AddMetadata("PageName", type => type.Name.Substring(0, type.Name.Length - 9)));         return GetOkraContainerConfiguration()                .WithAssembly(typeof(AppBootstrapper).GetTypeInfo().Assembly, conventionBuilder);    }}

With this code in place we can greatly simplify our page and view-model definitions to the following. Note that since we follow the convention we no longer need to add any attributes.

public sealed partial class FooPage : LayoutAwarePage

...

public class FooViewModel

...

Summary

As I have shown, when using the Okra App Framework navigation support you can simplify app development by using a convention based approach to defining pages and view-models for the MVVM pattern.

A sample application demonstrating this is available from the Okra CodePlex downloads.

Okra App Framework v0.9.4 Released

2012-08-27T21:26:00.001+01:00

Version 0.9.4 of the Okra App Framework is now available via CodePlex and NuGet. Since the core functionality of the framework has been in testing for some time now I have removed the ‘beta’ suffix from the version number, with the benefit that the framework should show in the default NuGet feed.

Minimal changes and bug fixes were made in this release, with the key change being updating the Okra App Framework to work against the RTM version of MEF (v1.0.15).

Cocoon is now the Okra App Framework

2012-08-12T20:15:00.001+01:00

Today I would like to announce that the Cocoon framework is now know as the ‘Okra App Framework’. It still includes the great features previously available in the Cocoon framework, but from now onwards will be developed under the new name.

How to Get The Okra App Framework

The ‘Okra App Framework’ CodePlex site is available at http://okra.codeplex.com/ (all previous code/downloads/discussions have been migrated from the old site, and any links to the previous URLs will redirect to their new location).

In addition there are two new NuGet packages,

“Okra App Framework” – This will be the package for most users and includes the MEF dependencies and the ‘OkraBootstrapper’ class.
“Okra App Framework (Core only)” – For users who only require the core assembly.

If you are using the Cocoon NuGet packages and wish to get future releases then you should use the NuGet package manager to uninstall Cocoon and then install the new Okra App Framework package.

Okra App Framework Release 0.9.3-beta

Along with the name change a new version of the framework has been released via NuGet and the Okra App Framework CodePlex downloads page. The changes include,

Namespace changes from ‘Cocoon’ to ‘Okra’ and from ‘CocoonBootstrapper’ to ‘OkraBootstrapper’ (a simple find-and-replace in your project should solve any errors occurring from this).
Addition of a SearchManager that allows an easy, view-model centric, implementation of the Windows 8 Search contract (I will aim to detail this in a future blog post).
The ActivationManager class allows extensible handling of application activation (you can write activation handlers to handle any of the activation types).
Upgraded to MEF version 1.0.13-rc.
Removal of the previous obsoleted VirtualizingVector with the recommendation that VirtualizingVectorBase is used going forward (although if you still require VirtualizingVector it can be downloaded as part of any of the previous source releases and copied into your own projects).

Why the Name Change?

I recently received a message from a member of the Apache Software Foundation, informing me that they also have a web application framework named Apache Cocoon. To avoid any confusion that may arise between the two frameworks the best approach going forward was a name change.

Shell Based Navigation in Cocoon

2012-08-06T21:01:00.001+01:00

I recently had a query in the Cocoon CodePlex forums regarding how to support an application shell when using the Cocoon framework’s navigation support. By default the Cocoon navigation framework will display pages full screen, with each navigation replacing the previous page with the next. There are some occasions however where it makes sense to have an application shell that takes up the full screen, with the page navigation occurring in a region within this.

A typical example would consist of a fixed region dedicated to navigation at the top of the screen, with the page content filling below. The end result looks like,

Creating an Application Shell in Cocoon

The key to creating an application shell in Cocoon is the INavigationTarget interface. This has only a single method named NavigateTo(…). When implemented by an application, any calls to the navigation framework will result in a call to this method with the page to display. The framework itself will handle the creation and wiring up of views and view-models, the navigation stack, persistence and other aspects of navigation.
In our example application we will use the MVVM pattern to define our application shell, hence we have a ShellViewModel,

   1: [Export(typeof(INavigationTarget))]

   2: [Shared]

   3: public class ShellViewModel : NotifyPropertyChangedBase, INavigationTarget

   4: {

   5:     // *** Fields ***

6:

   7:     private object content;

   8:     private ShellPage shellPage;

9:

  10:     // *** Properties ***

11:

  12:     public object Content

  13:     {

  14:         get

  15:         {

  16:             return content;

  17:         }

  18:         set

  19:         {

  20:             if (content != value)

  21:             {

  22:                 content = value;

  23:                 OnPropertyChanged();

  24:             }

  25:         }

  26:     }

27:

  28:     // *** INavigationTarget Methods ***

29:

  30:     public void NavigateTo(object page)

  31:     {

  32:         // If this is the first navigation then create the shell view and bind to this view model

33:

  34:         if (shellPage == null)

  35:         {

  36:             shellPage = new ShellPage();

  37:             shellPage.DataContext = this;

  38:         }

39:

  40:         // Set the content for the shell to the specified page

41:

  42:         this.Content = page;

43:

  44:         // Set the shell view as the window content

45:

  46:         Window.Current.Content = shellPage;

  47:     }

  48: }

The ShellViewModel exposes a single property named ‘Content’ that will contain the page to display and will be bound to in the view. In our NavigateTo(…) method we firstly determine if we have created the associated view and create this is necessary. We then set the ‘Content’ property to the supplied page and this ensure that the view is displayed in the window. Finally we mark the class as a shared export of INavigationTarget using the MEF attributes. Note that since we will never be navigating explicitly to the shell then we do not need to decorate this with a ViewModelExport attribute.

In the sample code the shell view model also exposes a ‘GoBackCommand’ that allows you to include a back navigation button within the shell region.

The ShellPage.xaml file contains the view for the application shell. This simply contains the required elements for the upper portion of the screen, with a ContentControl bound to the view models ‘Content’ property. It is within this ContentControl that the pages will be displayed. The key elements are shown below,

   1: <Grid Style="{StaticResource LayoutRootStyle}">

   2:     ...

3:

   4:     <!-- Back button and page title -->

   5:     <Grid>

   6:         <Grid.ColumnDefinitions>

   7:             <ColumnDefinition Width="Auto"/>

   8:             <ColumnDefinition Width="*"/>

   9:         </Grid.ColumnDefinitions>

  10:         <Button x:Name="backButton" .../>

  11:         <TextBlock x:Name="pageTitle" .../>

  12:     </Grid>

  13:     <ContentControl Content="{Binding Content}" .../>

  14: </Grid>

When the application is run the NavigationManager will automatically locate the INavigationTarget through the MEF export and direct all navigation through this.

Summary

I have shown above how you can implement an application shell using the Cocoon framework. The sample application with full source code is available from the Cocoon CodePlex downloads.

Cocoon Framework v0.9.2 Released

2012-07-24T21:26:00.001+01:00

As I discussed in my previous post on NuGet support in the Cocoon framework, I will be distributing major updates within the framework as new releases. Today I am pleased to say that version 0.9.2 is available from both the Cocoon CodePlex site and downloadable directly from NuGet.

New Features in This Release

This release has mainly focussed upon updates to the Cocoon data framework. In particular,

Significant improvements in how the data framework handles caching of list items.
Infrastructure added to support change notifications for data lists.
The ‘PagedDataListSource’ class now includes a ‘PageCacheSize’ property that allows you to specify the maximum number of pages to hold in memory at any one time (by default all pages are stored).
Introduction of an ‘IncrementalLoadingDataList’ class. This supports the Windows 8 Metro ISupportIncrementalLoading interface. This allows a data bound UI to download a small subset of a large list of items, with further items being retrieved and added when the user scrolls to the end of the list.
A Refresh() method has been added to SimpleDataListSource and PagedDataListSource. This allows you to clear the internal cache and re-fetch any data that may have changed. Any attached data lists will automatically update to reflect the changes.

Some improvements to the navigation framework include,

Updated to support MEF version 1.0.11-rc.
Changes to the ‘CocoonBootstrapper’ to help with a convention based approach to exporting pages and view models (I will write a blog post on this in the future).
The navigation manager now exposes a ‘CurrentPage’ property so that you can programmatically determine the currently displayed page and associated information.
Pages and view-models can now be named by specifying a type as an alternative to a string page name.
A MEF sharing boundary (named “page”) has been placed around each page and view model pair (see here for more information on MEF sharing boundaries).
Some common MVVM base classes have been included. Whilst you are not restricted to using these to take advantage of the Cocoon framework they provide basic functionality that is common to many applications. These classes include,

DelegateCommand and DelegateCommand<T> – implementations of the ICommand interface that allow you to bind UI interactions to methods on your view models.
NotifyPropertyChangedBase – provides a simple base class for view models that supports property change notification.

A number of other bug fixes.

Breaking Changes

Unfortunately there are a small number of breaking changes in this release. For most developers however the changes should be minimal.

‘SpecialPageNames.HomePage’ has been renamed ‘SpecialPageNames.Home’.
The contract for IDataListSource has changed. Note that this should only affect developers who are writing custom IDataListSource implementations. If you are using SimpleDataListSource or PagedDataListSource then existing code should not be affected. In particular the changes are,

Addition of an IndexOf(…) method to the IDataListSource interface.
The data list source implementations are now fully responsible for caching of data.

The ‘InternalList’ property of ‘DataListSourceBase’ has been removed (derived classes should create their own internal cache) and the corresponding property in ‘SimpleDataListSource’ and ‘PagedDataListSource’ has been made private.
VirtualizingVector<T> is now marked as Obsolete – it is recommended that you use the data list support or the new VirtualizingVectorBase<T>.

Getting the Latest Version of Cocoon

To get the latest release of the Cocoon framework the best place to start is using the NuGet package manager to download the “Cocoon Framework” package (see here for more information). If you are already using Cocoon via NuGet then you should be able to update your solution to the latest version directly through the NuGet package manager.

Alternatively the source code is available via the Cocoon CodePlex downloads page. As always the latest interim code drops are also available from CodePlex under the source code tab.

Cocoon Now Available on NuGet

2012-06-26T22:36:00.001+01:00

Update : The 'Cocoon' framework is now named the 'Okra App Framework'. For information on how to obtain the framework via NuGet then see the documentation here.

I am very pleased to announce that the Cocoon framework is now available via NuGet (thanks to Brendan Forster for helping to get this off the ground). Going forward this will be the recommended source when using the framework in your own projects.

Getting Cocoon Via NuGet

With the release of Visual Studio 2012, the NuGet package manager is included within the product. This means that to reference the Cocoon framework all you need to do is to right-click on the project’s “References” folder and select “Manage NuGet Packages…”

Note that since the Cocoon framework is currently pre-release then you should select “Include Prerelease” in the box highlighted in red below. You can then search for “Cocoon”.

Note that there are currently two packages for the Cocoon framework. In general you should select the package named “Cocoon Framework” as this includes the complete framework including the MEF based bootstrapper. Clicking install will then download Cocoon along with any dependencies and add these to your project.

Updating Your Project to the Latest Version Of the Cocoon Framework

One of the advantages of using NuGet to distribute the Cocoon framework is that it makes it very easy to upgrade projects to the latest version of the framework. To do this simply open the package manager for a project that you have previously added Cocoon via NuGet and select the “Updates” tab. Any updated packages will be displayed and can be upgraded with a single click.

Note: Making the Cocoon Framework Independent of Composition Container

I have had a number of queries from developers who wish to use alternative composition containers with the Cocoon framework. Whilst it is recommended for most projects that you use the provided MEF composition implementation, with this latest release the Cocoon framework can now be used with any other composition container. The project has been split into two assemblies,

Cocoon – contains the core framework independent of composition container.
Cocoon.MEF – contains the MEF dependencies (most importantly the MEF based “CocoonBootstrapper”).

How Will Cocoon be Released in the Future?

Going forward there will be three ways to obtain the Cocoon framework,

NuGet: This is the recommended source and will contain the latest stable versions. If I discuss any functionality on this blog then it will be implemented in the latest NuGet release unless otherwise stated.
CodePlex Downloads: I will also provide a zipped package of the source code via CodePlex in the Cocoon downloads section. This will be kept in sync with the NuGet releases.
CodePlex Source Control: For those interested in the very latest versions of Cocoon then this will be available as always via the “Source Code” tab of the Cocoon CodePlex site. Note however that this may include experimental functionality and may not be stable.

Cocoon Updated for Windows 8 Release Preview

2012-06-06T22:08:00.001+01:00

You will be pleased to hear that I have just pushed an updated version of the Cocoon framework onto CodePlex that supports the Windows 8 Release Preview.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Using MEF in the Release Preview

As many of you will be aware, the Cocoon framework uses the Managed Extensibility Framework (MEF) by default for locating and composing applications. With the release of the Windows 8 Release Preview, MEF is not being distributed separately – for more details see the announcement on the BCL team blog.

You will therefore need to add MEF as a reference to your application via NuGet. The above link has more details however the steps are,

Right click on your projects ‘References’ folder and select “Manage NuGet Packages…”
Select “Online” in the left-hand pane and make sure that you have “Include Prerelease” selected rather then “Stable Only” at the top.
Use the search box to search for “MEF”
Select “MEF for web and Metro style apps” and click “Install”

Changes in tHis Release of Cocoon

In general most applications should not be affected by the changes in this version of Cocoon (apart for the fact that they will run on the Release Preview!). Changes of interest include,

All use of MEF has been modified to support the new version
The ‘CocoonBootstrapper’ no longer has an overridable GetPartCatalog() method and is replaced with GetContainerConfiguration().
The ISupportPlaceholder interface has been removed in the Release Preview. The VirtualizingVector<T> implementation has been updated to reflect these changes and now returns ‘null’ as a placeholder (as now expected by the standard XAML controls).
Many other updates and bug fixes

Cocoon Navigation – Making Your App “Always Alive”

2012-05-29T19:25:00.001+01:00

Over the last few posts I have discussed the navigation framework that is included as part of the freely available Cocoon framework for developing Metro-style Windows 8 applications in .Net languages. I have shown how to annotate pages to be discovered by the framework and how to pass arguments between pages.

In this post I will discuss one of the benefits of using the Cocoon framework to manage your application’s navigation.

Making Your Application “Always Alive”

One of the challenges when writing Windows 8 Metro-style applications is to manage the application lifecycle. So that Windows is able to ensure a great experience for users running on battery powered devices, Metro style apps are suspended as the user moves to other applications. Furthermore, your application may be terminated to free more memory if this is required. However for the end user great Metro-style applications will give the impression that they are “always alive” in the background. It is up to you, the developer, to ensure that this illusion is maintained. For more background Microsoft’s Windows 8 Application Developer blog has a great post on this topic.

One aspect of making your application feel “always alive” is to ensure that if it is terminated and later relaunched then the user is taken to exactly the same point that they were previously viewing. To do this you must persist the navigation stack, currently viewed page and any page state then subsequently restore this.

Persisting Navigation With the Cocoon Framework

The great news is that if you are using the Cocoon navigation framework then this is all handled automatically for you. All you have to do is enable this by setting the INavigationManager.NavigationStorageType property. Typically you would set this by overrinding the SetupNavigationManager() method in your application bootstrapper (see this post for more information on the bootstrapper),

public class AppBootstrapper : CocoonBootstrapper

    // *** Overriden base methods ***

    protected override void SetupNavigationManager()

        NavigationManager.NavigationStorageType = NavigationStorageType.Local;

There are currently three possible NavigationStorageType values,

None – Your navigation state will not be persisted and your application will always launch to your home page.

Local – Your navigation state will be persisted to the current machine only.

Roaming – Your navigation state will be persisted between all devices that the user logs into using their Microsoft Account.

That’s all you need to do, Cocoon will handle everything else – persisting the navigation stack, restoring to the correct page, storing the arguments passed to each page.

Preserving Page State

In some cases you may want to go a step further and store some page state. Imagine for example you are half way through writing a comment in a social networking app, then change app to do something else. When you return you should expect that you can continue from where you left off. Other things you may want to preserve are selected search filters, selected items, position in a view, etc.

Preserving page state can be done by the view model implementing the IActivatable<TArguments, TState> interface that I discussed last time for passing arguments to pages. The TState generic type can be set to the data type you would like to persist (TArguments can be set to ‘string’ if it is not required).

public interface IActivatable<TArguments, TState>

    // *** Methods ***

    void Activate(TArguments arguments, TState state);

    TState SaveState();

On first navigation to the page the Activate(…) method will be called passing the default value of TState (‘null’ for string or reference types). When Cocoon determines that it should preserve page state then it will call the SaveState() method and your implementation should return the current state. If the application is later terminated and relaunched then a new instance of the view model is created and activated by calling the Activate(…) method with the preserved state.

For example, if as part of a hypothetical photo browsing app we allow the user to comment on a photo we could implement the view model as,

[ViewModelExport("ViewPhoto")]

public class ViewPhotoViewModel : IActivatable<string, ViewPhotoState>

    // *** Properties ***

    public string Comment

        get { ... }

        set { ... }

...

    // *** IActivatable Methods ***

    public void Activate(string arguments, ViewPhotoState state)

        this.Photo = GetPhoto(arguments);

        if (state != null)

            ViewPhotoState viewState = (ViewPhotoState)state;

            this.Comment = viewState.Comment;

    public ViewPhotoState SaveState()

        return new ViewPhotoState() { Comment = this.Comment };

    // *** Sub-classes ***

    [DataContract]

    private class ViewPhotoState

        [DataMember]

        public string Comment;

Note that we store the state as a custom ‘ViewPhotoState’ object that is decorated to allow serialization by the DataContractSerializer.

Summary

I have shown above how we can easily make our applications feel “always alive” by using the Cocoon navigation framework.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Cocoon Navigation – Passing Arguments Between Pages

2012-05-20T20:28:00.001+01:00

Over the last couple of posts I have introduced the navigation framework that is included as part of the freely available Cocoon framework for developing Metro-style Windows 8 applications. I have previously shown how to annotate pages with the PageExport and ViewModelExport attributes, and to navigate to these using the INavigationManager.

Passing Arguments to ViewModels

Whilst navigating between pages is a common pattern for modern applications, often you wish to pass some state during page navigation. As an example, imagine a photo browsing application. The “BrowsePhotos” page may show a number of images, which when clicked on navigates to a “ViewPhoto” page. In this case there needs to be some way to pass the image to display as an argument to the “ViewPhoto” page.

This is made simple in the Cocoon navigation framework by a second overload of the INavigationManager.NavigateTo(…) method that takes both a page name and an argument to pass between the pages.

public interface INavigationManager

...

    void NavigateTo(string pageName);

    void NavigateTo(string pageName, object arguments);

The ‘arguments’ parameter can be of any type, however there are a number of restrictions that should be observed in practice,

The type should be able to be serialized via a DataContractSerializer

The type should not rely on a reference to any particular object (for example if the value is from a shared cache it may be better to pass the key rather than the actual object to ensure that multiple versions are not created)

In our photo application example we are caching the image details, so pass the photoID from the “BrowsePhotos” view model,

[ViewModelExport("BrowsePhotos")]

public class BrowsePhotosViewModel

    // *** Fields ***

    private readonly INavigationManager navigationManager;

    // *** Constructors ***

    [ImportingConstructor]

    public BrowsePhotosViewModel(INavigationManager navigationManager)

        this.navigationManager = navigationManager;

    // *** Command Methods ***

    public void ViewPhoto(Photo photo)

        navigationManager.NavigateTo("ViewPhoto", photo.PhotoId);

Activating Destination Pages

The destination view model is able to accept parameters by implementing the IActivatable<TArguments, TState> interface where the type of the argument is designated by TArguments. The TState generic type will be discussed in a later blog post and if not required can be set as ‘string’.

public interface IActivatable<TArguments, TState>

    // *** Methods ***

    void Activate(TArguments arguments, TState state);

    TState SaveState();

After creating the new view model the Cocoon framework will call the Activate(…) method passing in the argument passed from the call to INavigationManager.NavigatedTo(…). This method will only be called once and prior to display of the view.

In our example photo browsing application the “ViewPhoto” view model will therefore be implemented as (Note that the unused SaveState() method simply returns ‘null’),

[ViewModelExport("ViewPhoto")]

public class ViewPhotoViewModel : IActivatable<string, string>

...

    // *** IActivatable Methods ***

    public void Activate(string arguments, string state)

        this.Photo = GetPhoto(arguments);

    public string SaveState()

        return null;

    // *** Private Methods ***

    private Photo GetPhoto(string photoId)

...

Summary

I have describe above how the Cocoon framework makes passing arguments between pages simple to implement. Over the next posts I will discuss some of the added value when using the Cocoon navigation framework, including how to make your application seem “always alive”.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Getting Started with Cocoon Navigation – The Cocoon Bootstrapper

2012-05-15T21:12:00.000+01:00

In my last post I introduced the navigation framework that is included as part of the freely available Cocoon framework (open source on CodePlex). This framework is designed to make page based Metro-style applications easy to construct in managed languages on Windows 8.

I previously discussed how easy it was to implement the Model-View-ViewModel (MVVM) pattern with Cocoon by simply annotating your view and view models with the ‘PageExport’ and ‘ViewModel’ export attributes respectively. Any view model can then navigate to another page by calling the INavigationManager.NavigateTo(…) method.

Since the Cocoon navigation framework is built on top of the Managed Extensibility Framework (MEF), the application is composed with the required dependencies as the user navigates through the application. MEF is a composition framework that is built into the .Net framework, that enables the construction of loosely-coupled, easily maintainable and testable applications to be composed automatically at run time. An introductory guide for those who are not familiar with MEF is available here.

What I have not covered previously however was how to navigate to the application’s first page when it is launched,

Launching Navigation Using The Cocoon Bootstrapper

To simplify the initialization of Cocoon based applications the framework includes the ‘CocoonBootstrapper’ class that can be used at startup. This manages the configuration of MEF for the most common scenarios, initialization of services and activation of the application.

To use the Cocoon bootstrapper you must first create an application specific class derived from the abstract ‘CocoonBootstrapper’ as shown below. For basic applications this class can be left empty, although the base implementation provides a number of extensibility points to enable more advanced features.

public class AppBootstrapper : CocoonBootstrapper

The next stage is to edit your application’s ‘App.xaml.cs’ file. Much of the code included with the Visual Studio templates can be removed (since this is handled by Cocoon) and the newly created bootstrapper is initialized as part of the constructor.

sealed partial class App : Application

    public App()

        this.InitializeComponent();

        // Create and initialize the application bootstrapper

        AppBootstrapper bootstrapper = new AppBootstrapper();

        bootstrapper.Initialize();

Defining the Application Home Page

The final step is to define the view and (optionally) the view model that is to be shown when your application is launched. Whilst the home page name can be modified the default value defined by the ‘SpecialPageNames.HomePage’ constant is generally all that is required.

Therefore the home page view is annotated as,

[PageExport(SpecialPageNames.HomePage)]

public sealed partial class HomePage : LayoutAwarePage

    public HomePage()

        this.InitializeComponent();

and the view model annotated as,

[ViewModelExport(SpecialPageNames.HomePage)]

public class HomeViewModel

...

The Cocoon navigation framework will then automatically locate, create and wire-up the home page on application launch.

Summary

Over the last two posts I have shown how easy the Cocoon navigation framework makes launching and navigating around Metro-style Windows 8 applications using the MVVM pattern. In the upcoming posts I will discuss some of the more advanced features you get when adopting Cocoon for navigation.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Navigation in Cocoon – MVVM for Metro-style apps

2012-04-30T22:47:00.001+01:00

Over the next series of posts I’m going to introduce a new subsystem within the Cocoon framework for Metro-style applications written in managed languages.
Modern rich client applications often consist of a number of interconnected pages or views. For example consider the Windows 8 “Store”. This has a home page that acts as a hub the links to a number of category pages, which in turn link to the individual application detail pages. The user navigates forward through the application flow by clicking images, buttons or links. They can also navigate backwards by using a back button that is placed in the top left hand corner of each page. In addition there are ‘special pages’ such as search, or even the settings panes available from the settings charm.

There are a number of challenges for developers who wish to correctly implement such a navigation structure.

Navigation in Cocoon

Although not limited to this, the Cocoon framework is designed to work great with the Model-View-ViewModel (MVVM) pattern that has become common when designing XAML based applications. One problem when using this pattern is that you need some way of associating a view with a view-model. Often this is done by navigating directly to a page, and using a “ViewModelLocator” to identify and wire up the respective view-model.

In Cocoon a slightly different approach is used. Here, rather than navigating directly to a view, you navigate to a named page. Although the behaviour is extensible, by default Cocoon will use MEF (the built in composition framework included in .Net) to locate both the view and view-model associated with this page name, create and initialise instances of these and wire them together.

You can export any XAML view (for example the pages created by any of the Visual Studio templates) by adding the ‘PageExport’ attribute to the code-behind file,

[PageExport("BrowsePhotos")]

public sealed partial class BrowsePhotosPage : MyPhotoApp.Common.LayoutAwarePage

    public BrowsePhotosPage()

        this.InitializeComponent();

And similarly you can export the view-model using the ‘ViewModelExport’ attribute,

[ViewModelExport("BrowsePhotos")]

public class BrowsePhotosViewModel

...

The Navigation Manager

In order to navigate between pages, Cocoon includes a navigation manager that can be accessed by importing the INavigationManager interface through MEF (simplified by the fact that all views and view models in Cocoon are themselves are composed by MEF).

public interface INavigationManager

    bool CanGoBack { get; }

...

    void GoBack();

    void NavigateTo(string pageName);

    void NavigateTo(string pageName, object arguments);

The most interesting methods are the two overloads of ‘NavigateTo(…)’ that both take the page name to navigate to. The navigation manager will also keep track of the current navigation stack so that you can easily use the ‘CanGoBack’ property and ‘GoBack()’ method to traverse backwards through the previously visited pages.

For example we could add methods to our BrowsePhotos view model as such,

[ViewModelExport("BrowsePhotos")]

public class BrowsePhotosViewModel

    // *** Fields ***

    private readonly INavigationManager navigationManager;

    // *** Constructors ***

    [ImportingConstructor]

    public BrowsePhotosViewModel(INavigationManager navigationManager)

        this.navigationManager = navigationManager;

    // *** Command Methods ***

    public void ViewPhoto()

        navigationManager.NavigateTo("ViewPhoto");

    public void NavigateBack()

        navigationManager.GoBack();

Summary

I have shown above how the Cocoon navigation framework allows you to easily construct a page based navigation structure for applications based upon the MVVM pattern. I have of course glossed over how you navigate to the first page of your application. I will discuss this further next time.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Using MEF in Metro-style applications

2012-04-22T20:31:00.001+01:00

Update 23 Aug 2012:

Since I originally wrote this post the standard .Net framework MEF implementation is no longer accessible from Windows 8 Windows Store applications. Instead MEF support is released out-of-band on NuGet as a specific "MEF for web and Windows Store apps" package. Once you have added this to your Windows 8 projects there is a slightly different programming model. For more information see the Microsoft.Compostion documentation.

In brief, you can set up composition with,

var configuration = new ContainerConfiguration()
        .WithAssembly(typeof(App).GetTypeInfo().Assembly);

var compositionHost = configuration.CreateContainer();
compositionHost.SatisfyImports(this);

Original post follows,

In a slight change from talking about the Cocoon framework, today I’m going to discuss how you may use MEF (the Managed Extensibility Framework) in Windows 8 Metro-style applications. Hopefully the reason for this deviation will become clear in my next post.

What Is MEF?

I’m not going to explain MEF in detail as this has been discussed many times before and is described on MSDN. Succinctly, taken directly from the MEF CodePlex page,

The Managed Extensibility Framework (MEF) is a composition layer for .NET that improves the flexibility, maintainability and testability of large applications. MEF can be used for third-party plugin extensibility, or it can bring the benefits of a loosely-coupled plugin-like architecture to regular applications.

For Windows 8 Metro-style app developers it is the loosely-coupled architecture that is of most interest (since third-party extensibility will not be applicable to application packages delivered through the Windows Store). This allows the individual components of your application to be designed, written and tested separately. The instantiation, lifetimes and connections between components is then managed by MEF at runtime.

Using MEF in Windows 8 Metro-Style Applications

The good news is that MEF is included in the .Net base class libraries as part of the Metro-style application profile so is included in-the-box for all such applications. Unfortunately if you look at the documentation you will see references to ‘Assembly.GetExecutingAssembly()’ that is not available in the Metro-profile,

// Does not work in Metro-style applications

var catalog = new AssemblyCatalog(System.Reflection.Assembly.GetExecutingAssembly());

All is not lost however, as you can access the main application assembly using,

// This does work in Metro-style applications!

var catalog = new AssemblyCatalog(typeof(App).GetTypeInfo().Assembly);

Note that since GetTypeInfo() is an extension method on 'Type' you will have to add "using System.Reflection;" to the top of your source file. You can also reference other assemblies simply by picking a type contained in that assembly and replacing ‘App’ in the above snippet.

Therefore a more complete snippet that would find and compose all imports in the current class is,

var catalog = new AssemblyCatalog(typeof(App).GetTypeInfo().Assembly);

var compositionService = catalog.CreateCompositionService();

compositionService.SatisfyImportsOnce(this);

Summary

Hopefully this post will help anybody trying to integrate MEF with their Windows 8 Metro-style app development. Ultimately there is an ‘ApplicationCatalog’ that should allow you to generate a catalog from all assemblies within the app package however there is a known bug in the Consumer Preview bits.

Using the Cocoon Data Framework

2012-04-15T20:15:00.001+01:00

Over the last series of posts I have discussed the Cocoon data framework. This aims to simplify the retrieval and display of data sets within Windows 8 Metro style applications. In particular it assists with pulling data from remote systems via typical page-based web APIs and displaying them as continuous lists.
The posts so far have covered,

Introductory post
SimpleDataListSource (for APIs that return all items from a single call)
PagedDataListSource (for APIs that return data in a paged format)
VirtualizingDataList (for data binding to display the data)

The Cocoon Sample Application

Included with the Cocoon source code (available from Codeplex) is a sample application that demonstrates there principles. This application is a simple Flickr viewer that displays the current list of “interesting” photos according to the Flickr API. Note that to compile this application you will need to register for a Flickr API key here and place this in the ‘FLICKR_API_KEY’ constant within the ‘Data/FlickrApi.cs’ file.
In this application the FlickrApi class provides basic access to the Flickr API with a single method GetInterestingPhotos() [Note: This is for demonstration purposes only and is not designed to demonstrate good practice for creating a web API client]

namespace Cocoon.Sample.Data

    public partial class FlickrApi

        // *** IMPORTANT : YOU MUST ENTER YOUR API KEY BELOW! ***

        public const string FLICKR_API_KEY = "ENTER YOUR FLICKR API KEY HERE";

        public async Task<FlickrPhotoPage> GetInterestingPhotos(int page, int perPage)

...

You will notice that this retrieves data in a paged manner, passing in the page to return as an argument and returning a FlickrPhotoPage as a result. Note also that since this is an asynchronous method call the result is returned as a Task. In the UI however we have a single scrollable list of photos, so we will use the Cocoon data framework to link these together.

Creating a New DataListSource

It is recommended that when you are using the Cocoon data framework you expose the IDataListSource implementations though a data source singleton class. Since data list sources can perform some caching of the data this allows several pages of your application to use the same underlying source. In the sample application this it the FlickrDataSource class.

namespace Cocoon.Sample.Data

    public class FlickrDataSource

        // *** Fields ***

        private FlickrApi flickrApi = new FlickrApi();

        private IList<FlickrPhoto> interestingPhotos;

        // *** Methods ***

        public IList<FlickrPhoto> GetInterestingPhotos()

            // Create a single instance of the interesting photos list

            // This can then be shared between multiple view models

            if (interestingPhotos == null)

                InterestingPhotosDataListSource dataListSource = new InterestingPhotosDataListSource(flickrApi);

                interestingPhotos = (IList<FlickrPhoto>)new VirtualizingDataList<FlickrPhoto>(dataListSource);

            return interestingPhotos;

Here we simply create an instance of our FlickrApi class along with a lazily generated InterestingPhotosDataListSource object. Whilst you can expose this to your rest of your application as is, here we also create a VirtualizingDataList<FlickrPhoto> passing the data list source into the constructor. Since this implements IList<FlickrPhoto> we can data bind to this in our UI.
The most interesting part of this is the InterestingPhotosDataListSource class – this is the class that you will need to write for each of the lists of data you wish to expose through the Cocoon data framework. As we have already discussed the Flickr API exposes the interesting photos feed as a series of pages, therefore we will derive from PagedDataListSource<FlickrPhoto>.
The three methods that we need to implement are FetchCountAsync, FetchPageSizeAsync and FetchPageAsync. Often however, as in this case, you will find that the number of items and page size are returned as part of the API call for returning the first page. Hence we only need to write an implementation of FetchPageAsync and use this to write the other two methods.

namespace Cocoon.Sample.Data

    public class InterestingPhotosDataListSource : PagedDataListSource<FlickrPhoto>

        // *** Fields ***

        private FlickrApi flickrApi;

        // *** Constructors ***

        public InterestingPhotosDataListSource(FlickrApi flickrApi)

            this.flickrApi = flickrApi;

        // *** Overriden Base Methods ***

        protected override Task<DataListPageResult<FlickrPhoto>> FetchCountAsync()

            return FetchPageAsync(1);

        protected override Task<DataListPageResult<FlickrPhoto>> FetchPageSizeAsync()

            return FetchPageAsync(1);

        protected async override Task<DataListPageResult<FlickrPhoto>> FetchPageAsync(int pageNumber)

            FlickrPhotoPage flickrPage = await flickrApi.GetInterestingPhotos(pageNumber, 20);

            return new DataListPageResult<FlickrPhoto>(flickrPage.Total, flickrPage.PerPage, flickrPage.Page, flickrPage.Photos);

In the FetchPageAsync(…) method we directly call the FlickrAPI.GetInterestingPhotos method (using the new C# async support). The result is then returned as a DataListPageResut<T> with the total number of items, the number of items per page, the page number returned, and a list of the items within that page.

Data Binding to the Data List

Since in this sample application we are using the MVVM pattern the user interface is split into two parts, the ‘InterestingPhotosPage.xaml’ and the ‘InterestingPhotosViewModel.cs’. In the view model we simple call FlickrDataSource.GetInterestingPhotos method that we wrote earlier and expose this IList<FlickrPhoto> as a property of the view model.

this.InterestingPhotos = flickrDataSource.GetInterestingPhotos();

And in the XAML we bind to this property as you would any other collection,

<CollectionViewSource

            x:Name="itemsViewSource"

            Source="{Binding InterestingPhotos}"/>

Summary

I hope that I have shown above a brief insight into the power of the Cocoon data framework. We started by writing a simple “data list source” implementation describing how to access data from a paged web UI. The framework then allows you to easily expose this as a list that can be data bound to a UI, with support for virtualization and ISupportPlaceholder for free.

VirtualizingDataList – Displaying Large Datasets

2012-03-20T21:03:00.000Z

In the last few posts I have introduced a number of features from the data framework included as part of the open-source Cocoon framework for Windows 8 Metro-style apps. Following an introduction to the framework I described the SimpleDataListSource and PagedDataListSource.
To recap, the IDataListSource implementations provide a simple way of accessing data from web APIs. These have been designed to reflect the typical structure of such APIs, generally resulting from a series of stateless HTTP requests to retrieve the data, often a page at a time.
In response to data provided from an IDataListSource, the DataList implementations are designed to request and display the information to the user. The aim here is to provide the user experience expected for a client application, with large scrolling lists of items and suitable support for background on-demand data retrieval.

Introducing The VirtualizingDataList

The first DataList implementation provided in the Cocoon data framework is the VirtualizingDataList<T> class. This can be used for situations where a large scrolling list only displays a small subset of the data at any one time. Only the data in view will be retrieved, with more data being fetched on-demand as the user scrolls through this list. In addition it supports the WinRT ISupportPlaceholder interface to indicate to the displaying UI to display a placeholder element whilst data is being retrieved in the background. This builds on top of Cocoon’s VirtualizingVector class so more information on data virtualization and placeholder support can be found in the associated post.
To use a VirtualizingDataList<T> you simply create a new instance, passing the IDataListSource via its constructor. It can then be bound to any of the many controls for displaying lists of information, most commonly the GridView and ListView controls.
If you are following the MVVM presentation pattern then you will expose the data list via a view model,

public class MyViewModel

    // *** Fields ***

    private IList<Person> employees;

    // *** Constructors ***

    public MyViewModel()

        IDataListSource<Person> source = new EmployeesDataListSource();

        employees = new VirtualizingDataList<Person>(source);

    // *** Properties ***

    public IList<Person> Employees

get

            return employees;

Then in your XAML you can define a CollectionViewSource that binds to the data list, and connect that to your items control,

<UserControl.Resources>

    <CollectionViewSource x:Name="itemsViewSource" Source="{Binding Employees}"/>

</UserControl.Resources>

...

<GridView ItemsSource="{Binding Source={StaticResource itemsViewSource}}" ... />

In fact, this is exactly what the Visual Studio 11 Metro-style XAML templates will produce for you.

Summary

In the above discussing I have shown how easy it is to consume any IDataListSource and display it to the user through the fluid scrollable user experience expected of modern applications. When I introduced the Cocoon data framework I discussed “bridging the data divide” between the stateless HTTP calls of web APIs and the continuous scrollable lists displayed to the user. By coding the former as IDataListSource implementations, and the latter as DataLists, Cocoon provides the bridge to span these two worlds.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Notes

Please note that due to a known issue with the Visual Studio templates in the Consumer Preview (see this forum post) they disable virtualization support for the GridView. Therefore although the VirtualizingVector and VirtualizingDataList classes will still work, they unfortunately fetch all items in the collection rather than on demand. To re-enable the virtualization support you can remove the ScrollViewer that surrounds the GridView, however this will clip elements a little strangely. Hopefully this will be resolved in the final release of Visual Studio, although I am working on a temporary workaround.

Update: Cocoon for Windows Consumer Preview

2012-03-18T20:29:00.001Z

Following the release of the Windows 8 Consumer preview I would like to announce that the Cocoon framework for Windows 8 Metro-style applications has been updated to support the new bits. As usual the full source code is available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

The changes include,

Code and project system migrated to the Visual Studio 11 Consumer Preview
Virtualization support converted to use the new ISupportPlaceholder interface rather than IVirtualizingVector
The VirtualizingVector class is now VirtualizingVector<T> for type-safe access
Improvements to the internal resource management
General tidying up of the codebase

PagedDataListSource – Consuming Data From Common Web APIs

2012-02-06T21:44:00.001Z

This is my third post in a series discussing the data framework that is included as part of the open-source Cocoon framework. Previously I have introduced the framework, and detailed the SimpleDataListSource base implementation.

In this post I will describe the more advanced PagedDataListSource base implementation included as part of the framework. This is designed to allow simple integration of data that is retrieved from web APIs as a series of pages. This is a common approach to enable access to large data sets in an efficient manner. In general there will be some way to retrieve the number of items in the data set, and a way to retrieve a single ‘page’ of data (often these can be combined in a single API call).

Consider for example a hypothetical web call,

http://www.example.com/api/getEmployees?page=1

This might return the following XML response,

<PersonResult TotalCount="450" Page="1" PageSize="50">

    <Person Name="Bob"/>

    <Person Name="Dave"/>

    <Person Name="Amy"/>

...

</PersonResult>

We can immediately see that there are a total of 450 employees, however the API returns only the first 50 entries. To retrieve subsequent employees you make the same call with the relevant ‘page’ query parameter.

From the point of view of a modern Windows 8 Metro style application, the user does not want to see separate pages of data. Instead they expect a continuous scrolling grid of items, with subsequent data retrieved on demand as it is required to be displayed. It is this mismatch between the paging web API and the desired UI that the PagedDataListSource and the Cocoon data framework sets out to address.

Implementing A PagedDataListSource

The PagedDataListSource<T> class in marked as abstract so you must derive a domain specific custom class for the type of data that you wish to retrieve. There are then three methods that you should override,

FetchCountAsync – This should retrieve the number of items in the data set

FetchPageSizeAsync – This should return the number of items per page

FetchPageAsync – This should return the items for a specified page

Note that each of these returns a Task<DataListPageResult<T>> as their response. DataListPageResult<T> is defined as,

public struct DataListPageResult<T>

    // *** Constructors ***

    public DataListPageResult(int? totalItemCount, int? itemsPerPage,

                              int? pageNumber, IList<T> page)

        : this()

        this.TotalItemCount = totalItemCount;

        this.ItemsPerPage = itemsPerPage;

        this.PageNumber = pageNumber;

        this.Page = page;

    // *** Properties ***

    public int? TotalItemCount { get; private set; }

    public int? ItemsPerPage { get; private set;}

    public int? PageNumber { get; private set; }

    public IList<T> Page { get; private set; }

This contains all the data that could be returned from any of the above methods. Whilst the requested information must always be present (e.g. a call to FetchCountAsync() must always return a ‘TotalItemCount’) any of the other values may be ‘null’ if they are not known.

The reason for this approach is that in many cases several of these items are returned from a single web API call – for example in the ‘getEmployees’ example above an initial call to GetFetchAsync() will not only return the number of items, but also the page size and the contents of the first page. Hence the implementation can often write FetchCountAsync() and FetchPageSizeAsync() as a simple call to FetchPageAsync(…).

So for our hypothetical ‘getEmployees’ web call we could write,

public class EmployeesDataListSource : PagedDataListSource<Person>

    // *** Overriden Base Methods ***

    protected override Task<DataListPageResult<Person>>
                           FetchCountAsync()

        return FetchPageAsync(1);

    protected override Task<DataListPageResult<Person>>
                           FetchPageSizeAsync()

        return FetchPageAsync(1);

    protected async override Task<DataListPageResult<Person>>
                                 FetchPageAsync(int pageNumber)

        PersonResult result = await ExampleEmployeesApi.
                                         GetEmployees(pageNumber);

        return new DataListPageResult<FlickrPhoto>
                      (result.TotalCount, result.PageSize,
                       result.Page, result.Items);

The Cocoon framework will then ensure that the correct pages are retrieved as required and that each web API call is only made once, with the results cached for future use.

Summary

Here I have discussed the PagedDataListSource<T> implementation of the Cocoon data framework. As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Next time I will show how you link these IDataListSource implementations with a DataList that can then be bound to your Windows 8 Metro style app’s UI. Following this I will show an end-to-end sample of how to the data framework to access a real web API and display it to the end user (Note: If you are really eager, the sample application is available from the latest code drop on the Cocoon CodePlex site).

SimpleDataListSource – Consuming Data From Simple Services

2012-01-31T22:06:00.001Z

In my last post I introduced the data framework exposed as part of the Cocoon framework project. Whilst the same principles could be applied to any presentation layer, this framework is designed from the ground up to work great with Windows 8 Metro applications written in managed .Net languages. This includes support for several of the advanced features of WinRT based UIs, such as data virtualization (which I discussed in this post).

As I discussed, Cocoon splits the passing of data from a data source into the UI with two parts. The DataListSource (represented by the IDataListSource<T> interface) describes how the data is retrieved and maps well onto the typical web service API calls to do so. At the other end of the pipeline is the DataList whose responsibility it is to determine when to retrieve the data and to present it in a format that is easily bound to the UI.

Whilst this system is designed to be easily extensible, there are a number of typical use-cases that are provided out of the box with the Cocoon framework. In this post I will describe the SimpleDataListSource.

The SimpleDataListSource Class

The SimpleDataListSource<T>, as its name suggests, is an implementation of the IDataListSource<T> interface for use with simple web APIs that return all items in a list with a single API call.

As an example consider the Flickr API method flickr.photos.people.getList that returns all the people that are tagged in a given photo. Since the number of people is likely to be relatively small the API simply takes a photo ID and returns all the people in one go, and is an ideal candidate for the SimpleDataListSource<T>. This is in contrast to a method such as flickr.interestingness.getList that returns all the interesting photos for the current day. In this case they may be many hundred items so the Flickr API splits these into several pages that are returned one at a time.

In code form we could consider this as,

public class FlickrApi

    public Task<IList<PeopleTag>> GetPeopleInPhoto(string photoId)

...

    public Task<IList<Photo>> GetInterestingPhotos(int page)

...

Implementing A Simple Data Source

Since SimpleDataSource<T> is an abstract class you must first derive a custom class for a specific data type. The only method you then are required to implement is the FetchItemsAsync() method that will initiate the call to the web API to retrieve all the items.

For our Flickr photo tagging example,

public class TaggedPeopleDataListSource : SimpleDataSource<PeopleTag>

    // *** Fields ***

    private FlickrApi flickrApi;

    private string photoId;

    // *** Constructors ***

    public TaggedPeopleDataListSource(string photoId, FlickrApi flickrApi)

        this.flickrApi = flickrApi;

        this.photoId = photoId;

    // *** Overriden Methods ***

    protected override Task<IList<PeopleTag>> FetchItemsAsync()

        return flickrApi.GetPeopleInPhoto(string photoId);

Here we firstly derive from ‘SimpleDataListSource<PeopleTag>’ (since every item in the list is of type ‘PeopleTag’). In the constructor we take the photo ID to retrieve the tagged people, and a reference to the ‘FlickrApi’ implementation. In the FetchItemsAsync() method we simply call the API method and return the result.

The underlying SimpleDataListSource<T> implementation will ensure that the web API is only called once, and will cache the results in memory for future use.

As usual the code is freely available for download from the Cocoon CodePlex site (to get the latest version go to the “Source Code” tab, select the first change set and use the “Download” link).

Next Time

Whilst simple scenarios such as those supported by the SimpleDataListSource are relatively basic to implement without the support provided by the Cocoon framework, many web APIs return paged results that are much more difficult to consume. For a fast and responsive UI these should be retrieved asynchronously and on demand as the user scrolls through a long list of items.

Next time I will introduce the PagedDataListSource that allows you to support this with minimal code. After that I will introduce the final piece in the puzzle – the DataList that can be connected to any of these DataListSources for binding to the UI. Finally I will describe a simple end-to-end example of how to use the data framework to bind to a real web service.

Bridging the Data Divide–An Introduction to Cocoon Data Lists

2012-01-17T21:33:00.000Z

When I first introduced the Cocoon framework one of the targets was to improve the ease at which data retrieval APIs (primarily web APIs) could be integrated into modern desktop applications. In this post I will introduce two concepts, the “data list” and the “data list source”, that are used in the Cocoon framework to simplify this process when writing Windows 8 Metro-style applications, in particular those implementing the MVVM design pattern.

The Data Divide

Let us first consider a typical web API that will return a list of information in response to a web request from a desktop application. In many cases there may be a large number of items in the list, so the API will split the results into several “pages”. For example, the hypothetical web call,

public Task<PersonResult> GetEmployeesAsync(int pageNumber) {...}

Might return the resulting data for pageNumber=1,

<PersonResult TotalCount="450" Page="1" PageSize="50">

    <Person Name="Bob"/>

    <Person Name="Dave"/>

    <Person Name="Amy"/>

...

</PersonResult>

Here, whilst there are a total of 450 items in the data set, only the first 50 are returned. If you then require any further items then additional calls must be made for the second, third, etc. pages as required.

In contrast let us consider a modern Windows 8 Metro-style UI. Here the user generally expects to see a single list of all items that can be scrolled through as desired. For performance reasons this list should take advantage of data virtualisation to retrieve data on demand, filling in the UI smoothly as the results are retrieved (see my last post on VirtualizingVector for more information).

It is this “data divide” between the state-less paged result sets of web APIs and the fluid continuous lists of desktop applications that often require much code to implement correctly. This is the problem that “data lists” and “data list sources” in the Cocoon framework are desired to solve.

“Data Lists” and “Data List Sources”

The approach taken by the Cocoon framework is to separate the two concerns of the web API calls (or any other data access call) and the resulting lists to display in the UI into separate components. These can then be developed separately using their own conventions, with the Cocoon framework bridging the divide.

In this model a web API call (or calls) that return information on a list of information is represented as part of a “data list source”. This understands how to query the source API to retrieve the list of data as required. In addition it is your application’s own representation of what it knows about the list of data – the length of the data set, and any items that have already been downloaded. This can be reused amongst different parts of your application and in some ways acts as a local cache of the data. Multiple data list sources will be available, for simple cases where all data is returned at once and for data that is returned by pages, as well as the option for custom implementations.

At the other end of the chain is the “data list”. This is the IList<T> implementation that is bound to the UI, either via the code behind or through a view model. Multiple data lists can be attached to the same data list source so that the application’s view of the data is consistent. Different data list implementations can determine how the data is retrieved for display; for example,

StaticDataList – This will retrieve all the information before display to the user
VirtualizingDataList – This will use data virtualization to only retrieve the data items that are currently visible to the user
IncrementalLoadingDataList – This will initially show a fixed number of items, but allow the user to expand the list if they wish to see more items
DynamicDataList – This will start with an empty list, with items being added as they are retrieved from the data list source

Between the data list and the data list source are a number of optional processing steps. For example these could constrain the list to only the first 50 items for preview, they could filter the items based on a search term, or could group the items to display as part of a grouped grid view.

The IDataListSource Interface

All of the above is orchestrated by the Cocoon.Data.IDataListSource<T> interface.

public interface IDataListSource<T>

    Task<int> GetCountAsync();

    Task<T> GetItemAsync(int index);

You can think of this as an asynchronous version of IList<T>, albeit a minimal version. There are two methods:

GetCountAsync() – Returns a task that results in the number of items in the list.

GetItemAsync(int index) – Returns a task that results in the item at the specified index.

Note that the GetItemAsync(…) method should throw an exception if ‘index’ is less than zero, however if ‘index’ is greater than the last item it should return default(T) (for reference types this will be null).

Summary

To summarize, the Cocoon framework supplies an infrastructure designed to bridge the gap between state-less web APIs and modern fluid Windows 8 Metro style applications. Over the next few blog posts (and associated code drops) I will provide a number of generic implementations of data lists and data list sources to make consuming lists of data from the web quick and easy.