Essential Python add-in concepts
This document introduces concepts that are essential for understanding how add-ins are created with Python.
Python Add-In Wizard
To simplify the development of add-ins, it is recommended that you use Python Add-In Wizard to declare the type of customization. Python Add-In Wizard reduces development time and possible errors by creating the files and folders necessary for the add-in to work.
Download the Python Add-In Wizard.
The download is a compressed ZIP file (.zip) containing all the files necessary to support the wizard. To use the wizard, unzip the contents to a folder and locate the executable file named addin_assistant.exe in the bin folder; double-click this executable to launch the wizard. Examples of using Python Add-In Wizard are provided in the topics for creating an add-in.
Tip:Create a shortcut of the executable file on your desktop or quick launch toolbar.
File and folder structure
An add-in is a collection of files and folders conveniently packaged in a compressed file containing an .esriaddin extension to make them easily identifiable by users and ESRI ArcGIS Add-In Installation Utility. For example, if you double-click an add-in in Windows Explorer, on a website, or in an e-mail, the add-in installation utility automatically installs the add-in on your machine, deploying it to a well-known folder.
Add-ins have a config.xml file located at the root level of the add-in archive. This file describes the add-in and declares its customizations. It is created by Python Add-In Wizard when you click the Save button and includes all the information describing the add-in such as the ArcGIS product, captions, ToolTips, help information, images, and layout details.
Add-ins also have an Install folder. The main purpose of the Install folder is to hold the Python script (the active portion) of the add-in. For example, a button is declared in the configuration file, but its custom behavior is defined in its associated Python script.
You can create additional folders and files in the Install folder. This is useful in cases where you want to ship data as part of your add-in. This data can include items such as layer files, toolboxes, and .xml files. To access data located inside the installation location, you can take advantage of the __file__ built-in function. This example shows how to access a layer file in a data folder located within the installation folder:
eq_layer = os.path.join(os.path.dirname(__file__), r'data\earth_quakes.lyr')
Most of the add-in types declared have graphics associated with them. All graphics entered through the wizard will be referenced in the configuration file and copied to the Images folder at the root level of the archive.
The following graphic illustrates the file and folder structure of an add-in file (.esriaddin):
makeaddin.py
The makeaddin.py Python file is a utility script created by Python Add-In Wizard and is used to package the files and folders within the project folder into the compressed add-in file. Double-click this file to create the add-in file. Each time you make changes to the add-in, you must run this script to repackage the add-in file with the latest updates.
Well-known folder locations
Add-ins are automatically discovered when ArcGIS for Desktop is started in a per user/per desktop version well-known folder. For example:
- Vista/7: C:\Users\<username>\Documents\ArcGIS\AddIns\Desktop10.1
- XP: C:\Documents and Settings\<username>\My Documents\ArcGIS\AddIns\Desktop10.1
Add-ins are automatically added and removed using ESRI ArcGIS Add-In Installation Utility and the Add-In Manager dialog box. The Add-In Manager dialog box within ArcGIS for Desktop also allows you to add your own well-known folders, which can be network shares.
In addition, add-ins automatically unpack their Install folder's contents to a temporary folder. For example:
- Vista/7: C:\Users\<username>\AppData\Local\ESRI\Desktop10.1\AssemblyCache
- XP: C:\Documents and Settings\<username>\Local Settings\Application Data\ESRI\Desktop10.1\AssemblyCache
This data is automatically removed by the add-in framework once it detects the add-in is no longer installed on the system.