How to: Create the Field Value Template

• Jun 07, 2019
• 6 minutes to read

This example demonstrates how to define a custom template used to display field values. The template in this example displays field values with images, as shown in the picture below.

Tip

A complete sample project is available in the DevExpress Code Examples database at https://supportcenter.devexpress.com/ticket/details/e2191/pivot-grid-for-wpf-how-to-create-a-field-value-template.

A custom control CategoriesControl displays the field’s text along with the related image. The required information is retrieved from the DataContext which is converted to the FieldValueElementData type.

A template for a certain field is assigned to the PivotGridField.ValueTemplate property . Also, you can use PivotGridControl.FieldValueTemplate property to apply a custom template to all field values.

C#

using DevExpress.Xpf.PivotGrid;
using HowToCreateFieldValueTemplate.CategoryPicturesTableAdapters;
using System;
using System.Collections.Generic;
using System.IO;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Media;
using System.Windows.Media.Imaging;

namespace HowToCreateFieldValueTemplate
{
    public class CategoriesControl : Control, IWeakEventListener {

        #region static staff
        static CategoriesTableAdapter categoriesTableAdapter;
        static Dictionary<string, ImageSource> categoriesPictures;
        public static readonly DependencyProperty ImageSourceProperty;

        static CategoriesControl() {
            DefaultStyleKeyProperty.OverrideMetadata(typeof(CategoriesControl), 
                new FrameworkPropertyMetadata(typeof(CategoriesControl)));
            Type ownerType = typeof(CategoriesControl);
            ImageSourceProperty = DependencyProperty.Register("ImageSource", typeof(ImageSource),
                   ownerType, new UIPropertyMetadata());
            categoriesPictures = new Dictionary<string, ImageSource>();
        }

        static CategoriesTableAdapter CategoriesTableAdapter {
            get {
                if(categoriesTableAdapter == null)
                    categoriesTableAdapter = new CategoriesTableAdapter();
                return categoriesTableAdapter;
            }
        }

        static ImageSource GetImage(string categoryName) {
            if(string.IsNullOrEmpty(categoryName)) return null;
            if(categoriesPictures.ContainsKey(categoryName)) {
                return categoriesPictures[categoryName];
            } else {
                byte[] icon = CategoriesTableAdapter.GetIconImageByName(categoryName) as byte[];
                if(icon == null || icon.Length == 0) {
                    return null;
                }
                BitmapDecoder img = new PngBitmapDecoder(new MemoryStream(icon), 
                    BitmapCreateOptions.None, 
                    BitmapCacheOption.OnLoad);
                ImageSource imageSource = img.Frames[0];
                if(imageSource.Height < 1) return null;
                categoriesPictures.Add(categoryName, imageSource);
                return imageSource;
            }
        }

        #endregion

        public CategoriesControl()
            : base() {
            FrameworkElementDataContextChangedEventManager.AddListener(this, this);
            Unloaded += OnUnloaded;
        }

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

        void OnUnloaded(object sender, RoutedEventArgs e) {
            ImageSource = null;
        }
        void OnDataContextChanged() {
            SetImageSource();
        }
        void SetImageSource() {
            FieldValueElementData item = this.DataContext as FieldValueElementData;
            if(item != null && !item.IsOthersRow && !string.IsNullOrEmpty(item.DisplayText)) {
                ImageSource = CategoriesControl.GetImage(item.Value as string);
            } else {
                ImageSource = null;
            }
        }

        #region IWeakEventListener Members
        bool IWeakEventListener.ReceiveWeakEvent(Type managerType, object sender, EventArgs e) {
            return OnReceiveWeakEvent(managerType, e);
        }
        protected virtual bool OnReceiveWeakEvent(Type managerType, EventArgs e) {
            if(managerType == typeof(FrameworkElementDataContextChangedEventManager)) {
                OnDataContextChanged();
                return true;
            }
            return false;
        }
        #endregion

        #region FrameworkElementDataContextChangedEventManager

        public class FrameworkElementDataContextChangedEventManager : WeakEventManager {
            static FrameworkElementDataContextChangedEventManager CurrentManager {
                get {
                    Type managerType = typeof(FrameworkElementDataContextChangedEventManager);
                    FrameworkElementDataContextChangedEventManager currentManager =
                        (FrameworkElementDataContextChangedEventManager)WeakEventManager
                        .GetCurrentManager(managerType);
                    if(currentManager == null) {
                        currentManager = new FrameworkElementDataContextChangedEventManager();
                        WeakEventManager.SetCurrentManager(managerType, currentManager);
                    }
                    return currentManager;
                }
            }

            FrameworkElementDataContextChangedEventManager() { }

            public static void AddListener(FrameworkElement source, IWeakEventListener listener) {
                CurrentManager.ProtectedAddListener(source, listener);
            }
            public static void RemoveListener(FrameworkElement source, IWeakEventListener listener) {
                CurrentManager.ProtectedRemoveListener(source, listener);
            }
            protected override void StartListening(object source) {
                FrameworkElement FrameworkElement = (FrameworkElement)source;
                FrameworkElement.DataContextChanged += OnDataContextChanged;
            }
            protected override void StopListening(object source) {
                FrameworkElement FrameworkElement = (FrameworkElement)source;
                FrameworkElement.DataContextChanged -= OnDataContextChanged;
            }
            void OnDataContextChanged(object sender, DependencyPropertyChangedEventArgs e) {
                base.DeliverEvent(sender, null);
            }
        }
        #endregion
    }
}

VB.NET

Imports DevExpress.Xpf.PivotGrid
Imports HowToCreateFieldValueTemplate.CategoryPicturesTableAdapters
Imports System
Imports System.Collections.Generic
Imports System.IO
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Media
Imports System.Windows.Media.Imaging

Namespace HowToCreateFieldValueTemplate
    Public Class CategoriesControl
        Inherits Control
        Implements IWeakEventListener

        #Region "static staff"

        Private Shared categoriesTableAdapter_Renamed As CategoriesTableAdapter
        Private Shared categoriesPictures As Dictionary(Of String, ImageSource)
        Public Shared ReadOnly ImageSourceProperty As DependencyProperty

        Shared Sub New()
            DefaultStyleKeyProperty.OverrideMetadata(GetType(CategoriesControl), New FrameworkPropertyMetadata(GetType(CategoriesControl)))
            Dim ownerType As Type = GetType(CategoriesControl)
            ImageSourceProperty = DependencyProperty.Register("ImageSource", GetType(ImageSource), ownerType, New UIPropertyMetadata())
            categoriesPictures = New Dictionary(Of String, ImageSource)()
        End Sub

        Private Shared ReadOnly Property CategoriesTableAdapter() As CategoriesTableAdapter
            Get
                If categoriesTableAdapter_Renamed Is Nothing Then
                    categoriesTableAdapter_Renamed = New CategoriesTableAdapter()
                End If
                Return categoriesTableAdapter_Renamed
            End Get
        End Property

        Private Shared Function GetImage(ByVal categoryName As String) As ImageSource
            If String.IsNullOrEmpty(categoryName) Then
                Return Nothing
            End If
            If categoriesPictures.ContainsKey(categoryName) Then
                Return categoriesPictures(categoryName)
            Else
                Dim icon() As Byte = TryCast(HowToCreateFieldValueTemplate.CategoryPicturesTableAdapters.CategoriesTableAdapter.GetIconImageByName(categoryName), Byte())
                If icon Is Nothing OrElse icon.Length = 0 Then
                    Return Nothing
                End If
                Dim img As BitmapDecoder = New PngBitmapDecoder(New MemoryStream(icon), BitmapCreateOptions.None, BitmapCacheOption.OnLoad)

                Dim imageSource_Renamed As ImageSource = img.Frames(0)
                If imageSource_Renamed.Height < 1 Then
                    Return Nothing
                End If
                categoriesPictures.Add(categoryName, imageSource_Renamed)
                Return imageSource_Renamed
            End If
        End Function

        #End Region

        Public Sub New()
            MyBase.New()
            FrameworkElementDataContextChangedEventManager.AddListener(Me, Me)
            AddHandler Unloaded, AddressOf OnUnloaded
        End Sub

        Public Property ImageSource() As ImageSource
            Get
                Return DirectCast(GetValue(ImageSourceProperty), ImageSource)
            End Get
            Set(ByVal value As ImageSource)
                SetValue(ImageSourceProperty, value)
            End Set
        End Property

        Private Sub OnUnloaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ImageSource = Nothing
        End Sub
        Private Sub OnDataContextChanged()
            SetImageSource()
        End Sub
        Private Sub SetImageSource()
            Dim item As FieldValueElementData = TryCast(Me.DataContext, FieldValueElementData)
            If item IsNot Nothing AndAlso Not item.IsOthersRow AndAlso Not String.IsNullOrEmpty(item.DisplayText) Then
                ImageSource = CategoriesControl.GetImage(TryCast(item.Value, String))
            Else
                ImageSource = Nothing
            End If
        End Sub

        #Region "IWeakEventListener Members"
        Private Function IWeakEventListener_ReceiveWeakEvent(ByVal managerType As Type, ByVal sender As Object, ByVal e As EventArgs) As Boolean Implements IWeakEventListener.ReceiveWeakEvent
            Return OnReceiveWeakEvent(managerType, e)
        End Function
        Protected Overridable Function OnReceiveWeakEvent(ByVal managerType As Type, ByVal e As EventArgs) As Boolean
            If managerType Is GetType(FrameworkElementDataContextChangedEventManager) Then
                OnDataContextChanged()
                Return True
            End If
            Return False
        End Function
        #End Region

        #Region "FrameworkElementDataContextChangedEventManager"

        Public Class FrameworkElementDataContextChangedEventManager
            Inherits WeakEventManager

            Private Shared ReadOnly Property CurrentManager() As FrameworkElementDataContextChangedEventManager
                Get
                    Dim managerType As Type = GetType(FrameworkElementDataContextChangedEventManager)

                    Dim currentManager_Renamed As FrameworkElementDataContextChangedEventManager = CType(WeakEventManager.GetCurrentManager(managerType), FrameworkElementDataContextChangedEventManager)
                    If currentManager_Renamed Is Nothing Then
                        currentManager_Renamed = New FrameworkElementDataContextChangedEventManager()
                        WeakEventManager.SetCurrentManager(managerType, currentManager_Renamed)
                    End If
                    Return currentManager_Renamed
                End Get
            End Property

            Private Sub New()
            End Sub

            Public Shared Sub AddListener(ByVal source As FrameworkElement, ByVal listener As IWeakEventListener)
                CurrentManager.ProtectedAddListener(source, listener)
            End Sub
            Public Shared Sub RemoveListener(ByVal source As FrameworkElement, ByVal listener As IWeakEventListener)
                CurrentManager.ProtectedRemoveListener(source, listener)
            End Sub
            Protected Overrides Sub StartListening(ByVal source As Object)
                Dim FrameworkElement As FrameworkElement = DirectCast(source, FrameworkElement)
                AddHandler FrameworkElement.DataContextChanged, AddressOf OnDataContextChanged
            End Sub
            Protected Overrides Sub StopListening(ByVal source As Object)
                Dim FrameworkElement As FrameworkElement = DirectCast(source, FrameworkElement)
                RemoveHandler FrameworkElement.DataContextChanged, AddressOf OnDataContextChanged
            End Sub
            Private Sub OnDataContextChanged(ByVal sender As Object, ByVal e As DependencyPropertyChangedEventArgs)
                MyBase.DeliverEvent(sender, Nothing)
            End Sub
        End Class
        #End Region
    End Class
End Namespace

MainWindow.xaml

<Window x:Class="HowToCreateFieldValueTemplate.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
        xmlns:dxpg="http://schemas.devexpress.com/winfx/2008/xaml/pivotgrid"
        xmlns:example="clr-namespace:HowToCreateFieldValueTemplate"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"        
        Title="MainWindow" Height="350" Width="525" Loaded="Window_Loaded" >
    <Window.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="CategoriesControl.xaml" />
            </ResourceDictionary.MergedDictionaries>
            <DataTemplate x:Key="ProductsTemplate" >
                <example:CategoriesControl />
            </DataTemplate>
        </ResourceDictionary>
    </Window.Resources>
    <Grid>
        <dxpg:PivotGridControl HorizontalAlignment="Left" Name="pivotGridControl1"
                               VerticalAlignment="Top">
            <dxpg:PivotGridControl.Fields>
                <dxpg:PivotGridField Name="fieldCountry" FieldName="Country" Area="ColumnArea" />
                <dxpg:PivotGridField Name="fieldCustomer" FieldName="Sales Person" Area="ColumnArea" 
                                     Caption="Customer" />
                <dxpg:PivotGridField Name="fieldYear" FieldName="OrderDate" Area="RowArea" 
                                     Caption="Year" GroupInterval="DateYear" />
                <dxpg:PivotGridField Name="fieldCategoryName" FieldName="CategoryName" Area="RowArea" 
                                     ValueTemplate="{StaticResource  ResourceKey=ProductsTemplate}"
                                     Caption="Product Category"/>
                <dxpg:PivotGridField Name="fieldExtendedPrice" FieldName="Extended Price"
                                     Area="DataArea" CellFormat="c0" />
            </dxpg:PivotGridControl.Fields>
        </dxpg:PivotGridControl>
    </Grid>
</Window>

CategoriesControl.xaml

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
                    xmlns:example="clr-namespace:HowToCreateFieldValueTemplate"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Style TargetType="example:CategoriesControl">
        <Style.Setters>
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="example:CategoriesControl">
                        <StackPanel Orientation="Horizontal">
                            <Image Stretch="UniformToFill" 
                        Source="{Binding ImageSource, RelativeSource={RelativeSource TemplatedParent}}"/>
                            <dxe:TextEdit Name="text" VerticalAlignment="Center" EditMode="InplaceInactive"                                           
                                          Text="{Binding Path=DisplayText, Mode=OneWay}" 
                                          TextTrimming="CharacterEllipsis" />
                        </StackPanel>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style.Setters>
    </Style>
</ResourceDictionary>