Creating a Python add-in application extension

Creating a Python add-in application extension

An application extension can be used in different ways to provide supplemental functionality to ArcGIS for Desktop.

• An application extension is often used to group an associated set of functions that perform similar tasks. Good examples of extensions in ArcMap are the ArcGIS 3D Analyst extension, Business Analyst, and so on.
• Application extensions are usually responsible for listening and responding to various events exposed by the host application. For example, anytime a layer is added or removed, an event is triggered and the extension responds by automatically saving the map document.
• Application extensions are used to coordinate activities between other components—such as buttons and tools—within a containing add-in. For example, an extension may not activate a set of tools on a toolbar unless a specific set of layers are added to the map.

Application extensions can be configured to load when needed or automatically when their associated application is started; extensions can also be configured to appear in the standard ArcGIS Extensions dialog box located under the Customize menu.

This topic guides you through the process of creating an application extension. Before beginning this workflow, make sure that you have created an ArcMap add-in project and specified the project settings. For more information, see Creating an add-in project. This workflow shows you how to create an extension for ArcMap; however, there are no differences in creating menus for any of the ArcGIS for Desktop applications. This topic examines the process of creating an extension that adds a base layer to ArcMap each time a document is opened or a new document is created. The Python class created by the Python Add-In Wizard is then examined in greater detail to explore the properties and methods that provide functionality to your extension.

Creating an add-in application extension consists of two steps:

1. Create the application extension.

   Once you have entered the required project settings, click on the Add-In Contents tab. To begin, right-click on EXTENSIONS and click New Extension.

   

   An extension has a number of properties for you to enter. The following is a list of all of the properties with an explanation for each. These properties are stored in the config.xml file for the project.

   Property	Description
   Name(required)	Represents the name of your application extension. On the screen capture below, this is the name that is used on the Extensions dialog box for desktop applications.
   Class Name(required)	The Python class representing your extension. The Python class is where you write your business logic for the extension. This class is important because it is called when the application extension is used in a desktop application. Use the Python naming convention when constructing your class. Python classes use cap-word notation. In this example, we create a class named AddBaseLayer.
   ID(required)	This is the unique name used to identify your extension. It is possible for you to create more than one extension for a given project and this ID is used to distinguish between the different application extensions. Ideally, you should replace the default ID with a more meaningful value. The ID should not contain any spaces. You may use underscores to connect words. You should not use Python keywords. Consult the Python documentation for reserved words. The add-in namespace will be prefixed to the ID. The namespace is stored in the config.xml file.
   Description(optional)	Describes the purpose of your application extension. For example, the 3D Analyst extension provides tools for surface modeling and 3D visualization. The description is displayed in the bottom portion of the Extensions dialog box.
   Loads Automatically(optional)	Allows you to load the application extension when a desktop application is opened. By default, this option is checked on. When this is checked, the enabled property in the Python script will be set to True.

   Once you have finished entering the properties, you can click the Save button at the bottom of the wizard. This will create all the necessary files and folders within your working folder.

2. Edit the Python script.

   The next step is to edit the Python script and update the Python class to include the functionality to add a base layer each time a map document is opened or created. It does this by listening and responding to the openDocument and newDocument events for ArcMap. To add the functionality to the custom extension, perform the following steps:

   1. Edit the Python script in the Install folder located in the working folder you created through the wizard.

      A class will exist with the same name as entered through the wizard. You should not rename this class as the class name is referenced in the config.xml. For details on each function within the extension class, see the Extension class topic.

   2. Update the newDocument and openDocument event functions as shown below.

      This code provides the functionality to add a base layer to the active data frame if it does not already exist.

      def newDocument(self):
      
          """
          Adds a base layer if it is not already added to the active data frame of the map.
          """
      
          # Provide a layer file and the layer name as it would appear in the Table of contents. 
          base_layer = r'C:\GISData\module5\World_Street_Map.lyr'
          base_layer_name = 'World Street Map'
          mxd = arcpy.mapping.MapDocument('current')
          active_view = mxd.activeView
          df = arcpy.mapping.ListDataFrames(mxd, active_view)[0]
          if arcpy.mapping.ListLayers(mxd, base_layer_name) == []:
              arcpy.mapping.AddLayer(df, arcpy.mapping.Layer(base_layer))
              arcpy.RefreshTOC()
          else:
              return   
      	
      def openDocument(self):
          """
          Adds a base layer if it is not already added to the active data frame of the map.
          """
      
          base_layer = r'C:\GISData\module5\World_Street_Map.lyr'
          base_layer_name = 'World Street Map'
          mxd = arcpy.mapping.MapDocument('current')
          active_view = mxd.activeView
          df = arcpy.mapping.ListDataFrames(mxd, active_view)[0]
          if arcpy.mapping.ListLayers(mxd, base_layer_name) == []:
              arcpy.mapping.AddLayer(df, arcpy.mapping.Layer(base_layer))
              arcpy.RefreshTOC()
          else:
              return
      

   3. Delete all functions not implemented from the script.

      You must delete all functions that are not implemented from the script. This ensures they are never called by the application.

   4. Save the script.
3. Test the application extension.

   Once the application extension is created and the script code is added, it is important to create the add-in file and test it before sharing it. For these steps, see Testing an add-in.

4. Deploy and share the application extension.

   For steps on deploying and sharing the add-in, see Sharing add-ins.

Feedback on this topic?