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

Cocoon Navigation – Passing Arguments Between Pages

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

Passing Arguments to ViewModels

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

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

public interface INavigationManager

{

    ...

    void NavigateTo(string pageName);

    void NavigateTo(string pageName, object arguments);

}

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

• The type should be able to be serialized via a DataContractSerializer


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

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

[ViewModelExport("BrowsePhotos")]

public class BrowsePhotosViewModel

{

    // *** Fields ***

    private readonly INavigationManager navigationManager;

    // *** Constructors ***

    [ImportingConstructor]

    public BrowsePhotosViewModel(INavigationManager navigationManager)

    {

        this.navigationManager = navigationManager;

    }

    // *** Command Methods ***

    public void ViewPhoto(Photo photo)

    {

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

    }

}

Activating Destination Pages

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

public interface IActivatable<TArguments, TState>

{

    // *** Methods ***

    void Activate(TArguments arguments, TState state);

    TState SaveState();

}

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

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

[ViewModelExport("ViewPhoto")]

public class ViewPhotoViewModel : IActivatable<string, string>

{

    ...

    // *** IActivatable Methods ***

    public void Activate(string arguments, string state)

    {

        this.Photo = GetPhoto(arguments);

    }

    public string SaveState()

    {

        return null;

    }

    // *** Private Methods ***

    private Photo GetPhoto(string photoId)

    {

        ...

    }

}

Summary

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

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

Getting Started with Cocoon Navigation – The Cocoon Bootstrapper

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

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

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

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

Launching Navigation Using The Cocoon Bootstrapper

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

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

public class AppBootstrapper : CocoonBootstrapper

{

}

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

sealed partial class App : Application

{

    public App()

    {

        this.InitializeComponent();

        // Create and initialize the application bootstrapper

        AppBootstrapper bootstrapper = new AppBootstrapper();

        bootstrapper.Initialize();

    }

}

Defining the Application Home Page

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

Therefore the home page view is annotated as,

[PageExport(SpecialPageNames.HomePage)]

public sealed partial class HomePage : LayoutAwarePage

{

    public HomePage()

    {

        this.InitializeComponent();

    }

}

and the view model annotated as,

[ViewModelExport(SpecialPageNames.HomePage)]

public class HomeViewModel

{

    ...

}

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

Summary

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

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