Sunday, April 26, 2015

Okra App Framework for Windows Phone 8.1 (beta)

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

Friday, April 10, 2015

Okra App Framework v1.0 Released

[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

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.

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