Caliburn Hello World

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:

  • Views
  • ViewModels

Finally, I’ll delete MainPage.xaml, since we won’t be using it.

The project looks like this:

the project setup

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
Attachment: HelloCaliburn.zip

[Advertisement]

About The CodeBetter.Com Blog Network
CodeBetter.Com FAQ

Our Mission

Advertisers should contact Brendan

Subscribe
Google Reader or Homepage

del.icio.us CodeBetter.com Latest Items
Add to My Yahoo!
Subscribe with Bloglines
Subscribe in NewsGator Online
Subscribe with myFeedster
Add to My AOL
Furl CodeBetter.com Latest Items
Subscribe in Rojo

Member Projects
DimeCasts.Net - Derik Whittaker

Friends of Devlicio.us
Red-Gate Tools For SQL and .NET

NDepend

SlickEdit
 
SmartInspect .NET Logging
NGEDIT: ViEmu and Codekana
LiteAccounting.Com
DevExpress
Fixx
NHibernate Profiler
Unfuddle
Balsamiq Mockups
Scrumy
JetBrains - ReSharper
Umbraco
NServiceBus
RavenDb
Web Sequence Diagrams
Ducksboard<-- NEW Friend!

 



Site Copyright © 2007 CodeBetter.Com
Content Copyright Individual Bloggers

 

Community Server (Commercial Edition)