Introduction

PDF for offline use
Sample Code:
Related Articles:
Related APIs:

Let us know how you feel about this


0/250

last updated: 2016-03

Xamarin.Forms data templates provide the ability to define the presentation of data on supported controls. This article provides an introduction to data templates, examining why they are necessary.

Consider a ListView that displays a collection of Person objects. The following code example shows the definition of the Person class:

public class Person
{
  public string Name { get; private set; }
  public int Age { get; private set; }
  public string Location { get; private set; }

  public Person (string name, int age, string location)
  {
    Name = name;
    Age = age;
    Location = location;
  }
}

The Person class defines Name, Age, and Location properties, which are set through the constructor. The ListView is used to display the collection of Person objects, as shown in the following XAML code example:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" x:Class="DataTemplates.WithoutDataTemplatePage" Title="Without a Data Template" Icon="xaml.png">
    <StackLayout Padding="0,20,0,0">
        ...
        <ListView x:Name="listView" />
    </StackLayout>
</ContentPage>

The ListView.ItemsSource property is initialized to a List of Person instances in code-behind:

public partial class WithoutDataTemplatesPage : ContentPage
{
  public WithoutDataTemplatesPage ()
  {
    InitializeComponent ();

    var people = new List<Person> {
      new Person ("Steve", 21, "USA"),
      new Person ("John", 37, "USA"),
      new Person ("Tom", 42, "UK"),
      new Person ("Lucas", 29, "Germany"),
      new Person ("Tariq", 39, "UK"),
      new Person ("Jane", 30, "USA")
    };

    listView.ItemsSource = people;
  }
}

The equivalent C# page is shown in the following code example:

public class WithoutDataTemplatePageCS : ContentPage
{
  public WithoutDataTemplatePageCS ()
  {
    ...
    var people = new List<Person> {
      ...
    };
    var listView = new ListView { ItemsSource = people };

    Content = new StackLayout {
      Padding = new Thickness (0, 20, 0, 0),
      Children = {
        ...
        listView
      }
    };
  }
}

The ListView calls ToString when displaying the objects in the collection. Because there is no Person.ToString override, ToString returns the type name of each object, as shown in the following screenshots:

In order to display meaningful data, the Person object can override the ToString method, as shown in the following code example:

public class Person
{
  ...
  public override string ToString ()
  {
    return Name;
  }
}

This results in the ListView displaying the Person.Name property value for each object in the collection, as shown in the following screenshots:

The Person.ToString override could return a formatted string consisting of the Name, Age, and Location properties. However, this approach offers only a limited control over the appearance of each item of data. For more flexibility, a DataTemplate can be created that defines the appearance of the data.

Creating a DataTemplate

A DataTemplate is used to specify the appearance of data, and typically uses data binding to display data. Its common usage scenario is when displaying data from a collection of objects in a ListView. For example, when a ListView is bound to a collection of Person objects, the ListView.ItemTemplate property will be set to a DataTemplate that defines the appearance of each Person object in the ListView. The DataTemplate will contain elements that bind to property values of each Person object. For more information about data binding, see Data Binding Basics.

A DataTemplate can be used as a value for the following properties:

Note that although the TableView makes uses of Cell objects, it does not use a DataTemplate. This is because data bindings are always set directly on Cell objects.

A DataTemplate that's placed as a direct child of the properties listed above is known as an inline template. Alternatively, a DataTemplate can be defined as a control-level, page-level, or application-level resource. Choosing where to define a DataTemplate impacts where it can be used:

  • A DataTemplate defined at the control level can only be applied to the control.
  • A DataTemplate defined at the page level can be applied to multiple valid controls on the page.
  • A DataTemplate defined at the application level can be applied to valid controls throughout the application.

Data templates lower in the view hierarchy take precedence over those defined higher up when they share x:Key attributes. For example, an application-level data template will be overridden by a page-level data template, and a page-level data template will be overridden by a control-level data template, or an inline data template.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.