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

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.

Settings Panes and the Okra App Framework

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,

1. Create a UserControl with the desired UI and set the PageExport attribute.
2. Optionally add a view-model attributed with the ViewModelExport attribute.
3. 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.

Convention Based Page Discovery With The Okra App Framework

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.

Cocoon is now the Okra App Framework

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.

Cocoon Updated for Windows 8 Release Preview

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,

1. Right click on your projects ‘References’ folder and select “Manage NuGet Packages…”
2. Select “Online” in the left-hand pane and make sure that you have “Include Prerelease” selected rather then “Stable Only” at the top.
3. Use the search box to search for “MEF”
4. 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”

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