Category	Featured projects
scm	Subversion, Subclipse, TortoiseSVN, RapidSVN
issuetrack	Scarab
requirements	xmlbasedsrs
design	ArgoUML
techcomm	SubEtha, eyebrowse, midgard, cowiki
construction	antelope, scons, frameworx, build-interceptor, propel, phing
testing	maxq, aut
deployment	current
process	ReadySET
libraries	GEF, Axion, Style, SSTree
Over 500 more tools...

Subversion and IDEs
Eclipse
JDeveloper
NetBeans
Visual Studio

Introduction to Action Messages 

This article discusses code which can be found in the Samples.ActionMessages project.

Action messages are a mechanism enabled by Caliburn, designed to facilitate the communication between views and presenters in an MVP architecture.  The allow the developer to create POCOs (Plain Old CLR Classes) that encapsulate application logic and bind them (methods and properties) to the UI.  This greatly simplifies WPF development and enables TDD by moving important code out of the XAML code-behind and into the presenter.

Before you can begin working with Caliburn and Action Messages, you must configure the framework.  We'll be using the default configuration for now, so all that is required is to make your App constructor look like this:

public App() { CaliburnApplication.Start(); }

Lets also add a class to serve as a simple presenter:

public class Calculator { public int Divide(int x, int y) { return x / y; } }

Notice that there is nothing special required of this class, such as inheriting from special base classes or implementing interfaces.  Now we need to make a view:

<Window x:Class="Samples.ActionMessages.Window1" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" Title="Action Message Sample" SizeToContent="WidthAndHeight" xmlns:cal="http://schemas.bluespire.com/wpf/2008/Caliburn" xmlns:local="clr-namespace:Samples.ActionMessages"> <cal:Presenter.Binding> <local:Calculator /> </cal:Presenter.Binding> <StackPanel Orientation="Horizontal"> <TextBox x:Name="leftSide" Width="65" Margin="3" /> <TextBlock Text="/" Width="20" VerticalAlignment="Center" TextAlignment="Center" /> <TextBox x:Name="rightSide" Width="65" Margin="3" /> <Button Content="=" Margin="3"> <cal:View.Messages> <cal:ActionMessage Trigger="Click" Action="Divide" Return="{Binding ElementName=result, Path=Text}"> <cal:Parameter Value="{Binding ElementName=leftSide, Path=Text}" /> <cal:Parameter Value="{Binding ElementName=rightSide, Path=Text}" /> </cal:ActionMessage> </cal:View.Messages> </Button> <Border BorderBrush="Black" BorderThickness="0 0 0 1" Margin="3"> <TextBlock x:Name="result" Width="65" VerticalAlignment="Center" TextAlignment="Center" /> </Border> </StackPanel> </Window>

The two important things to note about the view are the us of cal:Presenter.Binding and cal:View.Messages.  Binding causes the instance of Calculator to be bound to the Window.  Effectively, it is set as the Window's DataContext and registered with the framework as being connected to the Window.  You can bind a presenter to any DependencyObject, although it must be a FrameworkElement to get DataContext functionality.  Presenter bindings are directly related to ActionMessages.  The ActionMessage that is set with the Messages attached property has the following result:  When the Button is Clicked (Trigger) the Divide (Action) method on Calculator instance will be called.  The Text values of the TextBoxes "leftSide" and "rightSide" will be passed into the method as parameters.  The return value of the method will be bound to the Text property of the "result" TextBox.

A couple of other important things to know:  Caliburn provides a ResolveExtension that can be used with Binding to ask a dependency injection container to resolve the instance of the presenter for you.  Caliburn provides adapters for Windsor, Spring.net, StructureMap and Unity.  You must use a custom configuration to turn on this functionality.  Also, WPF Controls have default events and value properties, also configurable; so you don't have to specify that the ActionMessage in the above example is triggered by a Click event because this is the default for a Button.  If we follow a few more conventions, we can further streamline the ActionMessage markup to this:

<cal:ActionMessage Action="Divide" Return="{Binding ElementName=result, Path=Text}"/>

if we change our class to this:

public int Divide(int leftSide, int rightSide) { return leftSide / rightSide; }

If the message does not declare any parameters, and the action requires them, the framework will look for elements by name, based on the parameter names.  It will then query the found elements for their default property values (configurable) and supply those values to the method.  If it cannot find matches and the method only takes one parameter, it will attempt to bind that to the message sender's default property value.  If a message doesn't need to declare a return value or parameters, you can declare it with a simple string value:

<Button cal:View.Messages="DoSomething" />

If you play around with the sample long enough, you'll eventually put a zero in the second TextBox and throw a nasty exception.  You'd probably want to check for zero in reality, but you can handle exceptions like this:

[Presenter(Rescue="UhOh")] public class Calculator { public int Divide(int leftSide, int rightSide) { return leftSide / rightSide; } public void UhOh(Exception e) { MessageBox.Show("Uh oh. You been bad."); } }

You can also place an Action attribute on any method to declare custom exception handling for that method.  What if the method is a long running action?

[Presenter(Rescue="UhOh")] public class Calculator { [AsyncAction] public int Divide(int leftSide, int rightSide) { Thread.Sleep(2000); return leftSide / rightSide; } public void UhOh(Exception e) { MessageBox.Show("Uh oh. You been bad."); } }

The return value still binds! Need a callback instead of a return value?  The AsyncAction attribute lets you specify the name of a callback method.  The return values and callbacks are automatically marshaled back onto the UI thread for you.

Another, way to get the same functionality as all the above examples would be to give the presenter LeftSide, RightSide and Result properties bound to the UI along with a parameterless Divide method.  The design of Caliburn tries hard not to box the developer into one specific implementation of MVC/MVP because, in practice, both these techniques and others are often used in conjunction or depending on the specific situation.

There's one more important thing you need to know to get started with these features.  ActionMessages can bubble.  If, for example, a message was looking for an action called "DoSomething," but did not find it on the presenter, the message would bubble up the UI looking for a presenter until it found one with the appropriate action.  This is useful if a UserControl needs to have its own presenter, but also wants to pass messages on to its parent Window.

Everything shown above in XAML can be done imperatively through code by using the IPresenterManager and IViewManager services.  These can be obtained by by calling DI.Resolve<IPresenterManager>() and DI.Resolve<IViewManager>() respectively.