Magellan

Updated Wiki: Documentation

stovellp — Tue, 01 Feb 2011 14:21:22 GMT

See the Google Code Magellan wiki

Updated Wiki: Home

stovellp — Tue, 01 Feb 2011 14:17:20 GMT

Magellan has moved to Google Code. Go there now.

New Post: Default Transitions

CoolDadTx — Thu, 11 Nov 2010 16:02:16 GMT

In the discussion of transitions it points out that you have to define a transition for each mapping. Not really sure why you'd ever want to do that in most applications. In general you'd want one transition that impacts everybody and, perhaps, override the default for specific cases. To this end Magellan needs to expose the ability to set a default transition that applies to navigation except when specifically overridden either for a specific mapping (such as to an error page) or programmatically via the API.

Someone posted this in the feedback for the article and you mentioned that you'd try to post a simple implementation but I haven't seen anything since then.

New Post: Better Error Handling

CoolDadTx — Thu, 11 Nov 2010 15:59:30 GMT

Currently you can handle some errors during navigation by writing an action or result filter. But this only covers some of the cases. Ideally Magellan should allow us to handle any navigation error in a central location. For example it doesn't make a lot of sense to create an action filter that we then have to apply to each controller just to get consistent behavior. We should be able to specify that when a navigation error occurs do something irrelevant of the controller. This would become the default behavior (that controllers could override with filters).

Even more critical, some errors can't be dealt with using filters. Specifically if you enter a URL that doesn't match a controller then Magellan throws an exception. In order to handle this case we'd have to wrap all calls to Navigate in try-catch blocks. Since we generally want the same behavior it would be better if we could hook into either events off the navigator (or perhaps derive our own type and override some methods) to handle navigation errors. This would allow us, for example, to redirect to an error page or a "file not found" page when an error occurs.

New Post: External Navigation Support

CoolDadTx — Thu, 11 Nov 2010 15:55:29 GMT

Magellan seems pretty cool but it really needs support for going to URLs outside the application. I'm thinking either web sites or even custom URLs (definable by creating a new URI parser and registering it with .NET). Right now if you try to navigate to an external site then you'll get an exception. While you could just skip Magellan for these particular cases it causes the code to break down pretty quickly. Firstly you have to special case anywhere where you'd normally want to navigate to first check to see if it is an external URL. The second, even more annoying, problem is that Back/Forward won't work outside Magellan-managed pages. I've tried to create a route catalog to handle external sites but it seems that the catalog has to be aware of all routes rather than the navigator simply asking the catalog if it can handle the URL.

Ideally what would need to happen is that Magellan allows for navigation to external URLs. When switching to an external URL Magellan would need to hook into the WPF NavigationService to allow the Back/Forward commands to continue to work correctly.

New Post: What about Page lifetime?

heeroyui1777 — Fri, 15 Oct 2010 04:20:17 GMT

I was feeling like during execution with Magellan 2.0, it was recording strong references to unused pages as opposite to default WPF Navigation behavior. Someone could confirm it?

Garbage collector could incur in high memory volume missed to collect.

Updated Wiki: Home

stovellp — Sun, 22 Aug 2010 16:51:11 GMT

Magellan is moving to Google Code

Magellan 1.1 (stable) for VS 2008 is documented and available on this CodePlex site
Magellan 2.0 (unstable) for VS 2010/.NET 4.0 is undocumented, but source code is available from Google Code

What is it?

Magellan is a lightweight MVC framework that makes it easy to build WPF navigation applications. It is inspired by the ASP.NET MVC framework, and it should feel familiar to anyone who has worked with ASP.NET MVC.

The main features are:

Model-View-Controller framework
Blend behaviors and Commands to make navigation easy
Transitions between pages
Action filters for cross-cutting concerns such as authorization and redirection
Integration with Composite WPF

Applications built using Magellan still make use of common patterns such as MVP and MVVM; Magellan just provides navigation support.

Getting Started

Documentation

Integration

Advanced Features

Updated Wiki: Home

stovellp — Sun, 22 Aug 2010 14:52:37 GMT

Magellan is moving to Google Code

Magellan 1.1 (stable) for VS 2008 is documented and available on this CodePlex site
Magellan 2.0 (unstable) for VS 2010/.NET 4.0 is undocumented, but source code is available from http://code.google.com/p/magellan-framework

What is it?

Model-View-Controller framework
Blend behaviors and Commands to make navigation easy
Transitions between pages
Action filters for cross-cutting concerns such as authorization and redirection
Integration with Composite WPF

Applications built using Magellan still make use of common patterns such as MVP and MVVM; Magellan just provides navigation support.

Getting Started

Documentation

Integration

Advanced Features

Updated Wiki: Home

stovellp — Sun, 22 Aug 2010 14:52:17 GMT

Magellan is moving to Google Code

Magellan 1.1 (stable) for VS 2008 is documented and available on this CodePlex site
Magellan 2.0 (unstable) for VS 2010/.NET 4.0 is undocumented, but source code is available from http://code.google.com/p/magellan-framework

---

What is it?

Model-View-Controller framework
Blend behaviors and Commands to make navigation easy
Transitions between pages
Action filters for cross-cutting concerns such as authorization and redirection
Integration with Composite WPF

Applications built using Magellan still make use of common patterns such as MVP and MVVM; Magellan just provides navigation support.

Getting Started

Documentation

Integration

Advanced Features

Updated Wiki: Documentation

stovellp — Sun, 22 Aug 2010 14:43:59 GMT

Updated Wiki: Home

stovellp — Sun, 22 Aug 2010 14:43:51 GMT

What is it?

Model-View-Controller framework
Blend behaviors and Commands to make navigation easy
Transitions between pages
Action filters for cross-cutting concerns such as authorization and redirection
Integration with Composite WPF

Applications built using Magellan still make use of common patterns such as MVP and MVVM; Magellan just provides navigation support.

Getting Started

Documentation

Integration

Advanced Features

Updated Wiki: magellan-diagnostics

stovellp — Sun, 22 Aug 2010 14:43:22 GMT

Magellan makes use of TraceSources internally for providing diagnostic information. By default nothing is traced, but you can configure the trace sources to see details.

Configuring the trace sources can be done through the application configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <source name="Magellan" switchValue="Verbose">
        <listeners>
          <clear />
          <add name="Console" type="System.Diagnostics.ConsoleTraceListener" />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
</configuration>

Or through code, for example, in the App.xaml code behind:

Magellan.Diagnostics.TraceSources.MagellanSource.Switch.Level = SourceLevels.Verbose;

Here is an example of what is logged at the Information level:

Magellan Information: 0 : The Navigator is executing the request 'Controller=Home; Action=Home; RequestID=6ce8e373-f2d9-48d0-b1c2-9438094feeaf'.
Magellan Information: 0 : Controller 'iPhone.Applications.Home.Controllers.HomeController' is executing request 'Controller=Home; Action=Home; RequestID=6ce8e373-f2d9-48d0-b1c2-9438094feeaf'.
Magellan Information: 0 : The PageViewEngine is rendering the page 'iPhone.Applications.Home.Views.HomeView'.
Magellan Information: 0 : Request completed: 'Controller=Home; Action=Home; RequestID=6ce8e373-f2d9-48d0-b1c2-9438094feeaf'.

Here is what is logged at the Verbose level:

Magellan Information: 0 : The Navigator is executing the request 'Controller=Home; Action=Home; RequestID=2704ddc6-0dca-412f-88fc-b08a008ee586'.
Magellan Verbose: 0 : Resolving controller 'Home' for request 'Controller=Home; Action=Home; RequestID=2704ddc6-0dca-412f-88fc-b08a008ee586'
Magellan Information: 0 : Controller 'iPhone.Applications.Home.Controllers.HomeController' is executing request 'Controller=Home; Action=Home; RequestID=2704ddc6-0dca-412f-88fc-b08a008ee586'.
Magellan Verbose: 0 : DefaultActionInvoker found the action 'Home' as method 'Magellan.Framework.ActionResult Home()'
Magellan Verbose: 0 : DefaultActionInvoker found the following action filters for action 'Home': ''.
Magellan Verbose: 0 : DefaultActionInvoker found the following result filters for action 'Home': ''.
Magellan Verbose: 0 : The ViewEngineCollection is consulting the view engine 'Magellan.Framework.PageViewEngine' for the view 'Home'.
Magellan Information: 0 : The PageViewEngine is rendering the page 'iPhone.Applications.Home.Views.HomeView'.
Magellan Verbose: 0 : The PageViewEngine has navigated to the page 'iPhone.Applications.Home.Views.HomeView'.
Magellan Verbose: 0 : The PageViewEngine is clearing the navigation history.
Magellan Information: 0 : Request completed: 'Controller=Home; Action=Home; RequestID=2704ddc6-0dca-412f-88fc-b08a008ee586'.

The Warning and Error levels are rarely used - warning is used when Magellan decides on a course of action that is potentially incorrect, and errors are usually logged before an exception is thrown.

Updated Wiki: magellan-async-controllers

stovellp — Sun, 22 Aug 2010 14:42:10 GMT

Magellan 1.1 brings support for asynchronous controllers. First we'll look at what it enables, then I will show some ways to configure it.

The controller action below makes a WCF call to load a list of customers, which are used as the model for the view. This service call could take some time to evaluate:

public class CustomerController : Controller
{
    public ActionResult List()
    {
        Model = CustomerService.GetCustomers();
        return Page("CustomerList");
    }
}

With asynchronous controllers enabled, Magellan will invoke the List action on a background thread. Since page navigation has to take place on the UI thread, the page rendering will be automatically dispatched to the UI thread, but this happens after the controller action has been executed. The result is that the UI remains snappy and responsive.

Enabling Asynchronous Controllers

There are three simple options for enabling asynchronous controllers. The first option is to inherit from AsyncController instead of Controller:

public class CustomerController : AsyncController

The second option is to assign the AsyncActionInvoker when the controller is constructed (this is actually what both AsyncControllerFactory and AsyncController do):

public class CustomerController : Controller
{
    public CustomerController() 
    { 
        ActionInvoker = new AsyncActionInvoker();
    }
}

The preferred approach is to rely on controller factories to set the action invoker. Instead of using CoontrollerFactory, you can use AsyncControllerFactory:

var controllerFactory = new AsyncControllerFactory();
controllerFactory.Register("Home", () => new HomeController());
controllerFactory.Register("Customer", () => new CustomerController());

If you are using a custom controller factory, you just need to replace the ActionInvoker - for example:

public ControllerFactoryResult CreateController(NavigationRequest request, string controllerName)
{
    var controller = // Create controller
    if (controller is ControllerBase)
    {
        ((ControllerBase) controller).ActionInvoker = new AsyncActionInvoker();
    }
    return new ControllerFactoryResult(controller);
}

Reporting Progress

Now that navigation is occurring on a background thread, it's nice to show a progress indicator while navigation is happening. For this, Magellan now provides an INavigationProgressListener interface that you can implement.

public interface INavigationProgressListener
{
    void UpdateProgress(NavigationRequest request, NavigationStage navigationStage);
}

For example, the code behind for the Window is going to show a progress bar:

public partial class MainWindow : Window, INavigationProgressListener
{
    public MainWindow()
    {
        InitializeComponent();
        NavigationProgress.Listeners.Add(this);
        Loaded += (x, y) => Navigator.For(Frame).NavigateWithTransition("Home", "Home", "ZoomIn");
    }

    public void UpdateProgress(NavigationRequest request, NavigationStage navigationStage)
    {
        Dispatcher.Invoke(
            new Action(delegate
            {
                switch (navigationStage)
                {
                    case NavigationStage.BeginRequest:
                        ProgressBar.Visibility = Visibility.Visible;
                        break;
                    case NavigationStage.Complete:
                        ProgressBar.Visibility = Visibility.Collapsed;
                        break;
                }
            }));
    }
}

The iPhone sample application uses a spinning circle to indicate navigation progress:

The NavigationStage enum provides an indication as to where the request is up to. The table below explains each state:

Step Stage Description
1 BeginRequest This occurs at the start of the navigation request before the controller has been resolved.
2 ResolvingController This indicates that the controller is about to be resolved by name from the current controller factory.
3 ResolvingAction This indicates that the controller has been resolved, and the action is now about to be resolved.
4 PreActionFilters This indicates that the action has been resolved, and pre-action filters are about to be invoked.
5 ExecutingAction This indicates that pre-action filters have been invoked, and the action is about to to executed. This event does not always occur (pre-action filters can cancel the navigation request, for example).
6 PostActionFilters This indicates that the action has been invoked, and post-action filters are about to to executed. This event does not always occur (pre-action filters can cancel the navigation request, for example).
7 PreResultFilters This indicates that the action has been executed and all action filters have been invoked. The result is now about to be evaluated. This event does not always occur (action filters can cancel the navigation request, for example).
8 ExecutingResult This indicates that the pre-result filters have been executed, and the result is about to be executed (this is typically when views are rendered). This event does not always occur (action filters or pre-action filters can cancel the navigation request, for example).
9 PostResultFilters This indicates that the result has been executed (and views have been rendered) and the post-result filters are about to be executed.
10 Complete This indicates that the navigation request has been completed (whether successfully or failed), any views have been rendered and any resources from the navigation request have been cleared up.

Summary

The benefit of this approach is that controller code is the same whether we are using single threads or background threads, which also allows unit tests to remain singly threaded while at runtime the application is multi-threaded. Enabling this feature is quite easy, and so long as your controllers don't depend on the UI thread it should Just Work.

Updated Wiki: magellan-async-controllers

stovellp — Sun, 22 Aug 2010 14:41:02 GMT

public class CustomerController : Controller
{
    public ActionResult List()
    {
        Model = CustomerService.GetCustomers();
        return Page("CustomerList");
    }
}

Enabling Asynchronous Controllers

There are three simple options for enabling asynchronous controllers. The first option is to inherit from AsyncController instead of Controller:

public class CustomerController : AsyncController

The second option is to assign the AsyncActionInvoker when the controller is constructed (this is actually what both AsyncControllerFactory and AsyncController do):

public class CustomerController : Controller
{
    public CustomerController() 
    { 
        ActionInvoker = new AsyncActionInvoker();
    }
}

The preferred approach is to rely on controller factories to set the action invoker. Instead of using CoontrollerFactory, you can use AsyncControllerFactory:

var controllerFactory = new AsyncControllerFactory();
controllerFactory.Register("Home", () => new HomeController());
controllerFactory.Register("Customer", () => new CustomerController());

If you are using a custom controller factory, you just need to replace the ActionInvoker - for example:

public ControllerFactoryResult CreateController(NavigationRequest request, string controllerName)
{
    var controller = // Create controller
    if (controller is ControllerBase)
    {
        ((ControllerBase) controller).ActionInvoker = new AsyncActionInvoker();
    }
    return new ControllerFactoryResult(controller);
}

Reporting Progress

public interface INavigationProgressListener
{
    void UpdateProgress(NavigationRequest request, NavigationStage navigationStage);
}

For example, the code behind for the Window is going to show a progress bar:

public partial class MainWindow : Window, INavigationProgressListener
{
    public MainWindow()
    {
        InitializeComponent();
        NavigationProgress.Listeners.Add(this);
        Loaded += (x, y) => Navigator.For(Frame).NavigateWithTransition("Home", "Home", "ZoomIn");
    }

    public void UpdateProgress(NavigationRequest request, NavigationStage navigationStage)
    {
        Dispatcher.Invoke(
            new Action(delegate
            {
                switch (navigationStage)
                {
                    case NavigationStage.BeginRequest:
                        ProgressBar.Visibility = Visibility.Visible;
                        break;
                    case NavigationStage.Complete:
                        ProgressBar.Visibility = Visibility.Collapsed;
                        break;
                }
            }));
    }
}

Summary

Updated Wiki: magellan-windows-forms

stovellp — Sun, 22 Aug 2010 14:38:01 GMT

Magellan does not natively support Windows Forms, but adding support is as easy as writing your own View Engine.

As described in the documentation on View Engines, there are two classes we need to write. The first is an object that implements IViewEngine, which is responsible for finding the view. The second is an object inheriting from ViewEngineResult, which contains logic for rendering the form (i.e., calling Form.Show()).

There are also a couple of design considerations:

Magellan controllers like to create View Models, and it's the ViewEngineResult's job to make them available for binding on the view.
Windows Forms applications typically use naming conventions like frmCustomerDetails, CustomerDetailsForm or CustomerDetailsWindow. Our engine should support these.

Binding Models to Forms

To support the model, we're going to create an interface that allows the model to be given to the form. The form can then figure out how to display the model (either using a Windows Forms BindingContext, or manual code).

public interface IBindableForm
{
    void Bind(object model);
}

Our form implementation could look like this:

public partial class MainForm : Form, IBindableForm
{
    public MainForm()
    {
        InitializeComponent();
    }

    public void Bind(object model)
    {
        Text = model.ToString();
    }
}

The Controller

Here is what our Controller might look like:

public class HomeController : Controller
{
    public ActionResult Launch()
    {
        Model = "Hello world!";
        return Window("Main");
    }
}

Notice that there is no reference to Windows Forms here. The Window() return value merely indicates that we want to show a Window - it doesn't indicate what kind of Window should be shown. This should make it easier to convert to WPF in the future.

The View Engine

The view engine is also pretty short. Since we want to reuse the naming conventions and reflection code that the other view engines use, we can derive from ReflectionBasedViewEngine:

public class FormsViewEngine : ReflectionBasedViewEngine
{
    private readonly IViewActivator _viewActivator;

    public FormsViewEngine(IViewActivator viewActivator)
    {
        _viewActivator = viewActivator;
    }

    protected override IEnumerable<string> GetAlternativeNames(string viewName)
    {
        yield return viewName;
        yield return viewName + "Form";
        yield return viewName + "Window";
        yield return viewName + "Dialog";
        yield return "frm" + viewName;
    }

    protected override bool ShouldHandle(ControllerContext controllerContext, ParameterValueDictionary viewParameters, string viewName)
    {
        var viewType = viewParameters.GetOrDefault<string>("ViewType");
        return viewType == "Window" || viewType == "Dialog";
    }

    protected override IEnumerable<Type> FilterCandidateTypes(ControllerContext controllerContext, ParameterValueDictionary viewParameters, string viewName, IEnumerable<Type> candidates)
    {
        return candidates.Where(x => typeof (Form).IsAssignableFrom(x));
    }

    protected override ViewEngineResult CreateViewResult(ControllerContext controllerContext, ParameterValueDictionary viewParameters, Type type)
    {
        return new WindowsFormViewEngineResult(type, _viewActivator, viewParameters);
    }
}

Notice how we override GetAlternativeNames to support our conventions. We also override FilterCandidateTypes to restrict the view to objects derived from the Windows Forms Form class.

The View Engine Result

The View Engine above has taken charge of finding the view. When a view is found, it creates a WindowsFormViewEngineResult. The view engine result has the job of instantiating and rendering the view:

public class WindowsFormViewEngineResult : ViewEngineResult
{
    private readonly Type _formType;
    private readonly IViewActivator _viewActivator;
    private readonly ParameterValueDictionary _viewParameters;

    public WindowsFormViewEngineResult(Type formType, IViewActivator viewActivator, ParameterValueDictionary viewParameters) : base(true, new string[] {})
    {
        _formType = formType;
        _viewActivator = viewActivator;
        _viewParameters = viewParameters;
    }

    public override void Render()
    {
        var form = (Form)_viewActivator.Instantiate(_formType);
        var bindableForm = form as IBindableForm;
        if (bindableForm != null)
        {
            var model = _viewParameters.GetOrDefault<object>("Model");
            bindableForm.Bind(model);
        }

        var isDialog = _viewParameters.GetOrDefault<string>("ViewType") == "Dialog";
        if (isDialog) form.ShowDialog();
        else form.Show();
    }
}

We make use of two critical view parameters - the ViewType, which indicates whether to show it as a Window or a Dialog, and the Model, which is populated from the Model property that was set on the controller.

Wiring It Up

To support our view engine, we just have to add it to the list of registered view engines:

ViewEngines.Engines.Add(new FormsViewEngine(new DefaultViewActivator()));

The DefaultViewActivator implements the IViewActivator interface, which is used for actually constructing the form (it's passed to the view engine result). If you want, you can use an IOC container instead.

Summary

Hopefully this illustrates how easy it is to write a View Engine. The biggest benefit to the Magellan approach is that our controllers are consistent whether we are using WPF or Windows Forms. There's also the added benefit that if we upgrade a view to WPF, our controllers don't change. Likewise if we change our naming conventions for the forms, we don't need to change the controllers. Finally, our controllers and models remain testable, which is always important.

Updated Wiki: magellan-mvvm-light-toolkit

stovellp — Sun, 22 Aug 2010 14:35:59 GMT

The MVVM Light Toolkit is an MVVM framework by WPF MVP Laurent Bugnion, the author of Silverlight 2 Unleashed. It works well alongside Magellan and makes it easy to put behaviors behind views. The integration model with Magellan is quite similar to using the Microsoft MVVM toolkit.

One difference is that the MVVM Light Toolkit typically uses resources to refer to the ViewModel, limiting the amount of code behind that is required. Since Magellan controllers typically create the model, this does need to change.

As with using the Microsoft MVVM toolkit, we use the controller to create the ViewModel:

public class HomeController : Controller
{
    public ActionResult Main()
    {
        Model = new MainViewModel();
        return Page();
    }
}

MVVM Light views typically use a locator for creating the view model - this is a problem because our controller above will be creating the VM, and Magellan is taking care of assigning it.

<Window x:Class="MvvmLight1.MvvmView1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    DataContext="{Binding Main, Source={StaticResource Locator}}"
    >

To keep Blend support, change the XAML to use d:DataContext instead of DataContext.

<Window x:Class="MvvmLight1.MvvmView1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:ViewModel="clr-namespace:MvvmLight1.ViewModel" 
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    d:DataContext="{x:Type ViewModel:MainViewModel}"
    >

Updated Wiki: magellan-mvvm-light-toolkit

stovellp — Sun, 22 Aug 2010 14:35:54 GMT

public class HomeController : Controller
{
    public ActionResult Main()
    {
        Model = new MainViewModel();
        return Page();
    }
}

MVVM Light views typically use a locator for creating the view model - this is a problem because our controller above will be creating the VM, and Magellan is taking care of assigning it.

<Window x:Class="MvvmLight1.MvvmView1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    DataContext="{Binding Main, Source={StaticResource Locator}}"
    >

To keep Blend support, change the XAML to use d:DataContext instead of DataContext.

<Window x:Class="MvvmLight1.MvvmView1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:ViewModel="clr-namespace:MvvmLight1.ViewModel" 
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    d:DataContext="{x:Type ViewModel:MainViewModel}"
    >

Updated Wiki: magellan-mvvm-toolkit

stovellp — Sun, 22 Aug 2010 14:34:52 GMT

Magellan's MVC framework is designed to handle navigation between views. However, the views themselves, and how they are implemented, is outside of Magellan's concern. Views can be simple XAML pages, or they can be driven by an MVVM or MVP pattern, or any other way you might like.

Microsoft provide a Visual Studio project template known as the MVVM Toolkit, which makes it easy to get started using the MVVM pattern.

To use Magellan with the MVVM toolkit, you can set up a new MVVM project using the MVVM project template. Then configure it the same way as described in the Magellan quickstart.

By default with the MVVM toolkit, you typically create the ViewModel and View and assign them yourself, as shown in the project template:

Views.MainView view = new Views.MainView();
view.DataContext = new ViewModels.MainViewModel();
view.Show();

Instead, with Magellan, you can assign the controller's Model property to you ViewModel:

public class HomeController : Controller
{
    public ActionResult Main()
    {
        Model = new MainViewModel();
        return Page();
    }
}

The view engines will create the page or Window, and set the DataContext to the Model for you. It will then navigate to the page or show the Window.

Your ViewModels can make use of commands, event managers, data binding, and all the other common MVVM patterns. MVVM would typically handle:

Local interaction with the view
Validation
Control state, such as whether a button should be enabled based on data

While Magellan would be used for:

Navigating to another page or window

A good way to think about this is to think in terms of the web. On the web, JavaScript is typically the "view model" - it handles the logic for a particular page. The server processes requests for many pages and navigation between pages - that's the job of Magellan.

There is also a NavigateCommand that can be used in ViewModels, instead of the need to use a DelegateCommand/RelayCommand for common navigation events.

Updated Wiki: magellan-composite-wpf

stovellp — Sun, 22 Aug 2010 14:33:43 GMT

Magellan was designed to work with Composite WPF from day one. Composite WPF provides support for multiple modules, loosely coupled pub/sub eventing, and regions for sub-dividing zones in the UI. However, Composite WPF does not enforce any particular UI pattern - MVVM, MVP and MVC could all work.

Magellan and Composite WPF can work well together to create a composite navigation-oriented application using the MVC pattern. Here are some examples:

Composite WPF modules could contain views and controllers
Composite WPF events could be used for navigation - i.e., a Navigate event that could be raised by different modules and services
Instead of pages, Magellan view results could return UserControls that are added to regions

Region Support

For region support, Magellan.Composite.dll contains some extensions that can be used. A controller may look like this:

public class ShellController : CompositeController 
{
    public ActionResult Explorer()
    {
        return CompositeView("Explorer").InRegion("LeftRegion");
    }
}

On application startup, the view can be navigated to via:

Navigator.Primary.Navigate("Shell", "Explorer");

Lastly, an additional Region View Engine needs to be registered. As discussed in the IOC topic, you can also use a custom view activator to control how views are instantiated, if you want to use IOC. In this case we'll use the Microsoft common ServiceLocator:

ViewEngines.Engines.Clear();
ViewEngines.Engines.Add(new PageViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new WindowViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new CompositeViewEngine(new ServiceLocatorViewActivator()));

When the InRegion extension method is used, and the view class derives from UIElement, the region view engine will use the service locator to resolve the default RegionManager, and then add the view to the region.

Controller Factory

There is also a new controller factory that can be used with the Common Service Locator. It will automatically back onto ServiceLocator.Current to resolve controllers, so you just have to register them in the container:

ControllerBuilder.Current.SetControllerFactory(new ServiceLocatorControllerFactory());

Updated Wiki: magellan-composite-wpf

stovellp — Sun, 22 Aug 2010 14:33:37 GMT

Composite WPF modules could contain views and controllers
Composite WPF events could be used for navigation - i.e., a Navigate event that could be raised by different modules and services
Instead of pages, Magellan view results could return UserControls that are added to regions

Region Support

For region support, Magellan.Composite.dll contains some extensions that can be used. A controller may look like this:

public class ShellController : CompositeController 
{
    public ActionResult Explorer()
    {
        return CompositeView("Explorer").InRegion("LeftRegion");
    }
}

On application startup, the view can be navigated to via:

Navigator.Primary.Navigate("Shell", "Explorer");

ViewEngines.Engines.Clear();
ViewEngines.Engines.Add(new PageViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new WindowViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new CompositeViewEngine(new ServiceLocatorViewActivator()));

Controller Factory

ControllerBuilder.Current.SetControllerFactory(new ServiceLocatorControllerFactory());