Building a Simple Card Control in Avalonia

Published on

I noticed this closed discussion in the AvaloniaUI repository discussions that didn't exactly ring clear to me when I came across it as it just left me with the question:

But how can I also provide a basic template their content is displayed in?

Naturally, the AvaloniaUI repo discussions section is probably not the place for people to do your homework for you, but I wanted to take a little time to demonstrate how you can build a simple "Card" control that accepts user provided content as well as provides a basic template.

The Documentation

The first place to take a look is, of course, the documentation which can be found at How To Create a Custom Control.

We can see there's two types of custom control to implement, with the choices being:

  • Templated Custom Control
  • Custom Control
  • User Control - a high-level approach for Custom Controls

For our purposes we can use a custom control and leverage the existing ContentControl templated control to provide our content presenter which allows consumers to pass in other controls to be rendered.

The steps defined in the documentation are:

  1. Define the control class
  2. Create the control template
  3. Styling and templating

The Control Class

For our simple card, our control's class is going to inherit from ContentControl and to demonstrate a little more extensibility, we're going to expose a Title property which can be set by the consumer.

Card.cs

public class Card : ContentControl
{
    public static readonly StyledProperty<string> TitleProperty =
        AvaloniaProperty.Register<Card, string>(nameof(Title), "");

    public string Title
    {
        get => GetValue(TitleProperty);
        set => SetValue(TitleProperty, value);
    }
}

We register our TitleProperty and expose it with the required getter and setter. This can then be used by the consumer with <ns:Card Title="My Card"></ns:Card>.

The Control Theme

Next we want to create a control theme that specifies the visual appearance and structure of the control.

Card.xaml

<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:controls="using:MyControls.Controls">

    <ControlTheme x:Key="{x:Type controls:Card}" TargetType="controls:Card">
        <Setter Property="Background" Value="LightGray" />
        <Setter Property="HorizontalAlignment" Value="Stretch" />
        <Setter Property="CornerRadius" Value="8" />
        <Setter Property="Margin" Value="5, 0, 10, 10" />
        <Setter Property="Padding" Value="15" />
    </ControlTheme>
</ResourceDictionary>

What About User Content?

One of the things that seems to be missing from documentation and you can only really find by looking into the source for existing templated controls, is how to make use of the Template property and its corresponding ControlTemplate.

Using this, we can extend our control to wrap the ContentPresenter with a border and title.

Card.xaml

<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:controls="using:MyControls.Controls">

    <ControlTheme x:Key="{x:Type controls:Card}" TargetType="controls:Card">
        <Setter Property="Background" Value="LightGray" />
        <Setter Property="HorizontalAlignment" Value="Stretch" />
        <Setter Property="CornerRadius" Value="8" />
        <Setter Property="Margin" Value="5, 0, 10, 10" />
        <Setter Property="Padding" Value="15" />
        <Setter Property="Template">
            <ControlTemplate>
                <Border Background="{TemplateBinding Background}"
                        HorizontalAlignment="{TemplateBinding HorizontalAlignment}"
                        CornerRadius="{TemplateBinding CornerRadius}"
                        Margin="{TemplateBinding Margin}"
                        Padding="{TemplateBinding Padding}">
                    <StackPanel Orientation="Vertical">
                        <TextBlock 
                            Margin="0,0,0,5"
                            FontSize="16"
                            Text="{TemplateBinding Title}">
                        </TextBlock>
                        <Border Padding="5">
                            <ContentPresenter Name="PART_ContentPresenter"
                                              ContentTemplate="{TemplateBinding ContentTemplate}"
                                              Content="{TemplateBinding Content}"/>
                        </Border>
                    </StackPanel>
                </Border>
            </ControlTemplate>
        </Setter>
    </ControlTheme>
</ResourceDictionary>

And there we have it! A simple card control we can use like so:

<ns:Card Title="My Card">
    <TextBlock Text="Some card content!" />
</ns:Card>

Summary

This post I covered some of the Avalonia documentation and how it can be applied to making a custom control that allows for consumers to render content within a reusable template.

Having reusable controls like this should help serve to keep your Avalonia views cleaner with DRY and KISS principles.