Skip to main content
All docs
V24.1

CustomItemMetadata Class

A base class that contains metadata for custom dashboard items.

Namespace: DevExpress.DashboardCommon

Assembly: DevExpress.Dashboard.v24.1.Core.dll

NuGet Package: DevExpress.Dashboard.Core

Declaration

public abstract 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:

using System.ComponentModel;
using DevExpress.DashboardCommon;

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

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):

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

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

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

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:

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();
  }
}

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:

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

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

win-custom-funnel-icon

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:

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());
        }
    }
}

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

Funnel custom item binding panel

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

Refer to the following topic for details:

Inheritance

Object
CustomItemMetadata
See Also