Skip to main content
All docs
V21.2

CustomItemMetadata Class

A base class that contains metadata for custom dashboard items.

Namespace: DevExpress.DashboardCommon

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

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:

The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomItemMetadata class.

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.

Inheritance

Object
CustomItemMetadata
See Also