Skip To Content

Overview

ArcGIS Maps for SharePoint allows you to add functionality to your application by adding tools, behaviors, and custom picture marker sets using extension packs.

Extension packs

Central to extensibility in ArcGIS Maps for SharePoint is the extension pack. An extension pack is a container for all tools, behaviors, and custom picture marker sets that can be loaded into the application.

An extension pack typically consists of a uniquely named folder that contains the required manifest file; the JavaScript files that describe the tool, behavior, or picture marker sets; and any required supporting files. Extension packs can contain more than one tool, behavior, or picture marker set.

The manifest is provided to ArcGIS Maps for SharePoint in the form of a JSON file and must be named manifest.json.txt.

Although it is not required, it is generally a best practice to package tools, behaviors, and picture marker sets in separate, dedicated folders, as shown below.

Extension packs

ArcGIS Maps for SharePoint can have multiple extension packs. The functionality available in ArcGIS Maps for SharePoint on application startup is defined in the tool_collections.json.txt and behaviors.json.txt files in the ArcGIS Maps for SharePoint Administration Configuration Files list. Site collection administrators can edit these files to modify the default tools and behaviors.

Extension pack names

Dojo keeps an internal list of namespaces and package names, and does not allow different packages to have the same name. If your extension pack contains a module that you reference using its absolute path (for example, acme/stuff/SomeModule), you must name the extension pack in the same manner as you would name the package in a regular Dojo application (for example, acme).

For example, the following references a module in a package named acme; in this case, the extension pack must be named acme:

define([
	"dojo/_base/declare",
	"esriMaps/extensions/tools/_Tool",
	"acme/stuff/SomeModule"],
	function(declare, _Tool, SomeModule) {
   return declare(_Tool, {
      constructor: function() {
         var myModule = new SomeModule();
      } 
   });
});

If your code does not reference a module in the package using its absolute path, as shown in the code sample below, you can name your extension pack using any name that does not include special characters or spaces. You must ensure, however, that your tool or template code does not reference a specific module.

define([
	"dojo/_base/declare",
	"esriMaps/extensions/tools/_Tool",
	"./stuff/SomeModule"],
	function(declare, _Tool, SomeModule) {
   return declare(_Tool, {
      constructor: function() {
         var myModule = new SomeModule();
      } 
   });
});

Manifest file

The manifest included in an extension pack contains descriptions of the extensions contained within that extension pack; these include tools, behaviors, and picture marker sets. 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 may also optionally include other initial properties. The path defined in the location property is relative to the location of the manifest file.

Important: Be sure to save your manifest file with UTF-8 encoding. If you receive the following error message when adding an extension pack, Failed to load Extension pack manifest file. Verify that the JSON content is valid, check to see if the file was saved with Byte Order Marker (BOM). If it was, remove the BOM using an advanced text editor such as Notepad++ and save the file.

Use UTF-8 encoding for manifest file

The basic structure of an extension pack manifest, in JSON format, is as follows:

Caution:

Do not include comments in your JSON file.

{
    "name" : "myExtensions",
    "description" : "",
    "tools" : [],
    "behaviors" : [],
    "pictureMarkerSets": []
}
Where:
  • name— Required. Name of the extension pack. Must be the same as the name of the extension pack folder, for example, myExtensions. See Extension pack names.
  • description—Optional. Brief description of the extension pack.
  • tools—Array of JSON objects, each describing an individual tool. See Tool description.
  • behaviors—Array of JSON objects, each describing an individual behavior. See Behavior description.
  • pictureMarkerSets—Array of JSON objects, each describing a custom picture marker set. See Picture Marker Set description.

Tool description

{
    "name" : "myTool",
    "location" : "./tools/MyTool.js",
    "label" : "My Tool",
    "description" : "This does something",
    "iconClass" : "logToolIcon",
    "showTooltip" : true,
    "tooltip" : "tooltip message"
}
Where:
  • name—Tool name; must be unique within the manifest.
  • location—Path to the tool's JS file, relative to manifest.json.txt.
  • label—Label displayed in the application's user interface.
  • description—Optional. Brief description of the tool.
  • iconClass—Optional. Name of the CSS class used to style the tool's icon.
  • showTooltip—Optional. If true, displays the tooltip defined in the tooltip property.
  • tooltip—Optional. Defines the content of the tooltip.

The name, location, and label properties are required; other properties are optional.

Behavior description

{
    "name" : "myBehavior",
    "location" : "./behaviors/MyBehavior.js",
    "label" : "My Behavior"
}
Where:
  • name—Behavior name; must be unique within the manifest.
  • location—Path to the behavior's JS file, relative to manifest.json.txt.
  • label—Label displayed in the application's user interface.

Picture marker set description

{
    "label" : "My Picture Marker Set",
    "description" : "This is my Picture Marker Set",
    "location" : "./symbols/MyPictureMarkerSet.json.txt"
}
Where:
  • label—Label displayed in the application's user interface.
  • description—Optional. Brief description of the picture marker set.
  • location—Path of the picture marker set's JSON.txt file, relative to manifest.json.txt.

Example

The following code shows an example of a populated manifest.json.txt file. It contains the definition for two tools, one behavior, and one picture marker set.

{
    "name" : "myExtensions",
    "description" : "",
    "tools" : [
        {
            "name" : "MyTool",
            "location" : "./tools/MyTool.js",
            "label": "My Tool"
        },
        {
            "name" : "MyOtherTool",
            "location" : "./tools/MyOtherTool.js",
            "label" : "My Other Tool"
        }
    ],

    "behaviors" : [
        {
            "name" : "MyBehavior",
            "location" : "./behaviors/MyBehavior.js",
            "label" : "My Behavior"
        }
    ],

    "pictureMarkerSets": [
        {
            "label": "My Picture Marker Set",  
	           "description" : "My Picture Marker Set",
            "location": "./symbols/MyPictureMarkerSet.json.txt"
        }
    ]
}

Tool collections

Tool collections are named sets of tools; they determine which tools are displayed and made available to the user. The ArcGIS Maps for SharePoint layout is composed of tool containers, a series of widgets that can be configured to display different sets of tools and behaviors. Each tool container is responsible for displaying a specific set of named tool collections.

The following images show the default tool collections:

Tool collections

  1. main—Menu items that appear on the main menu, for example, Analysis Tools and Share.
  2. rightBanner—Tools on the application's main right banner tools toolbar, for example, Configure and Help.
  3. mapTools—Tools on the Map tools toolbar, for example, Select, Route, and Basemap.
  4. layerPrimary—Tools on the application's Map contents toolbar, for example, Move up, Move down, Duplicate layer, Zoom to, Layer details, and Remove layer.
  5. addData—Tools on the Add data drop-down menu, for example, from SharePoint and from ArcGIS.
  6. layerSecondary—Tools or widgets related to a selected layer, for example, Style, Pop-ups, Cluster points, and Filter layer.
  7. select—Tools available from the Select Tools drop-down menu, for example, View selected records, Find nearby, and Route selected features.
  8. popup—Tools on the pop-up toolbar, for example, Zoom to, Open Item, and Infographics.

The tool collection has a configuration file in JSON format, named tool_collections.json.txt. The file lists the IDs of tool collections, relative to the layout's tool containers. Each tool collection can contain individual tools, or tools assembled into tool groups. For each tool, the file lists the unique ID and name of the tool, along with the path of the extension pack that contains it.

For example:

Caution:

Comments are included here for documentation purposes only. Do not include comments in your JSON files.

[{                                      
  "id": "main",                               // ToolCollection ID
  "tools": [{                                 // first ToolGroup in ToolCollection
    "label": "First Menu",                    // label of ToolGroup
    "tools": [{                               // tools included in this ToolGroup
        "name": "Menu1",                      // tool name
        "extensionPackName": "myExtensions"   // extension pack that contains the tool
    }, {
        "name": "Menu2",                      // tool name
        "extensionPackName": "myExtensions"   // extension pack that contains the tool
    }]                                  
  }, {                                        // second ToolGroup in ToolCollection
    "label": "Second Menu",                   // label of ToolGroup
    "tools": [{                               // tools included in this ToolGroup
        "name": "Tool1",                      // name of tool
        "extensionPackName": "myExtensions"   // extension pack that contains the tool
    }, {
        "name": "Tool2",
        "extensionPackName": "myExtensions"
    }, {
        "name": "Tool3",
        "extensionPackName": "myExtensions"
    }, {
        "name": "Tool4",
        "extensionPackName": "myExtensions"
    }] 
  }]
}]

Note:

When you define a tool, the tool's name attribute must match the tool name specified in the tool's extension pack manifest (manifest.json.txt).

To see the default Tool Collection definition, see tool_collection.json.txt listed under Configuration Files in the ArcGIS Maps for SharePoint Site settings. This file determines the tools that are loaded when creating a new ArcGIS Maps Web Part. You can modify the tool definitions to overwrite properties defined in the extension pack's manifest or other properties. For example, to change a tool's label at run time, edit the value in the tool collection.

For example:

. . .
"name" : "MyTool",
"extensionPackName" : "MyExtensions",
"label" : "Display a different label",
"newProperty" : "new value"

Behavior definition

You can define one or more behaviors in ArcGIS Maps for SharePoint. Behaviors are defined in a configuration file in JSON format, named behaviors.json.txt. This file is in the Configuration Files list of the ArcGIS Maps for SharePoint Site settings. You can modify the behavior definitions to overwrite properties defined in the extension pack's manifest or other properties.

For example:

[{
    "name": "MyCustomBehavior",
    "extensionPackName": "MyExtensions"
}]