DataPages Controls Reference

PDF for offline use

Let us know how you feel about this

Translation Quality


0/250

The DataPages preview currently requires a Xamarin.Forms Theme reference to render.

The Xamarin.Forms DataPages Nuget includes a number of controls that can take advantage of data source binding.

To use these controls in XAML, ensure the namespace has been included, for example see the xmlns:pages declaration below:

<ContentPage
    xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:pages="clr-namespace:Xamarin.Forms.Pages;assembly=Xamarin.Forms.Pages"
    x:Class="DataPagesDemo.Detail">

The examples below include DynamicResource references which would need to exist in the project's resources dictionary in order to work. There is also an example of how to build a custom control

Built-in Controls

HeroImage

The HeroImage control has four properties:

  • Text
  • Detail
  • ImageSource
  • Aspect
<pages:HeroImage
    ImageSource="{ DynamicResource HeroImageImage }"
    Text="Keith Ballinger"
    Detail="Xamarin"
/>

Android

iOS

ListItem

The ListItem control's layout is similar to native iOS and Android list or table rows, however it can also be used as a regular view. In the example code below it is shown hosted inside a StackLayout, but it can also be used in data-bound scolling list controls.

There are five properties:

  • Title
  • Detail
  • ImageSource
  • PlaceholdImageSource
  • Aspect
<StackLayout Spacing="0">
    <pages:ListItemControl
        Detail="Xamarin"
        ImageSource="{ DynamicResource UserImage }"
        Title="Miguel de Icaza"
        PlaceholdImageSource="{ DynamicResource IconImage }"
    />

These screenshots show the ListItem on iOS and Android platforms using both the Light and Dark themes:

Android

iOS

Custom Control Example

The goal of this custom CardView control is to resemble the native Android CardView.

It will contain three properties:

  • Text
  • Detail
  • ImageSource

The goal is a custom control that will look like the code below (note that a custom xmlns:local is required that references the current assembly):

<local:CardView
  ImageSource="{ DynamicResource CardViewImage }"
  Text="CardView Text"
  Detail="CardView Detail"
/>

It should look like the screenshots below using colors corresponding to the built-in Light and Dark themes:

Android

iOS

Building the Custom CardView

  1. DataView subclass
  2. Define Font, Layout, and Margins
  3. Create Styles for the Control's Children
  4. Create the Control Layout Template
  5. Add the Theme-specific Resources
  6. Set the ControlTemplate for the CardView class
  7. Add the Control to a Page

1. DataView Subclass

The C# subclass of DataView defines the bindable properties for the control.

public class CardView : DataView
{
    public static readonly BindableProperty TextProperty =
        BindableProperty.Create ("Text", typeof (string), typeof (CardView), null, BindingMode.TwoWay);

    public string Text
    {
        get { return (string)GetValue (TextProperty); }
        set { SetValue (TextProperty, value); }
    }

    public static readonly BindableProperty DetailProperty =
        BindableProperty.Create ("Detail", typeof (string), typeof (CardView), null, BindingMode.TwoWay);

    public string Detail
    {
        get { return (string)GetValue (DetailProperty); }
        set { SetValue (DetailProperty, value); }
    }

    public static readonly BindableProperty ImageSourceProperty =
        BindableProperty.Create ("ImageSource", typeof (ImageSource), typeof (CardView), null, BindingMode.TwoWay);

    public ImageSource ImageSource
    {
        get { return (ImageSource)GetValue (ImageSourceProperty); }
        set { SetValue (ImageSourceProperty, value); }
    }

    public CardView()
    {
    }
}

2. Define Font, Layout, and Margins

The control designer would figure out these values as part of the user-interface design for the custom control. Where platform-specific specifications are required, the OnPlatform element is used.

Note that some values refer to StaticResources – these will be defined in step 5.

<!-- CARDVIEW FONT SIZES -->
<OnPlatform x:TypeArguments="x:Double"
    Android="15"
    iOS="15"
    x:Key="CardViewTextFontSize"/>

<OnPlatform x:TypeArguments="x:Double"
    Android="13"
    iOS="13"
    x:Key="CardViewDetailFontSize"/>

<OnPlatform
    x:TypeArguments="Color"
    x:Key="CardViewTextTextColor"

    Android="{ StaticResource AndroidCardViewTextTextColor }"
    iOS="{ StaticResource iOSCardViewTextTextColor }"
/>
<OnPlatform
    x:TypeArguments="Thickness"
    x:Key="CardViewTextlMargin"

    Android="20,0,20,5"
    iOS="12,10,12,4"
/>

<OnPlatform
    x:TypeArguments="Color"
    x:Key="CardViewDetailTextColor"

    Android="{ StaticResource AndroidCardViewDetailTextColor }"
    iOS="{ StaticResource iOSCardViewDetailTextColor }"
/>

<OnPlatform
    x:TypeArguments="Thickness"
    x:Key="CardViewDetailMargin"

    Android="20,0,20,20"
    iOS="12,0,10,12"
/>

<OnPlatform
    x:TypeArguments="Color"
    x:Key="CardViewBackgroundColor"

    Android="{ StaticResource AndroidCardViewBackgroundColor }"
    iOS="{ StaticResource iOSCardViewBackgroundColor }"
/>

<OnPlatform
    x:TypeArguments="x:Double"
    x:Key="CardViewShadowSize"

    Android="5"
    iOS="2"
/>

<OnPlatform
    x:TypeArguments="x:Double"
    x:Key="CardViewCornerRadius"

    Android="4"
    iOS="0"
/>

<OnPlatform
    x:TypeArguments="Color"
    x:Key="CardViewShadowColor"
    Android="#CDCDD1"
    iOS="#CDCDD1"
/>

3. Create Styles for the Control's Children

Reference all the elements defined about to create the children that will be used in the custom control:

<!-- EXPLICIT STYLES (will be Classes) -->
<Style TargetType="Label" x:Key="CardViewTextStyle">
    <Setter Property="FontSize" Value="{ StaticResource CardViewTextFontSize }" />
    <Setter Property="TextColor" Value="{ StaticResource CardViewTextTextColor }" />
    <Setter Property="HorizontalOptions" Value="Start" />
    <Setter Property="Margin" Value="{ StaticResource CardViewTextlMargin }" />
    <Setter Property="HorizontalTextAlignment" Value="Start" />
</Style>

<Style TargetType="Label" x:Key="CardViewDetailStyle">
    <Setter Property="HorizontalTextAlignment" Value="Start" />
    <Setter Property="TextColor" Value="{ StaticResource CardViewDetailTextColor }" />
    <Setter Property="FontSize" Value="{ StaticResource CardViewDetailFontSize }" />
    <Setter Property="HorizontalOptions" Value="Start" />
    <Setter Property="Margin" Value="{ StaticResource CardViewDetailMargin }" />
</Style>

<Style TargetType="Image" x:Key="CardViewImageImageStyle">
    <Setter Property="HorizontalOptions" Value="Center" />
    <Setter Property="VerticalOptions" Value="Center" />
    <Setter Property="WidthRequest" Value="220"/>
    <Setter Property="HeightRequest" Value="165"/>
</Style>

4. Create the Control Layout Template

The visual design of the custom control is explicitly declared in the control template, using the resources defined above:

<!--- CARDVIEW -->
<ControlTemplate x:Key="CardViewControlControlTemplate">
  <StackLayout
    Spacing="0"
    BackgroundColor="{ TemplateBinding BackgroundColor }"
  >

    <!-- CARDVIEW IMAGE -->
    <Image
      Source="{ TemplateBinding ImageSource }"
      HorizontalOptions="FillAndExpand"
      VerticalOptions="StartAndExpand"
      Aspect="AspectFill"

      Style="{ StaticResource CardViewImageImageStyle }"
    />

    <!-- CARDVIEW TEXT -->
    <Label
      Text="{ TemplateBinding Text }"

      LineBreakMode="WordWrap"
      VerticalOptions="End"

      Style="{ StaticResource CardViewTextStyle }"
    />


    <!-- CARDVIEW DETAIL -->
    <Label
      Text="{ TemplateBinding Detail }"
      LineBreakMode="WordWrap"
      VerticalOptions="End"

      Style="{ StaticResource CardViewDetailStyle }" />

  </StackLayout>

</ControlTemplate>

5. Add the Theme-specific Resources

Because this is a custom control, add the resources that match the theme you are using the resource dictionary:

Light Theme Colors

<Color x:Key="iOSCardViewBackgroundColor">#FFFFFF</Color>
<Color x:Key="AndroidCardViewBackgroundColor">#FFFFFF</Color>

<Color x:Key="AndroidCardViewTextTextColor">#030303</Color>
<Color x:Key="iOSCardViewTextTextColor">#030303</Color>

<Color x:Key="AndroidCardViewDetailTextColor">#8F8E94</Color>
<Color x:Key="iOSCardViewDetailTextColor">#8F8E94</Color>

Dark Theme Colors

<!-- CARD VIEW COLORS -->
            <Color x:Key="iOSCardViewBackgroundColor">#404040</Color>
            <Color x:Key="AndroidCardViewBackgroundColor">#404040</Color>

            <Color x:Key="AndroidCardViewTextTextColor">#FFFFFF</Color>
            <Color x:Key="iOSCardViewTextTextColor">#FFFFFF</Color>

            <Color x:Key="AndroidCardViewDetailTextColor">#B5B4B9</Color>
            <Color x:Key="iOSCardViewDetailTextColor">#B5B4B9</Color>

6. Set the ControlTemplate for the CardView class

Finally, ensure the C# class created in step 1 uses the control template defined in step 4 using a Style Setter element

<Style TargetType="local:CardView">
    <Setter Property="ControlTemplate" Value="{ StaticResource CardViewControlControlTemplate }" />
  ... some custom styling omitted
  <Setter Property="BackgroundColor" Value="{ StaticResource CardViewBackgroundColor }" />
</Style>

7. Add the Control to a Page

The CardView control can now be added to a page. The example below shows it hosted in a StackLayout:

<StackLayout Spacing="0">
  <local:CardView
    Margin="12,6"
    ImageSource="{ DynamicResource CardViewImage }"
    Text="CardView Text"
    Detail="CardView Detail"
  />
</StackLayout>

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.