Andy On WPF, Windows 8 and Beyond

Okra App Framework for Windows 10 Universal

2015-08-28T09:43:00.002+01:00

[Cross posted from the official Okra App Framework blog]

Okra App Framework v1.2

With the release of Windows 10, Microsoft have introduced the Universal Windows Platform with a single API set and one app package to target PCs, tablets, phones and more. Today’s release of version 1.2 of the Okra App Framework allows you to write apps that target Windows 10 devices.

New in version 1.2 is,

Windows 10 UAP support - Use the MVVM pattern to write a single app that runs on PCs, tablets and phones running Windows 10.
Windows 10 UAP Visual Studio Template - A basic Visual Studio template is available to get you started with developing Windows 10 apps.
Advanced Windows 10 features include,
- Compiled binding support (see below)
- Automatic support for hardware back buttons and tablet mode

You can get the Okra App Framework now by installing the Visual Studio extension, from NuGet or via GitHub. Full details on how to download the framework are available here.

Windows 10 Compiled Binding Support

Since the MVVM pattern relies heavily on data binding to bind the UI to the underlying view-model, data binding performance is very important. The Universal Windows Platform introduces “compiled binding” as a high performance data binding system.

To use compiled bindings you use the new x:Bind syntax,

<TextBlock Text="{x:Bind ViewModel.Title}"/>

Note however that these bindings do not bind to the DataContext, but instead to the page itself. To support this, the Okra App Framework v1.2 introduces the IViewModelBindable interface. This is applied to the page code-behind as shown below,

public sealed partial class MyPage : Page, IViewModelBindable
{
    ...

    public HomeViewModel ViewModel
    {
        get;
        private set;
    }

    public void SetViewModel(object viewModel)
    {
        this.ViewModel = viewModel as HomeViewModel;
        Bindings.Update();
    }
}

You can now take advantage of type-safe, high performance data binding using the x:Bind syntax in your Windows 10 projects.

Okra App Framework for Windows Phone 8.1 Released

2015-06-29T18:04:00.000+01:00

Okra App Framework v1.1

I’m pleased to announce that version 1.1 of the Okra App Framework has been released. For Windows 8.1 development there is not much new to report - the same great MVVM framework designed with Windows apps in mind. The big news however is the official release of Windows Phone 8.1 support - it has been a couple of months since the beta release and I’ve no bug reports so here it is.

In summary the new NuGet packages include,

Windows 8.1 support - Create a new project using the Visual Studio templates and start using the MVVM pattern straight away.
Windows Phone 8.1 support - Simply add a new Windows Phone 8.1 project and reference the NuGet package. The programming model is the same as for Windows 8.1, and most of your code should be sharable between projects.
Portable Class Library support - In addition, a PCL version is included. This allows sharing of logic and view-models in a single portable binary between Windows and Windows Phone projects.

You can get the Okra App Framework now by installing the Visual Studio extension, from NuGet or via GitHub. Full details on how to download the framework are available here.

Windows 10, Android and iOS

In other news, Windows 10 support has now been merged into the master branch of the framework. Unfortunately NuGet currently does not have platform support for Windows 10, so this is not available via the NuGet packages. If you wish to experiment with the latest bits you can download and build the source code from the Okra.Core project on GitHub.

Additionally, many thanks go to Joel Fjordén who has made a start on Android and iOS support via Xamarin.Forms. This is only the start, but if you want to experiment with cross-platform development then there are specific NuGet packages on the Okra pre-release feed at https://www.myget.org/F/okra/ (add this in the NuGet settings and make sure you have prerelease packages enabled).

Okra App Framework for Windows Phone 8.1 (beta)

2015-04-26T15:53:00.003+01:00

[Cross posted from the Okra Framework blog]

Okra App Framework for Windows Phone 8.1

Following on from the recent v1.0 release of the Okra App Framework, preview support for Windows Phone 8.1 is now available. This will be wrapped up in an upcoming v1.1 release, but as of today a beta release is downloadable via NuGet (turn on support for preview versions and look for the v1.1.0-beta001 package).

This package includes,

Windows Phone 8.1 support - Simply add a new Windows Phone 8.1 project and reference the NuGet package. The programming model is the same as for Windows 8.1, and most of your code should be sharable between projects.
Portable Class Library support - In addition a PCL version is included, which allows sharing of logic and view-models in a single portable binary between Windows and Windows Phone projects.

Get in touch with any bugs or comments via the Okra.Core issue tracker.

Okra App Framework for Windows 10

In addition to the beta relase, progress is going well on a Windows 10 port of the Okra App Framework. Whilst this is not currently available via NuGet, you can check out and build the code via the Okra.Core/win-10 branch.

Okra App Framework v1.0 Released

2015-04-10T19:46:00.000+01:00

[Cross posted from the new Okra Framework blog]

I am really happy to announce that version 1.0 of the Okra App Framework has officially been released. For those new to the framework, it is an MVVM framework designed from the ground up to be great for creating Windows apps. Dependency injection is baked in to allow you to create easy to maintain, test and reuse code. A number of advanced features allow simple integration with application settings, app-to-app sharing and search. In addition a full set of Visual Studio templates is available to get you started with MVVM development.
For more information checkout the Okra Framework website.
You can get the Okra App Framework now by installing the Visual Studio extension, from NuGet or GitHub. Full details on how to download the framework are available here.
In addition to the release of the framework we have,

Changes from v0.9.8

Settings panes can now derive from SettingsFlyout - This allows you to use the full Visual Studio designer experience for the settings pane UI
The Visual Studio settings pane template now derives from SettingsFlyout by default
All classes/methods/properties/events marked as obsolete in v0.9.8 have been removed for the v1.0 release
A number of other minor bug fixes

Okra App Framework vNext

The next step for the Okra App Framework v1.1 is to support other platforms, in particular Windows Phone 8.1 and preview support for Windows 10. Much of the development on these features is already complete so expect to see a beta release in the near future. You can check out progress and submit bugs and feature requests on the Okra.Core issue tracker. For more information on feature progress on the v1.1 release you can look at the v1.1.0 milestone progress page.

Okra App Framework v0.9.8

2014-10-27T21:17:00.001+00:00

For those of you following the Okra App Framework, I can announce that v0.9.8 has been released today. This release is mainly aimed at converging on a stable API for v1.0, although a small number of new features have also been included.

Details of how to obtain the latest version of the framework are available here. In the approach to v1.0 I’d be very interested in any feedback and bug reports, which you can post in the Okra.Core issues tracker.

New Features in v0.9.8

You can now navigate back multiple pages in the navigation stack, for example directly to the application home page from deep in the navigation hierarchy. This is supported by an INavigationStack.GoBackTo(…) method and associated extension methods.
Built in support for keyboard back navigation.
Built in support for mouse back button navigation.
Support for variable-sized settings panes has been reintroduced. The width can be set using a SettingsPaneInfo.Width property in your XAML.
A number of minor bug fixes.

Code Changes When Updating From v0.9.7

In readiness for a v1.0 release, a number of breaking changes have been made,

Any methods that return or consume the WinRT ‘NavigationMode’ enumeration now use an Okra specific ‘PageNavigationMode’ enumeration.
Sharing support (for both share targets and share sources) has been moved into a new ‘Okra.Sharing’ namespace along with a number of changes to the API surface. This removes dependencies to WinRT types and allows sharing code to be included in portable class libraries.
The INavigationTarget.NavigateTo(…) method now takes an associated INavigationBase as a second parameter.
The FlyoutPane class and FlyoutEdge enumeration have been marked as obsolete and will be removed prior to v1.0. If you still require this control then feel free to include the source code directly in your solution (FlyoutPane code, FlyoutEdge code).

New Website for the Okra Framework

2014-08-10T21:45:00.001+01:00

In addition to moving to GitHub I would like to announce that the Okra Framework has a new website. Find us at,

http://okraframework.github.io/

This website is the new location for information about the framework and all official documentation. Since it is hosted using GitHub Pages you can also contribute to the documentation by submitting a pull request to the website repository.

Look forward to seeing you all there…

Okra Framework is now on GitHub

2014-08-10T21:39:00.001+01:00

Anyone who has been following the Okra App Framework (an MVVM framework designed for creating great Windows 8 apps) will know that up until now the project has been hosted on CodePlex. From this point onwards all further development will be based on GitHub. The new url is,

https://github.com/OkraFramework

On the new GitHub site you will find,

All the source code for Okra.Core and Okra.Data
All releases from v0.9.7 going forward
A new issue tracker for managing bug reports and feature requests (I have migrated all open issues from CodePlex)
Okra feature samples as part of the Okra-Samples repository

Contributing to the Okra Framework

As part of the move to GitHub I am aiming to be more proactive in accepting any community contributions to the project. The first thing I would welcome is the continued submission of bug reports and feature requests to the Okra.Core issue tracker and the Okra.Data issue tracker. I’m always interested in hearing in how users are using the framework and any problems they encounter.

If you would like to contribute any code to the project then I’d be really happy to accept pull requests (no matter how small). Try to keep these focused on one issue per pull request (this helps me get an overview of the changes before I merge them) and for anything but small bug fixes open an issue in the issue tracker first (so we can discuss the best way to approach it). Some simple contribution guidelines are available in the CONTRIBUTING.md file at the root of each project.

Windows Store MVVM Development with the Okra App Framework v0.9.7

2014-07-07T20:22:00.000+01:00

After a bit of hiatus, the latest version of the Okra App Framework has been released. The v0.9.7 release of the Windows Store centric MVVM framework targets Windows 8.1, and focuses on tidying up some of the API surface prior to an upcoming v1.0 release.

How to Get The Okra App Framework

You can download the latest version of the Okra App Framework,

From NuGet: For the complete MVVM framework add the “Okra App Framework” NuGet package to your project.
Using the Visual Studio Extension: The official Okra App Framework Visual Studio extension has been updated for the latest release with all new project and item templates targeting Windows 8.1. Look for the “Windows Store MVVM Templates for the Okra App Framework” extension in the Visual Studio gallery or directly from the Extensions and Updates manager in Visual Studio.

New Features in This Release

The big change with this update is that the Okra App Framework is now targeting Windows 8.1 development. The framework makes the most of the recent improvements in the underlying operating system, with a number of changes reflecting the new API surface. Note however that this release no longer supports Windows 8.0 projects, which should continue to use v0.9.6.
All new Windows 8.1 project and item templates for Visual Studio. These are based upon the Visual Studio 2013 templates, but rewritten to take advantage of the MVVM pattern.
The Okra Data Framework is now available as a separate download (see the “Okra App Framework (Data Framework)” package in NuGet) so you can choose to use this independently of the core framework if desired.

Code Changes When Updating From v0.9.6

In readiness for a v1.0 release, a number of breaking changes have been made,

To simplify page activation the IActivatable interface in no longer generic. Instead of directly passing the page arguments and state, a PageInfo object is used instead.

// Old code using the Okra App Framework v0.9.6 public class MyViewModel : ViewModelBase, IActivatable<string, string>{    ...     public void Activate(string arguments, string state)    {        this.Photo = GetPhoto(arguments);        this.State = state;    }     public string SaveState()    {        return this.State;    }} // New code using the Okra App Framework v.0.9.7 public class MyViewModel : ViewModelBase, IActivatable{    ...     public void Activate(PageInfo pageInfo)    {        string arguments = pageInfo.GetArguments<string>();        this.Photo = GetPhoto(arguments);        this.State = pageInfo.GetState<string>("MyState");    }     public void SaveState(PageInfo pageInfo)    {        pageInfo.SetState<string>("MyState", this.State);    }}

To allow more flexible navigation patterns a number of properties and methods have been moved from INavigationBase to INavigationStack (accessible from any INavigationBase via the NavigationStack property).
Since the Windows 8.1 update includes a system provided SettingsFlyout control, you no longer need to wrap any settings pages in a SettingsChrome control.

Sharing App Content using MVVM and the Okra App Framework

2013-05-29T21:03:00.002+01:00

One of the key differentiating features of the Windows Store application model in Windows 8 is the availability of system provided “charms” for common tasks such as sharing, search and application settings. In this post I will focus on sharing, and how the Okra App Framework makes it easy to incorporate this functionality into applications using the MVVM pattern.

How to share content the Windows 8 way?

The MSDN documentation details how to share content from Windows Store apps in C#/VB. The first step is to get a reference to the application’s DataTransferManager, and then register for its DataRequested event. When the user selects the share charm this event is fired, passing a DataRequestedEventArgs object to the event handler.

There are a number of problems with this approach in the context of an MVVM application,

The content to share should be determined dynamically based upon the page displayed and any user selected content. In the MVVM pattern this is best accomplished by the view-model, and not by a single event handler.
The application specific sharing code is passed a DataRequestedEventArgs object (which is a sealed class with no public constructors). This makes unit testing this code difficult.
Supporting pull operations (see the MSDN documentation on this topic) requires additional event handler registration, not following the typical Task based async support used elsewhere.

Sharing content with the Okra App Framework

The Okra App Framework overcomes these problems, whilst maintaining the power of the sharing contract by allowing view-models to implement a simple, easily unit-testable, IShareable interface. The framework will handle all the other infrastructure required for application sharing. Since the IShareable interface is applied to the view-model, a ‘ViewPhoto’ page can share an individual photo, whilst a ‘ViewAlbum’ page can share the whole album (or selected photos if the user has done so).

The first step in adding sharing support to an application is to add a reference to an IShareSourceManager in the application bootstrapper.

public class AppBootstrapper : OkraBootstrapper

    [Import]

    public IShareSourceManager ShareSourceManager { get; set; }

You can then add the IShareable interface to any view-model that has suitable data to share,

[ViewModelExport("MyPage")]

public class MyViewModel : IShareable

    public void ShareRequested(IDataRequest dataRequest)

...

You will notice that the ShareRequested method is passed an IDataRequest object in which to return the data to share. This is a unit-testable wrapper around the WinRT DataRequest object and the standard MSDN documentation can be followed from this point to respond to the share request. For example to share some text you would implement this as follows,

[ViewModelExport("MyPage")]

public class MyViewModel : IShareable

    public void ShareRequested(IDataRequest dataRequest)

        dataRequest.Data.Properties.Title = "...";

        dataRequest.Data.Properties.Description = "...";

        request.Data.SetText("Hello World!");

Sharing content asynchronously (optional)

There are occasions when you may wish to only download the data once the user has completed the share request (e.g. when sharing a large file from a web service) – these are known as pull operations. The Okra App Framework provides extension methods to allow you to implement pull operations using the async features of .Net. For each SetXXX(…) method, Okra provides a corresponding SetAsyncXXX(…) method. For example, the code below demonstrates how to return text returned from some async method call. Note the signature of the GetShareTextAsync(…) method.

[ViewModelExport("MyPage")]

public class MyViewModel : IShareable

    public void ShareRequested(IDataRequest dataRequest)

...

        request.Data.SetAsyncText(GetShareTextAsync);

    private async Task<string> GetShareTextAsync(string formatId, DateTimeOffset deadline)

        string text = await SomeAsyncMethod();

        return text;

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.000+00:00

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.001+00:00

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.001+00:00

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.001+00:00

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.001+00:00

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.001+00:00

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).