CustomItemMetadata Class

A base class that contains metadata for custom dashboard items.

Namespace : DevExpress.DashboardCommon

Assembly : DevExpress.Dashboard.v25.2.Core.dll

NuGet Package : DevExpress.Dashboard.Core

Declaration

C#
VB.NET

csharp

public abstract class CustomItemMetadata

Public MustInherit Class CustomItemMetadata

Remarks

Metadata is a specialization of the CustomItemMetadata base class. It describes options and settings available to a user in the UI. A dashboard uses the structure you specify in metadata to store custom item settings in a dashboard definition.

Follow the steps below to create metadata for a custom dashboard item:

Derive a Class from CustomItemMetadata

You can apply the following attributes to a CustomItemMetadata object:

Name	Description
DisplayNameAttribute	Specifies a name for a custom item’s icon.
CustomItemDescriptionAttribute	Specifies tooltip text that is displayed for a custom item’s bar in the Ribbon.
CustomItemImageAttribute	Specifies an icon for a custom item’s bar in the Ribbon.

The code snippet below shows how to create a CustomItemMetadata descendant (CustomFunnelMetadata) and define its attributes to specify a custom item’s bar in the Ribbon:

C#
VB.NET

csharp

using System.ComponentModel;
using DevExpress.DashboardCommon;

namespace CustomItemsSample {
  [DisplayName("Funnel"),
  CustomItemDescription("Funnel description"),
  CustomItemImage("CustomItemsSample.Images.Funnel.svg")]
  public class CustomFunnelMetadata : CustomItemMetadata {
  }
}

Imports System.ComponentModel
Imports DevExpress.DashboardCommon

Namespace CustomItemsSample
<DisplayName("Funnel"), CustomItemDescription("Funnel description"), CustomItemImage("Funnel.svg")>
Public Class CustomFunnelMetadata
    Inherits CustomItemMetadata
End Class
End Namespace

Declare Properties in the Derived Class

Create public or readonly Measure/Dimension collection properties. These properties correspond to data sections in the Data Items pane.

Use collection properties if you need a custom section that contains several data items (like Arguments/Series sections in a Chart dashboard item):

C#
VB.NET

csharp

public DimensionCollection Arguments { get; } = new DimensionCollection();

Public ReadOnly Property Arguments() As New DimensionCollection()

If you need a section with an individual data item, create a single Measure/Dimension property:

C#
VB.NET

csharp

public Measure Value {
        get { return GetPropertyValue<Measure>(); }
        set { SetPropertyValue(value); }
}

Public Property Value() As Measure
  Get
      Return GetPropertyValue(Of Measure)()
  End Get
  Set(ByVal value As Measure)
      SetPropertyValue(value)
  End Set
End Property

You can apply the following attributes to properties:

Name	Description
DisplayNameAttribute	Specifies a data section’s name in the Data Items pane.
EmptyDataItemPlaceholderAttribute	Specifies placeholder text for a pane where you can place a data item.
SupportColoringAttribute	Specifies whether data items in a section support coloring.
SupportInteractivityAttribute	Specifies whether data items in a data section support interactivity.
SupportedDataTypesAttribute	Specifies types of data fields that can be used for data items in a section.
DefaultGroupIntervalAttribute	Specifies the default group interval for data items.

The following code snippet shows how to create metadata for a CustomFunnelMetadata object:

C#
VB.NET

csharp

using System.ComponentModel;
using DevExpress.DashboardCommon;

namespace CustomItemsSample {
  [DisplayName("Funnel"),
  CustomItemDescription("Funnel description"),
  CustomItemImage("CustomItemsSample.Images.Funnel.svg")]
  public class CustomFunnelMetadata : CustomItemMetadata{
     [DisplayName("Value"),
      EmptyDataItemPlaceholder("Value"),
      SupportColoring(DefaultColoringMode.Hue)]
      public Measure Value {
          get { return GetPropertyValue<Measure>(); }
          set { SetPropertyValue(value); }
      }
      [DisplayName("Arguments"),
      EmptyDataItemPlaceholder("Argument"),
      SupportColoring(DefaultColoringMode.Hue),
      SupportInteractivity]
      public DimensionCollection Arguments { get; } = new DimensionCollection();
  }
}

Imports System.ComponentModel
Imports DevExpress.DashboardCommon

Namespace CustomItemsSample
  <DisplayName("Funnel"), CustomItemDescription("Funnel description"), CustomItemImage("Funnel.svg")>
  Public Class CustomFunnelMetadata
      Inherits CustomItemMetadata
      <DisplayName("Value"), EmptyDataItemPlaceholder("Value"), SupportColoring(DefaultColoringMode.Hue)>
      Public Property Value() As Measure
          Get
              Return GetPropertyValue(Of Measure)()
          End Get
          Set(ByVal value As Measure)
              SetPropertyValue(value)
          End Set
      End Property
      <DisplayName("Arguments"), EmptyDataItemPlaceholder("Argument"), SupportColoring(DefaultColoringMode.Hue), SupportInteractivity>
      Public ReadOnly Property Arguments() As New DimensionCollection()
  End Class
End Namespace

Add a Button to the Ribbon

Call the DashboardDesigner.CreateCustomItemBars(Type[]) method that inserts a custom item’s bar in the Ribbon. To create a custom item in the Dashboard Designer, click the bar.

The code snippet below adds the Funnel custom item’s bar in the Ribbon:

C#
VB.NET

csharp

using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;

namespace CustomItemsSample {
public partial class Form1 : Form {
  public Form1() {
      InitializeComponent();
      dashboardDesigner1.CreateRibbon();
      dashboardDesigner1.CreateCustomItemBars();
  }
}

Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin

Namespace CustomItemsSample
Partial Public Class Form1
  Inherits Form
  Public Sub New()
    InitializeComponent()
    dashboardDesigner1.CreateRibbon()
    dashboardDesigner1.CreateCustomItemBars()
  End Sub
End Class

Register a New Metadata Type

You should call the CustomItemMetadataTypes.Register<T>() method before the main application form is created. Pass a new metadata type to the method. This allows the dashboard control to read custom item data from a dashboard.

The following code snippet shows how to register the CustomFunnelMetadata metadata type:

C#
VB.NET

csharp

using DevExpress.XtraEditors;
using System;
using System.Windows.Forms;
using DevExpress.DashboardCommon;

namespace CustomItemsSample {
    static class Program {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main() {
          //...
          Dashboard.CustomItemMetadataTypes.Register<CustomFunnelMetadata>();
          Application.Run(new Form1());
        }
    }
}

Imports DevExpress.XtraEditors
Imports System
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon

Namespace CustomItemsSample
    Friend NotInheritable Class Program
        ''' <summary>
        ''' The main entry point for the application.
        ''' </summary>
        Private Sub New()
        End Sub
        <STAThread> _
        Shared Sub Main()
          '...
          Dashboard.CustomItemMetadataTypes.Register(Of CustomFunnelMetadata)()
          Application.Run(New Form1())
        End Sub
    End Class
End Namespace

The Dashboard Designer automatically creates a binding panel based on CustomFunnelChart metadata for the custom item.

Once you have registered a metadata type, derive a class from CustomControlProviderBase.

Refer to the following topic for details:

CustomControlProviderBase

Inheritance

Object CustomItemMetadata