Parameters

Explanation

Caliburn's parameters are used to pass additional information from the UI as part of a message body. The most common use case is sending data from a UI to an action on a controller, presenter or presentation model (View Model). ActionMessage and CommandMessage both make extensive use of parameters.

Details

Caliburn is intelligent enough in many cases to automatically be able to determine the parameters required by a message. The method binder can do this by comparing action/command parameter names to the names of elements within the UI. If it finds the appropriate matches, it can bind the message. There is a drawback to this approach, however. Several of Caliburn's most useful features can not function properly if the framework does not know the parameters ahead of time. Specifically, the ability to auto-disable parts of UI based on changes in parameter value will not work. It would be considered a best practice to always explicitly define the parameters that a message will send.

Special Values

In WPF, the Value property of a parameter can be bound using any valid databinding expression. In Silverlight, you can only use simple ElementName binding using the ElementName and Path properties. Both platforms support explicitly passed values, using their Value property and both support the following set of special values:

Value Effect
$eventArgs Passes the EventArgs from an event based trigger as a parameter.
$source Passes the source UI element as a parameter.
$dataContext Passes the source's datacontext as a paramter.
$value Gets the source's default value, using the IRoutedMessageController's default settings.
$this.Some.Property.Path Passes the value of the property of the control to which the message is attached. This can only be used in the shortened (parsed) message declaration for WPF/Silverlight or in the long declaration for Silverlight only, where $this is used for the ElementName property. $this can also be used in the return binding.


Note: Case is ignored except when using $this syntax.

Literals

To pass literals as a message parameter (short syntax only), you must surround it with single quotes. Here are some examples:

MyAction('this is a string literal')
MyAction('false')
MyAction($this.Property)
MyAction(someElement.Property)
MyAction($eventArgs.Some.Property)
MyAction('1234')
MyAction(password) - You can specify a control name without a property and Caliburn will bind the default property.

Last edited Jan 27, 2010 at 6:13 PM by EisenbergEffect, version 9