Sunday, March 24, 2013

Improvements in Version 0.9.6 of the Okra App Framework

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

Thursday, March 21, 2013

Okra App Framework v0.9.6 Released

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.