Skip To Content

Create a tool

As a developer, you may want to add functionality to ArcGIS Maps for SharePoint by creating custom tools. Tools are executed through user interaction. They can be added as buttons, tools, or menu items to tool containers in the map.

Built-in tools

ArcGIS Maps for SharePoint comes with a variety of built-in tools that provide the basic functionality for the application. These include menus, buttons on toolbars, and tools selected through a menu.

The following image shows the built-in tools included with ArcGIS Maps for SharePoint. These are defined in tool_collection.json.txt, listed under Configuration Files in the ArcGIS Maps for SharePoint Site settings.

Built-in tools

Built-in layer tools

Create a new tool

The following example illustrates the implementation of a tool that displays an alert message when clicked. For more information, see the Tool class documentation in the API reference section.

define([
	"dojo/_base/declare",
	"esriMaps/extensions/tools/_Tool"
	], function (declare, _Tool) {

return declare([_Tool], {
	message: "Welcome!",
	label: "My Tool",
	description: "This is my custom tool",
	execute:function(){     // Function called when tool is clicked in the app
		alert(this.message);
	},
	...
});

Tools that show widgets

Some tools need to show widgets as part of their functionality. When implementing a tool that shows a widget, it is recommended that you implement the following logic to check for the existence of the widget.

Additionally, when uploading extensions with widgets with templates (.html files) from a URL, there is the potential for a cross-domain error if the extension pack location is on a different domain than the SharePoint server. To resolve this, there are two options:

  • Embed the HTML content into the widget's JavaScript file. This makes for a longer file but resolves the issue.
  • Use the Dojo build process to bundle multiple resources into a single resource.

Here are the solutions:

  • The tool.execute method is called for the first time.
  • The tool creates an instance of the widget and stores a reference to it on the tool.

    For example:

    this._myWidget = new MyWidget({
        layer:this.selectedLayer
        });

  • The tool shows the widget by calling the following:
    layout.showWidget(this._myWidget)
  • The tool creates a listener for an event to destroy the widget and delete the reference to the widget.

    For example:

    widget.on('ok', function(){
        widget.destroy();
        tool._myWidget = null;
        }
    );

  • Check to see if the reference to the widget still exists; if it does, it means the user didn't close the tool.

    If the reference still exists, set the properties on the existing widget (this._myWidget.set('layer', this.selectedLayer)) to update the state of the widget and call layout.showWidget(this._myWidget) again. The layout should bring the widget forward if it was hidden by another widget.

Set a tool's icon

Some tools display an icon, while others only display text. To set the icon for a tool, you must first create an icon, and then create a style sheet and assign the style rule to the tool.

  • Create an icon that measures 24x24 pixels to best fit into the layout. Use an existing icon as a guideline for colors and positioning.
  • Create a CSS style sheet with a class rule that contains the icon as a background image.

    For example:

    .myToolIcon {
            background-image:url(./umbrella.png);
        }

  • Assign the class rule to the iconClass property of the tool, either in the tool module or in the tool's manifest.

    To load the class rule, you must inject the CSS style sheet into the page. You can use the xstyle package for this purpose.

    Your tool module would then resemble the following:

    define([
        "dojo/_base/declare",
        "esriMaps/extensions/tools/_Tool",
        "xstyle!./stylesheet.css"
        ], function(declare, _Tool) {
        return declare([_Tool], { 
            message:"My tool",
            isDisabled:false,
     
            execute:function() {
                console.log(this.message);
                }
        });
    });

    If you added the iconClass to the tool's manifest, the code would resemble the following:

    {
        "tools": [{
            "name": "MyTool",
            "location": "./tools/MyTool.js",
            "label": "This is my tool",
            "iconClass": "myToolIcon"
        }]
    }

Add a tool to ArcGIS Maps for SharePoint

Tools, behaviors, and picture marker sets are packaged in collections named extension packs, which consist of the code files for each extension, any supporting files, and a manifest file that describes the extensions contained within that extension pack. These descriptions, written in JSON format, outline the properties of each extension; for example, a tool's description must include name, location, and label properties, but it may also include other optional properties.

See Add extensions for more information.