How to create a widget

A custom widget is a class in an add-in that implements the ESRI.ArcGIS.OperationsCenter.IWidget interface, and also inherits from UserControl. It must have an Export attribute with the value ESRI.ArcGIS.OperationsDashboard.Widget. It should also have ExportMetadata attributes to set DisplayName, Description and ImagePath attributes. Other optional attributes and interfaces can add additional functionality.

The simplest way to create a new custom widget is to use the Widget item template available in Visual Studio for Operations Dashboard for ArcGIS.

Creating a new widget

1. Open an existing add-in project or create a new one by following the steps in the Getting started topic.
2. Click Project -> Add New Item.

   The New Item dialog box appears with the list of installed templates.

3. Navigate to Visual C# or Visual Basic > WPF > ArcGIS.
4. Select the Operations Dashboard for ArcGIS Widget template, enter a Name, and click OK.

The following items are added to the project:

• A new Widget.xaml file providing the user interface of the widget dockable window.
• A corresponding Widget.xaml.cs/.vb code behind file. This item defines the custom widget and provides a default implementation of IWidget and IDataSourceConsumer (see below).
• A Config folder containing a WidgetDialog.xaml file with corresponding WidgetDialog.xaml.cs/.vb code behind file. This item defines a default implementation of a configuration dialog for the custom widget.
• An Images folder containing an image file. This item defines the icon for the custom widget.

Essential elements of a widget

The following essential elements of a widget are automatically generated by the item template, with default values and implementation. Edits to these elements may be required when the default implementation is adapted.

• IWidget interface: The IWidget interface must be implemented on a widget class. This provides the minimum contract for a widget to be hosted inside a dockable window in the application, defining essential identification, activation and configuration members for custom widgets. See the API Reference help for information on implementing each member of this interface.
• Export attribute: An Export attribute with the value "ESRI.ArcGIS.OperationsDashboard.Widget" is required on the widget class. This attribute is defined in the System.ComponentModel.Composition namespace, part of the .NET Framework that provides the Managed Extensibility Framework (MEF). The application uses MEF to find and load custom add-ins and the types they contain.
• Serializing attributes: A DataContract attribute is required on the widget class, and DataMember attributes are required on any members which must be serialized to the operation view when the operation view containing the widget is saved. For example, the IDataSourceConsumer.DataSourceIds property should be persisted to ensure the same data source is identified if the view is saved and later re-opened. These attributes are defined in the System.Runtime. Serialization namespace, part of the .NET Framework providing serialization and deserialization support. See the Serializing add-in properties topic for more information.
• Metadata attributes: Three ExportMetadata attributes are required on the widget class to define information shown about the widget before the assembly is loaded, in the Manage Add-Ins and Add Widget dialog boxes. The names of these attributes should be DisplayName, Description, and ImagePath, all with appropriate values. The widget item template, and sample widgets, that are part of the SDK demonstrate appropriate values. This attribute is again defined in the System.ComponentModel.Composition namespace.

Optional elements of a widget

The additional areas of functionality can be implemented on a widget, if the workflow being developed requires them.

ExportMetadata attribute with DataSourceRequired

ExportMetadata attribute with the name DataSourceRequired is optionally applied to a widget class, with a boolean value indicating if the widget requires data sources in order to function correctly. If the attribute value is true, within the Add Widget dialog box in the application, the widget is only enabled if there are data sources defined in the application; if the value is false, the widget is enabled regardless of the presence of data sources. If the attribute is not present, the application assumes a value of true. The use of this attribute allows the application to function more efficiently, by enabling or disabling widgets in the list without needing to create an instance of each type of widget in order to determine if it is dependent on data sources.

An ExportMetadata attribute with the name DataSourceRequired and the value true is added by default in the widget created using the Widget template, as the IDataSourceConsumer interface is implemented. To create a widget that can be added to an operation view if no data sources are present, add the ExportMetadata attribute with a name DataSourceRequired and a value false.

IDataSourceConsumer interface

Most out-of-the-box widgets shows information about a data source, for example the gauge widget shows a statistic calculated on a specific field in a specific data source.

To create a widget that shows information about a data source, implement the IDataSourceConsumer interface which provides members to notify the consuming widget about changes to the data source. Information about the features and attributes in the data source is found by using the query methods on the DataSource class.

See the Working with data sources and How to respond to changes in data sources topics for more information. Also, see the API Reference help for information on implementing each member of this interface.

Configuration

All out-of-the-box widgets are configurable–they allow the operation view author to choose the information displayed in the widget, and how it is displayed. For example, all data source consumer widgets allow the author to choose the data source used. However, configuration is optional.

To make a widget configurable, return true from the IWidget.CanConfigure method–the application will then call the Configure method before adding a new instance of the widget to the operation view. If the CanConfigure method returns false, the widget will be added to the application directly. See the API Reference help for other information on implementing the CanConfigure and Configure members of IWidget. See the Count widget sample for an example of a configurable widget.

IMapConsumer interface

Some widgets show information relating to a specific map widget, instead of that relating to a data source. For example, the legend widget shows a legend of symbols used in a specific map widget. When there is more than one map widget in an operation view, a color theme is applied to widgets to inform the user which widgets are related, based on the map or data source they consume.

Implementing the IMapConsumer interface allows a widget to participate in this color theming when the widget does not consume a specific data source. See the API Reference help for information on implementing this interface.

Feature action support

Custom feature actions provide new options for dealing with a single feature from a data source, and are made available in some widgets that represent information for individual features. For example, list widget allows an operation view author to determine the feature actions that are available from the widget for a specific feature in the list. Feature actions can then be shown in a context menu for each feature in the list.

Classes are available to represent and execute each type of out-of-the-box feature action, for example the PanToFeatureAction and HighlightFeatureAction. The FeatureActionContextMenu in the ESRI.ArcGIS.OperationsDashboard.Controls namespace can be used to show and execute feature actions in a context menu for a custom widget, including both the out-of-the-box and custom feature actions. The list of available feature actions can be hardcoded, or can be configurable by the author. If allowing configuration of the available feature actions, the FeatureActionList and FeatureActionSelector controls can be used to help display, arrange, and configure the feature actions. The add-in developer is responsible for persisting the feature actions selected, their order, and any configuration settings made, as part of the data persisted by the widget class.

For an example of a widget that supports feature actions, using the FeatureActionList and FeatureActionContextMenu, see the Widget with feature actions sample. For more information on the FeatureActionContextMenu, FeatureActionList, FeatureActionSelector, and feature action classes, see the API Reference help.