DataTemplate DataTemplate DataTemplate Class

Definition

Describes the visual structure of a data object. Use data binding for specific elements in the template that display the data values.

public : class DataTemplate : FrameworkTemplate, IDataTemplate
public class DataTemplate : FrameworkTemplate, IDataTemplate
Public Class DataTemplate Inherits FrameworkTemplate Implements IDataTemplate
<DataTemplate ...>
  templateContent
</DataTemplate>
 

Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The following example uses a DataTemplate to display the items of a ListBox. In this example, the ListBox is bound to a collection of Customer objects. The DataTemplate contains TextBlock controls that bind to the FirstName, LastName, and Address properties. For more info on data binding, see Data binding in depth.

<Grid>
    <Grid.Resources>
        <src:Customers x:Key="customers"/>
    </Grid.Resources>

    <ListBox ItemsSource="{StaticResource customers}" Width="350" Margin="0,5,0,10">
        <ListBox.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal">
                    <TextBlock Padding="5,0,5,0"
          Text="{Binding FirstName}" />
                    <TextBlock Text="{Binding LastName}" />
                    <TextBlock Text=", " />
                    <TextBlock Text="{Binding Address}" />
                </StackPanel>
            </DataTemplate>
        </ListBox.ItemTemplate>
    </ListBox>
</Grid>
public class Customer
{
    public String FirstName { get; set; }
    public String LastName { get; set; }
    public String Address { get; set; }

    public Customer(String firstName, String lastName, String address)
    {
        this.FirstName = firstName;
        this.LastName = lastName;
        this.Address = address;
    }

}

public class Customers : ObservableCollection<Customer>
{
    public Customers()
    {
        Add(new Customer("Michael", "Anderberg",
                "12 North Third Street, Apartment 45"));
        Add(new Customer("Chris", "Ashton",
                "34 West Fifth Street, Apartment 67"));
        Add(new Customer("Seo-yun", "Jun",
                "56 East Seventh Street, Apartment 89"));
        Add(new Customer("Guido", "Pica",
                "78 South Ninth Street, Apartment 10"));
    }

}
Public Class Customer
    Private _firstName As String
    Private _lastName As String
    Private _address As String

    Public Property FirstName() As String
        Get
            Return _firstName
        End Get

        Set(ByVal value As String)
            _firstName = value
        End Set
    End Property

    Public Property LastName() As String
        Get
            Return _lastName
        End Get

        Set(ByVal value As String)
            _lastName = value
        End Set
    End Property

    Public Property Address() As String
        Get
            Return _address
        End Get

        Set(ByVal value As String)
            _address = value
        End Set
    End Property

    Public Sub New(ByVal firstName As String, ByVal lastName As String, ByVal address As String)
        Me.FirstName = firstName
        Me.LastName = lastName
        Me.Address = address
    End Sub

End Class

Public Class Customers
    Inherits ObservableCollection(Of Customer)

    Public Sub New()
        Add(New Customer("Michael", "Anderberg", "12 North Third Street, Apartment 45"))
        Add(New Customer("Chris", "Ashton", "34 West Fifth Street, Apartment 67"))
        Add(New Customer("Seo-yun", "Jun", "56 East Seventh Street, Apartment 89"))
        Add(New Customer("Guido", "Pica", "78 South Ninth Street, Apartment 10"))
    End Sub

End Class

Remarks

A DataTemplate object is used as the value for these properties:

You typically use a DataTemplate to specify the visual representation of your data. DataTemplate objects are particularly useful when you are binding an ItemsControl such as a ListBox to an entire collection. Without specific instructions, a ListBox displays the string representation of the objects in a collection. Use a DataTemplate to define the appearance of each of your data objects. The content of your DataTemplate becomes the visual structure of your data objects.

You typically use data binding in a DataTemplate. For example, suppose that a ListBox is bound to a collection of Customer objects and has the ItemTemplate property set to a DataTemplate. When the ListBox is created, a ListBoxItem is created for each Customer in the collection, and the DataContext of the ListBoxItem is set to the appropriate customer. In other words, the DataContext of the first ListBoxItem is set to the first customer, the DataContext of the second ListBoxItem is set to the second customer, and so on. You can bind elements in the DataTemplate to show property values that come from each of the Customer objects.

You can also use a DataTemplate to share UIElement objects across multiple ContentControl objects. For example, suppose you need multiple buttons on your application to have the same graphic. You can create a DataTemplate that contains the graphic and use it as the ContentTemplate for the buttons. A data template for ContentTemplate can also use data binding. But in this case the data context is the same as the element where the template's applied. Usually this is one data object, and there's no concept of items.

You can place a DataTemplate as the direct child of an ItemTemplate property element in XAML. This is know as an inline template and you'd do this if you had no need to use that same data template for other areas of your UI. You can also define a DataTemplate as a resource and then reference the resource as the value of the ItemTemplate property. Once it's a resource, you can use the same template for multiple UI elements that need a data template. If you factor the data template into Application.Resources, you can even share the same template for different pages of your UI.

The XAML usage for contents of a data template is not exposed as a settable code property. It is special behavior built into the XAML processing for a DataTemplate.

For advanced data binding scenarios, you might want to have properties of the data determine which template should produce their UI representations. For this scenario, you can use a DataTemplateSelector and set properties such as ItemTemplateSelector to assign it to a data view. A DataTemplateSelector is a logic class you write yourself, which has a method that returns exactly one DataTemplate to the binding engine based on your own logic interacting with your data. For more info, see Data binding in depth.

Constructors

DataTemplate() DataTemplate() DataTemplate()

Initializes a new instance of the DataTemplate class.

public : DataTemplate()
public DataTemplate()
Public Sub New()

Properties

Dispatcher Dispatcher Dispatcher

Inherited from DependencyObject

ExtensionInstanceProperty ExtensionInstanceProperty ExtensionInstanceProperty

Identifies the ExtensionInstance XAML attached property.

public : static DependencyProperty ExtensionInstanceProperty { get; }
public static DependencyProperty ExtensionInstanceProperty { get; }
Public Static ReadOnly Property ExtensionInstanceProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ExtensionInstance XAML attached property.

See Also

Methods

ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Inherited from DependencyObject

GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty)

Inherited from DependencyObject

GetExtensionInstance(FrameworkElement) GetExtensionInstance(FrameworkElement) GetExtensionInstance(FrameworkElement)

Gets the value of the DataTemplate.ExtensionInstance XAML attached property for the target element.

public : static IDataTemplateExtension GetExtensionInstance(FrameworkElement element)
public static IDataTemplateExtension GetExtensionInstance(FrameworkElement element)
Public Static Function GetExtensionInstance(element As FrameworkElement) As IDataTemplateExtension
Parameters
element
FrameworkElement FrameworkElement FrameworkElement

The object from which the property value is read.

Returns
See Also

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Inherited from DependencyObject

LoadContent() LoadContent() LoadContent()

Creates the UIElement objects in the DataTemplate.

public : DependencyObject LoadContent()
public DependencyObject LoadContent()
Public Function LoadContent() As DependencyObject
Returns

Examples

The following examples demonstrate using the LoadContent method to change the appearance of a Border at run time. The example creates a ListBox that contains the numbers 1 through 10. When the user selects an item in the ListBox, the Border displays the selected number. If the user selects an even number, the number is red and has a green circle around it. If the user selects an odd number, the number is blue and has a purple square around it.

<StackPanel  Name="rootStackPanel">

  <StackPanel.Resources>
    <DataTemplate x:Key="oddNumberTemplate">
      <Grid>
        <Rectangle Stroke="Purple" StrokeThickness="4" />
        <TextBlock HorizontalAlignment="Center" 
                   VerticalAlignment="Center" 
                   FontSize="24" Foreground="Blue" 
                   FontWeight="Bold"/>
      </Grid>
    </DataTemplate>


    <DataTemplate x:Key="evenNumberTemplate">
      <Grid>
        <Ellipse Stroke="Green" StrokeThickness="4"/>
        <TextBlock HorizontalAlignment="Center" 
                   VerticalAlignment="Center" 
                   FontSize="24" Foreground="Red" 
                   FontWeight="Bold"  />
      </Grid>
    </DataTemplate>
  </StackPanel.Resources>

  <Border Name="selectedItemDisplay"
          Width="50" Height="50"/>

  <ListBox Name="numberList" SelectionChanged="ListBox_SelectionChanged">
    <ListBoxItem Content="1"/>
    <ListBoxItem Content="2"/>
    <ListBoxItem Content="3"/>
    <ListBoxItem Content="4"/>
    <ListBoxItem Content="5"/>
    <ListBoxItem Content="6"/>
    <ListBoxItem Content="7"/>
    <ListBoxItem Content="8"/>
    <ListBoxItem Content="9"/>
    <ListBoxItem Content="10"/>
  </ListBox>

</StackPanel>
private void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    ListBoxItem lbi = ((sender as ListBox).SelectedItem as ListBoxItem);
    SelectDataTemplate(lbi.Content);
}

private void SelectDataTemplate(object value)
{
    string numberStr = value as string;

    if (numberStr != null)
    {
        int num;

        try
        {
            num = Convert.ToInt32(numberStr);
        }
        catch
        {
            return;
        }

        DataTemplate template;

        // Select one of the DataTemplate objects, based on the 
        // value of the selected item in the ComboBox.
        if (num % 2 != 0)
        {
            template = rootStackPanel.Resources["oddNumberTemplate"] as DataTemplate;
        }
        else
        {
            template = rootStackPanel.Resources["evenNumberTemplate"] as DataTemplate;
        }

        selectedItemDisplay.Child = template.LoadContent() as UIElement;
        TextBlock tb = FindVisualChild<TextBlock>(selectedItemDisplay);
        tb.Text = numberStr;
    }
}

private childItem FindVisualChild<childItem>(DependencyObject obj)
    where childItem : DependencyObject
{
    for (int i = 0; i < VisualTreeHelper.GetChildrenCount(obj); i++)
    {
        DependencyObject child = VisualTreeHelper.GetChild(obj, i);

        if (child != null && child is childItem)
        {
            return (childItem)child;
        }
        else
        {
            childItem childOfChild = FindVisualChild<childItem>(child);
            if (childOfChild != null)
                return childOfChild;
        }
    }
    return null;
}
Private Sub ListBox_SelectionChanged(ByVal sender As Object, ByVal e As SelectionChangedEventArgs)
    Dim lbi As ListBoxItem = CType(CType(sender, ListBox).SelectedItem, ListBoxItem)
    SelectDataTemplate(lbi.Content)

End Sub

Private Sub SelectDataTemplate(ByVal value As Object)
    Dim numberStr As String = CType(value, String)

    If Not numberStr Is Nothing Then
        Dim num As Integer

        Try
            num = Convert.ToInt32(numberStr)
        Catch
            Return
        End Try

        Dim template As DataTemplate


        ' Select one of the DataTemplate objects, based on the 
        ' value of the selected item in the ComboBox.
        If num Mod 2 <> 0 Then
            template = CType(rootStackPanel.Resources("oddNumberTemplate"), DataTemplate)
        Else
            template = CType(rootStackPanel.Resources("evenNumberTemplate"), DataTemplate)
        End If

        selectedItemDisplay.Child = CType(template.LoadContent(), UIElement)
        Dim tb As TextBlock = FindVisualChild(Of TextBlock)(selectedItemDisplay)
        tb.Text = numberStr

    End If
End Sub

Private Function FindVisualChild(Of childItem As DependencyObject) _
        (ByVal obj As DependencyObject) As childItem

    Dim i As Integer

    For i = 0 To VisualTreeHelper.GetChildrenCount(obj) - 1

        Dim child As DependencyObject = VisualTreeHelper.GetChild(obj, i)
        If ((Not child Is Nothing) And (TypeOf child Is childItem)) Then
            Return child
        End If

        Dim childOfChild As childItem = Me.FindVisualChild(Of childItem)(child)
        If (Not childOfChild Is Nothing) Then
            Return childOfChild
        End If

    Next i

    Return Nothing

End Function

Remarks

When you call LoadContent, the UIElement objects in the DataTemplate are created, and you can add them to the visual tree of another UIElement.

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Inherited from DependencyObject

RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Inherited from DependencyObject

SetExtensionInstance(FrameworkElement, IDataTemplateExtension) SetExtensionInstance(FrameworkElement, IDataTemplateExtension) SetExtensionInstance(FrameworkElement, IDataTemplateExtension)

Sets the value of the DataTemplate.ExtensionInstance XAML attached property for a target element.

public : static void SetExtensionInstance(FrameworkElement element, IDataTemplateExtension value)
public static void SetExtensionInstance(FrameworkElement element, IDataTemplateExtension value)
Public Static Function SetExtensionInstance(element As FrameworkElement, value As IDataTemplateExtension) As void
Parameters
element
FrameworkElement FrameworkElement FrameworkElement

The object to which the property value is written.

See Also

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Inherited from DependencyObject

UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Inherited from DependencyObject

See Also