Share via


TemplateBinding markup extension

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Links the value of a property in a control template to the value of some other exposed property on the templated control. TemplateBinding can only be used within a ControlTemplate definition in XAML.

XAML attribute usage

<object propertyName="{TemplateBinding sourceProperty}" .../>

XAML attribute usage (for Setter property in template or style)

<Setter Property="propertyName" Value="{TemplateBinding sourceProperty}" .../>

XAML values

Term Description

propertyName

The name of the property being set in the setter syntax. This must be a dependency property.

sourceProperty

The name of another dependency property that exists on the type being templated.

 

Remarks

Using TemplateBinding is a fundamental part of how you define a control template, either if you are a custom control author or if you are replacing a control template for existing controls. For more info, see Quickstart: Control templates.

It's fairly common for propertyName and targetProperty to use the same property name. In this case, a control might define a property on itself and forward the property to an existing and intuitively named property of one of its component parts. For example, a control that incorporates a TextBlock in its compositing, which is used to display the control's own Text property, might include this XAML as a part in the control template: <TextBlock Text="{TemplateBinding Text}" .... />

The types used as the value for the source property and the target property must match. There's no opportunity to introduce a converter when you're using TemplateBinding. Failing to match values results in an error when parsing the XAML. If you need a converter you can use the verbose syntax for a template binding such as: {Binding RelativeSource={RelativeSource TemplatedParent}, Converter="..." ...}

Attempting to use a TemplateBinding outside of a ControlTemplate definition in XAML will result in a parser error.

You can use TemplateBinding for cases where the templated parent value is also deferred as another binding. The evaluation for TemplateBinding can wait until any required runtime bindings have values.

A TemplateBinding is always a one-way binding. Both properties involved must be dependency properties.

TemplateBinding is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the "{" and "}" characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute.

Note  In the Windows Runtime XAML processor implementation, there is no backing class representation for TemplateBinding. TemplateBinding is exclusively for use in XAML markup. There isn't a straightforward way to reproduce the behavior in code.

 

Quickstart: Control templates

Data binding overview

ControlTemplate

XAML overview

Dependency properties overview