Best Practices: Getting Started

The ArcGIS for SharePoint Map Web Part includes an extensibility API that provides Viewer developers access to the map and selected layer, methods to show UI in dialogs, and the ability to store and load configuration data. To get started extending the Viewer, first determine whether you will create a tool or a behavior. Once you have decided on the type of add-in to create, see the section below on Working with the Map and Selected layer for detailed information on accessing the map from your add-in.

Commands and Behaviors

Commands provide a simple way to surface logic that should be initiated by the user. If it makes sense to have the functionality you are implementing initiated by having a user click a button on the toolbar, then you should encapsulate this functionality in a command. An identify tool is an example of a situation where you would provide a button on the toolbar for the user.

Map behaviors provide a simple way to surface functionality that should always be enabled. Map behaviors provide functionality without the need for user interaction. If you are developing functionality to add a capability or modification that should always be present, then this should be encapsulated as a map behavior. Map behaviors can be used, for instance, to constrain the map extent, show mouse coordinates on the cursor, or display an introductory dialog when the application loads.

For more information and examples, see Writing commands and Writing map behaviors.

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 via the MapApplication.Current property. To access the map object, use MapApplication.Current.Map in your add-in 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 tool is executed, and the logic in the CanExecute method is such that the tool will be enabled only if a GraphicsLayer is selected.

[Export(typeof(ICommand))]
[DisplayName("Show GraphicsLayer ID")]
[Category("My Tools")]
[Description("Shows the ID of the selected GraphicsLayer")]
[DefaultIcon("Path to icon, ex: "/Viewer.Addins;component/Images/Identify.png"")]
public class ShowGraphicsLayerIdCommand : ICommand
{
     public void Execute(object parameter)
     {
          // Show the selected layer's ID
 									MapApplication.Current.ShowWindow("Layer ID", new TextBlock()
            {
                Text = MapApplication.Current.SelectedLayer.ID,
                TextWrapping = TextWrapping.Wrap,
                Margin = new Thickness(30),
                MaxWidth = 480
            });
   
     }    
 
     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 in the Map Contents Panel. These differ from a layer IDs in that they are meant to be a intuitive name to identify a layer to end users of the Map Web Part, whereas IDs are meant to uniquely identify a layer in the map's layer collection from a programmatic perspective. The selected layer changed 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 a simple behavior that displays the selected layer's name in a message box when the selected layer changes:

[Export(typeof(Behavior<Map>))]
[DisplayName("Show Selected Layer Name Behavior")]
[Category("My Behaviors")]
[Description("Shows a message box with the selected layer name")]
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(object s, EventArgs args)
     {
          // Show a message box with the selected layer name
          string layerName = MapApplication.Current.SelectedLayer.GetValue(MapApplication.LayerNameProperty) as string;
          MapApplication.Current.ShowWindow("Layer Name", new TextBlock()
            {
                Text = layerName,
                TextWrapping = TextWrapping.Wrap,
                Margin = new Thickness(30),
                MaxWidth = 480
            });
     }
 
     protected override void OnDetaching()
     {
          // Remove the handler from the application's SelectedLayerChanged event
          MapApplication.Current.SelectedLayerChanged -= ShowSelectedLayerName;
     }
}