Monday, October 27, 2014

Okra App Framework v0.9.8

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

Sunday, August 10, 2014

New Website for the Okra Framework

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

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.

Monday, July 07, 2014

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.

Wednesday, May 29, 2013

Sharing App Content using MVVM and the Okra App Framework

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;
    }
}

Sunday, May 12, 2013

Windows Store MVVM Templates for Visual Studio

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.

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