Working with the extensibility API

ArcGIS for SharePoint includes an extensibility API that provides Map Web Part extension developers with access to the map and selected layer, methods to show the UI in dialog boxes, and the ability to store and load configuration data. All the functionality exposed by the extensibility API is available in the ESRI.ArcGIS.Client.Extensibility assembly. To take advantage of this functionality, add a reference to this assembly to your Visual Studio project.

Working with the map and selected layer

The map and selected layer can be accessed through properties on the static ESRI.ArcGIS.Client.Extensibility.MapApplication object. The MapApplication object is available to any Map Web Part extension via the MapApplication.Current property, so to access the Map Web Part map object, use MapApplication.Current.Map in your extension code. To access the selected layer, use MapApplication.Current.SelectedLayer. The code for the simple command in the Writing commands topic demonstrates accessing the map in the CanExecute method. The code below shows another example of a simple command, but in this case, the selected layer's ID is shown when the command is executed, and the logic in the CanExecute method is such that the command is enabled only if a GraphicsLayer is selected.

[Export(typeof(ICommand))]
[DisplayName("Show GraphicsLayer ID")]
public class ShowGraphicsLayerIdCommand : ICommand
{
     public void Execute(object parameter)
     {
          // Show the selected layer's ID
          MessageBox.Show(MapApplication.Current.SelectedLayer.ID);
     }    
 
     public bool CanExecute(object parameter)
     {
          // Return true (i.e. make the command executable) only if the selected layer is a GraphicsLayer
          return MapApplication.Current.SelectedLayer is GraphicsLayer;
     }
 
     public event EventHandler CanExecuteChanged;
}

The extensibility API also provides an event that fires when the selected layer changes, along with methods to retrieve and set the names of layers. Layer names are how layers are identified on the Map Contents panel. A layer name differs from a layer ID in that it is meant to be an intuitive name to identify a layer to end users of the Map Web Part, whereas an ID is meant to uniquely identify a layer in the map's layer collection from a programmatic perspective. The SelectedLayerChanged event can be accessed via MapApplication.Current.SelectedLayerChanged. Layer names can be retrieved and set through the MapApplication.Current.GetLayerName and MapApplication.Current.SetLayerName methods. The code below shows simple behavior that displays the selected layer's name in a message box when the that layer changes:

[Export(typeof(Behavior<Map>))]
[DisplayName("Show Selected Layer Name Behavior")]
public class ShowSelectedLayerNameBehavior : Behavior<Map>
{
     protected override void OnAttached()
     {
          base.OnAttached();
 
          // Add a handler to the applications's SelectedLayerChanged event
          MapApplication.Current.SelectedLayerChanged += ShowSelectedLayerName;
     }
 
     private void ShowSelectedLayerName(sender s, EventArgs args)
     {
          // Show a message box with the selected layer name
          string layerName = MapApplication.Current.SelectedLayer.GetValue(MapApplication.LayerNameProperty) as string;
          MessageBox.Show(layerName);
     }
 
     protected override void OnDetaching()
     {
          // Remove the handler from the application's SelectedLayerChanged event
          MapApplication.Current.SelectedLayerChanged -= ShowSelectedLayerName;
     }
}

Displaying dialog boxes

To expose a UI within the Map Web Part, the extensibility API provides two methods—ShowWindow and HideWindow. In Map Web Part extensions, these methods are available off of MapApplication.Current. ShowWindow displays any FrameworkElement in a floating dialog window. To do so, pass the object you want to display to the ShowWindow method. This method also takes the title of the dialog box as a string and optionally accepts (1) a Boolean to determine whether the dialog box is modal, (2) an event handler that is called when the dialog box starts closing, and (3) a second event handler that is called when the dialog box completes closing. To close the dialog box, pass the same FrameworkElement to the HideWindow.

For an example of displaying Silverlight UI in the Map Web Part, suppose that you have implemented the UserControl with the default code-behind class and the XAML markup shown below:

<UserControl x:Class="MyExtension.SimpleDialog"
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
     mc:Ignorable="d"
     d:DesignHeight="300" d:DesignWidth="400">
     <Grid x:Name="LayoutRoot" Background="Transparent">
          <TextBlock Text="This is my Silverlight UI!" Margin="20" />
     </Grid>
</UserControl>

Note:

The Map Web Part sets the background color of dialog boxes according to the web part's theme. As shown in the XAML markup, you should usually specify a transparent background for UI components that will be displayed in Map Web Part dialog boxes so that the theme colors are visible.

A command that shows this control in a dialog box when the command is executed would be implemented as follows:

[Export(typeof(ICommand))]
[DisplayName("Show A Simple Dialog")]
public class ShowDialogCommand : ICommand
{
     private SimpleDialog dialog = null;
     public void Execute(object parameter)
     {
          // Instantiate a new dialog if one does not already exist
          dialog = dialog ?? new SimpleDialog();
 
          // Display the dialog
          MapApplication.Current.ShowWindow("Simple Dialog", dialog);
     }    
 
     public bool CanExecute(object parameter)
     {
          // Return true so that the command is always enabled
          return true;
     }
 
     public event EventHandler CanExecuteChanged;
}

In a Map Web Part that has the default theme, this dialog box appears as follows:

Making commands and behaviors configurable

The extensibility API included with ArcGIS for SharePoint also provides the ability to make your commands and behaviors configurable. If a command or behavior is configurable, designers editing the Map Web Part will be allowed to configure the component. To expose configuration on a command or behavior, all you need to do is implement the ESRI.ArcGIS.Client.Extensibility.ISupportsConfiguration interface. This interface requires you to implement the following methods:

• Configure—Invoked when a designer clicks the Configure button for the command or behavior. Your configuration logic should be initiated here. Usually this involves displaying a dialog box to get input from the designer.
• SaveConfiguration—Invoked when Map Web Part is saved. The string you return from this method persists and is passed back to the command or behavior when the web part is loaded.
• LoadConfiguration—Invoked when the Map Web Part initializes. The last string you returned from SaveConfiguration is passed to this method.

For an example of a configurable command, suppose you have implemented a simple user control that contains the default code-behind and a text box. The XAML for this control may appear as follows:

<UserControl x:Class="MyExtension.ConfigurationDialog"
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
     mc:Ignorable="d"
     d:DesignHeight="300" d:DesignWidth="400">
     <Grid x:Name="LayoutRoot" Background="Transparent">
          <TextBox x:Name="InputTextBox" Width="200" />
     </Grid>
</UserControl>

This control could be used in a simple configurable command as follows:

[Export(typeof(ICommand))]
[DisplayName("Simple Configurable Command")]
public class ConfigurableCommand : ICommand, ISupportsConfiguration
{
     private string configurationString = "";
     private ConfigurationDialog dialog = null;
     public void Execute(object parameter)
     {
          // Show the saved configuration string
          MessageBox.Show(configurationString);
     }     
 
     public bool CanExecute(object parameter)
     {
          // Return true so that the command is always enabled
          return true;
     }
 
     public void Configure()
     {
          // Instantiate a new dialog if one does not already exist
          dialog = dialog ?? new ConfigurationDialog();
 
          // Initialize the dialog's textbox
          dialog.InputTextBox.Text = configurationString;
 
          // Display the dialog
          MapApplication.Current.ShowWindow("Configuration Dialog", dialog);
     }    
 
     public void LoadConfiguration(string configData)
     {
          // Initialize the configuration string with the saved data as long as the saved data is not null
          configurationString = configData ?? configurationString;
     }
 
     public string SaveConfiguration()
     {
          // Return the configuration string so that it is saved
          return configurationString;
     }
 
     public event EventHandler CanExecuteChanged;
}

With this command added to the Map Web Part, designers editing the web part would be able to initiate configuration by selecting Configure from the command's menu:

Note that the Configure option is only available while editing the web part. When the web part is not in edit mode, a configurable command is represented on the ribbon as a button. Clicking the button invokes the command's Execute method.

Clicking Configure will invoke the command's Configure method. With the implementation shown above, this displays the following dialog box:

When the web part is saved, the text in the text box persists as a string. When the web part loads, this string is passed to the LoadConfiguration method and used to initialize the configurationString variable. Executing the command—by selecting Execute from the command's menu in edit mode or by clicking the command's button in run mode—will display a message box that shows the saved configuration string: