A friend recently complained to me that he had a hard time putting together a Hello World application using Caliburn. Here’s a simple step-by-step guide to getting a very simple Caliburn application up and running with the 1.0 release.
The goal is to demonstrate the built-in conventions-based binding for view models and views, as well as binding to a method on the view model. This tutorials assume a basic knowledge of MVVM.
Setup
First, go and download the 1.0 RTW.
Next, we’ll create a new Silverlight 3.0 application. I named mine HelloCaliburn.
We’ll need to reference a few assemblies from the 1.0 RTW. Since we are working with Silverlight, the required assemblies are located in the downloaded zip at
\Caliburn v1 RTW\Bin\Silverlight-3.0\release
Since we are keeping things as simple as possible, we only need three assemblies:
- Caliburn.Core.dll
- Caliburn.PresentationFramework.dll
- Microsoft.Practices.ServiceLocation.dll
Copy these to a convenient location and add a reference to them in your Silverlight project.
Next, we’ll create two folders in our project:
Finally, I’ll delete MainPage.xaml, since we won’t be using it.
The project looks like this:
Caliburn’s Pattern
Caliburn has a opinion about how you should structure your application. (Of course, you can pick and choose and modify that default opinion considerably).
By default, though, Caliburn thinks of the UI as a graph or tree of view model objects. So we’ll need to have a top level view model that will be the root of this object graph. It’s become our common practice to name this root ShellViewModel.
Let’s create a class ShellViewModel in the ViewModels folder. For the time being, we’ll leave it as a simple POCO.
We’ll also need to create view that will be associated with the view model. Let’s create a new Silverlight User Control named ShellView in the Views folder.
The names ShellViewModel and ShellView are very important. Caliburn uses these names to associate a view with a particular view model. Given a view model named MyViewModel, Caliburn’s default convention is to look for a view named MyView. In addition, it expects the view models to be in a folder (or namespace rather) named ViewModels and that the corresponding views will in Views. All of these defaults can be changed.
Configuration
We are going to keep things to a bare minimum. We’ll inherit from the base class CaliburnApplication. This class will provide most of the default configuration we need. Open App.xaml.cs and modify it so that it looks like this:
namespace HelloCaliburn
{
using Caliburn.PresentationFramework.ApplicationModel;
using ViewModels;
public partial class App : CaliburnApplication
{
public App()
{
InitializeComponent();
}
protected override object CreateRootModel()
{
return new ShellViewModel();
}
}
}
The override CreateRootModel returns an instance that will be the root of our UI object graph. It’s analogous to setting the RootVisual for the application. However, you’ll notice that it returns an object and is not to limited returning an actual visual.
This is because Caliburn is biased towards the view model. This method returns the view model; it is the responsibility of Caliburn to locate and display the corresponding view.
Since we’ve changed the base class for App, we also need to modify the associated XAML. Let’s change App.xaml to look like this:
<am:CaliburnApplication
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:am="clr-namespace:Caliburn.PresentationFramework.ApplicationModel;assembly=Caliburn.PresentationFramework"
x:Class="HelloCaliburn.App">
<Application.Resources>
</Application.Resources>
</am:CaliburnApplication>
If we run the application now, everything would work. However, we couldn’t tell because the view and view model are empty.
Bindings
Silverlight and WPF already have a rich data binding system. However, it is awkward for binding to methods. One of Caliburn’s core features is the ability to bind to methods on the view model.
Let’s add a simple string property to our view model and a method that will change the property when it is executed.
We’ll make ShellViewModel inherit from Caliburn’s PropertyChangedBase. This class is a basic implementation of INotifyPropertyChanged. Modify ShellViewModel so that it looks like this:
namespace HelloCaliburn.ViewModels
{
using Caliburn.Core;
public class ShellViewModel : PropertyChangedBase
{
private string _message;
public ShellViewModel()
{
Message = "My First Message";
}
public string Message
{
get { return _message; }
set
{
_message = value;
NotifyOfPropertyChange("Message");
}
}
public void ChangeMessage()
{
Message = "Hello World";
}
}
}
I give the Message property an initial value in the constructor. This is just so we’ll see something when it is first displayed.
We’ll bind to Message using standard binding techniques. However, we’ll need to use a Caliburn attached property, Message.Attach. Change the markup in ShellView.xaml to look like this:
<UserControl x:Class="HelloCaliburn.Views.ShellView"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:pf="clr-namespace:Caliburn.PresentationFramework;assembly=Caliburn.PresentationFramework"
Width="400"
Height="300">
<Grid x:Name="LayoutRoot"
Background="White">
<StackPanel>
<TextBlock Text="{Binding Message}" />
<Button pf:Message.Attach="ChangeMessage"
Content="Click Me" />
</StackPanel>
</Grid>
</UserControl>
The simplest way to use Message.Attach is to specify the name of the method on the view model. This causes Caliburn to “bind” the invocation of that method to the button’s click event.
You’re Done
Run the app and click the button. This is (of course) a very trivial example, but I hope it gives you an idea of how things work. For more details, be sure to check out the official documentation.
Download the code for this tutorial here.
Posted
11-22-2009 11:32 AM
by
Christopher Bennage