PivotGridField.ValueTemplate Property

Gets or sets a template used to display values of the current field. This is a dependency property.

Namespace: DevExpress.Xpf.PivotGrid

Assembly: DevExpress.Xpf.PivotGrid.v20.2.dll

NuGet Packages: DevExpress.WindowsDesktop.Wpf.PivotGrid, DevExpress.Wpf.PivotGrid

Declaration

C#

public DataTemplate ValueTemplate { get; set; }

VB.NET

Public Property ValueTemplate As DataTemplate

Property Value

Type	Description
DataTemplate	A DataTemplate object representing the template used to display values of the current field.

Remarks

If the ValueTemplate is not specified, the field values are displayed via the PivotGridControl.FieldValueTemplate template. The PivotGridField.ActualValueTemplate property allows you to obtain which template is currently used.

You can implement custom logic to choose the required template using the PivotGridField.ValueTemplateSelector property.

Example

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>

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the ValueTemplate property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

XAML

how-to-create-the-field-value-template-e2191/CS/HowToCreateFieldValueTemplate/MainWindow.xaml#L28

<dxpg:PivotGridField Name="fieldCategoryName" FieldName="CategoryName" Area="RowArea"
                     ValueTemplate="{StaticResource  ResourceKey=ProductsTemplate}"
                     Caption="Product Category"/>