DataTemplate Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

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

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class DataTemplate : FrameworkTemplate, IElementFactory

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class DataTemplate : FrameworkTemplate, IElementFactory

Public Class DataTemplate
Inherits FrameworkTemplate
Implements IElementFactory

Inheritance: Object IInspectable DependencyObject FrameworkTemplate DataTemplate

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements: IElementFactory

Examples

The following example uses a DataTemplate to display the items of a ListView. In this example, the ListView 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>
        <local:Customers x:Key="customers"/>
    </Grid.Resources>

    <ListView ItemsSource="{StaticResource customers}" 
       Width="350" Margin="0,4,0,8">
        <ListView.ItemTemplate>
            <DataTemplate x:DataType="local:Customer">
                <StackPanel>
                    <StackPanel Orientation="Horizontal">
                        <TextBlock Text="{x:Bind LastName}"/>
                        <TextBlock Text="," Margin="0,0,2,0"/>
                        <TextBlock Text="{x:Bind FirstName}"/>
                    </StackPanel>
                    <TextBlock Text="{x:Bind Address}" Margin="8,0,0,2"/>
                </StackPanel>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
</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"));
    }

}

Remarks

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

ItemsControl.ItemTemplate (which is inherited by various items controls such as ListView, GridView, ListBox)
ContentControl.ContentTemplate (which is inherited by various content controls such as Button, Frame, SettingsFlyout)
HeaderTemplate and FooterTemplate properties of various items control classes
ItemsPresenter.HeaderTemplate and ItemsPresenter.FooterTemplate
HeaderTemplate and FooterTemplate properties of text controls such as RichEditBox, TextBox
HeaderTemplate property of controls such as ComboBox, DatePicker, Hub, HubSection, Pivot, Slider, TimePicker, ToggleSwitch; some of these also have FooterTemplate

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 ListView is bound to a collection of Customer objects and has the ItemTemplate property set to a DataTemplate. When the ListView is created, a ListViewItem is created for each Customer in the collection, and the DataContext of the ListViewItem is set to the appropriate customer. In other words, the DataContext of the first ListViewItem is set to the first customer, the DataContext of the second ListViewItem 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.

XAML attached properties

DataTemplate is the host service class for a XAML attached property.

In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing the identifier field as the dependency property identifier.

Attached property	Description
ExtensionInstance	Gets or sets an extension instance that defines helper methods for phased rendering of a data template. Type: IDataTemplateExtension Identifier field: ExtensionInstanceProperty Accessor methods: GetExtensionInstance, SetExtensionInstance

Constructors

DataTemplate()

Initializes a new instance of the DataTemplate class.

Properties

Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
ExtensionInstanceProperty	Identifies the ExtensionInstance XAML attached property.

Attached Properties

ExtensionInstance

Gets or sets an extension instance that defines helper methods for phased rendering of a data template.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetElement(ElementFactoryGetArgs)	Creates or retrieves an existing instance of the UIElement object declared in the DataTemplate.
GetExtensionInstance(FrameworkElement)	Gets the value of the DataTemplate.ExtensionInstance XAML attached property for the target element.
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
LoadContent()	Creates the UIElement objects in the DataTemplate.
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RecycleElement(ElementFactoryRecycleArgs)	Recycles a UIElement that was previously retrieved using GetElement.
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetExtensionInstance(FrameworkElement, IDataTemplateExtension)	Sets the value of the DataTemplate.ExtensionInstance XAML attached property for a target element.
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to

Share via