useful functions are available at ESRI's ArcScripts. I also bookmark scripts that look especially useful for archaeology or anthropology. However, sometimes figuring out how to add this new script into ArcMap is so frustrating that it can feel like one is about to have their head chopped off...To help minimize these frustrations, this post details information on how to add user created scripts to ArcMap.
Scripts are written in a number of different languages. Each of these requires slightly different methods to connect the script to ArcMap. It can be confusing to figure out how the scripts need to be integrated into the program so that the scripts can be used. Descriptions are given for adding functions in the following formats:
Arc Macro Language (AML)
Visual Basic (VB, VBA, VBScript)
1. Visual Basic:
1a. VBScript & VBA Macros: these are VBA (Visual Basic for Applications) or VBScript files that can be added to an .mxd via the Tools / Macros / Visual Basic Editor menu and/or the Tools / Customize menu. Once these macros (scripts) have been added to a project they can be executed (run) from the Tools / Macros menu or from an associated icon on a toolbar, performing a series of steps. VB macros do not require administrator permissions to install, as they are contained in the .mxd, not the operating system files. Macros also have the advantage of being editable (i.e., the user can alter the code to customize the functionality). Installation of these files does require the user to understand and be able to navigate the basic VBA environment for customizing ArcGIS.
The basic steps for adding a VB script to ArcMap are:
1. From the Tools menu, choose Macros / Macros
2. Enter a name for your new macro
3. Choose whether to store the macro in the current .mxd (Project) or in the Normal.mxt or in All Standard Projects - if stored in the Normal.mxt it will be available anytime ArcMap is opened (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the Project option)
4. Click Create
5. This should open the VB editor, with a Project - Module window open
6. Using Copy and Paste, copy the code from the macro you wish to use into the Project - Module window - you will probably need to delete the default text (Sub... End Sub) first
7. In the upper right hand dialog box of the Project - Module window, choose the name of the pasted module from the drop down list
8. Save the Project (File / Save Project menu or the Save icon)
9. Close the Visual Basic editor
10. To run (execute) the macro:
· Once again choose Macros / Macros from the Tools menu
· Choose the name of the macro you wish to run
· Click Run
11. Macros can also be edited by choosing Edit
12. To associate and run the macro with an icon:
· From the Tools menu, choose Customize
· Click the Commands tab
13. In the Categories (left side) dialog box, scroll down and select Macros
14. If your macro is saved in the .mxd, choose the .mxd name in the Save in box
15. Drag and drop the desired macro from the Commands (right side) dialog box to any toolbar
16. The icon can now be used similar to any other icon on the toolbar
17. The macro can be edited by right-clicking on the icon and choosing View Source
The basic steps for adding a VBScript as as UITool in ArcMap are:
1. From the Tools menu, choose Customize
2. Click the Commands tab
3. In the Categories (left side) dialog box, scroll down and select UIControls
4. In the Save in dialog box (at bottom of Customize window) choose the current .mxd or the Normal.mxt (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the current .mxd option)
5. Click New UIControl
6. In the New UIControl dialog box, choose UIToolControl for a Tool (or UIButtonControl for a button, etc)
7. Click Create
8. Close the Customize window
9. To add the code for the Tool, right click on the tool icon and choose View Source
10. Copy and Paste the code for the UITool into the Visual Basic Editor window (This Document) - you will probably need to delete the default text (Sub... End Sub) first
11. Save the Project (File / Save Project menu or the Save icon)
12. Close the Visual Basic editor
13. Click on the tool icon to use it as usual (tools typically enable the mouse to perform new functionality...)
14. Note that a UITool can be removed from (or relocated on) a toolbar by choosing Customize from the Tools menu and then dragging the undesired icon off of the toolbar (to anywhere else) or to a new location on a toolbar. This can only be done while the Customize window is open.
(see: Customizing the user interface / Creating, editing and running macros)
1b. VB dll files: Dynamic Link Library (dll) files are typically more complex then a simple macro. These .dll's are VB (Visual Basic) files that need to be 'loaded' (installed) via the Tools / Customize dialog box using the Add from file... button. Once the .dll has been installed, it will be available from the Command window of the Customize dialog box, and can be added to any toolbar in ArcMap or ArcCatalog. Having added the tool to a toolbar, the user can use the tool by clicking the icon as with any other tool on a toolbar. Because the .dll file needs to be installed in the Program Files of the operating system, these files typically require administrator privileges to install. Once installed, any login can add the tool to a toolbar and/or use the tool. These files are compiled and cannot be edited/customized (though the authors may choose to include the uncompiled code used to create the .dll as well). They are, however, relatively easy to install (simpler than an VBA macro).
The basic steps for installing a .dll file in ArcMap are:
1. From the Tools menu, choose Customize
2. Click the Add from file button at the bottom of the Customize window
3. Browse to and select the .dll to be installed
4. Click OK in the Added Objects dialog box
5. Click the Commands tab in the Customize window
6. In the Categories (left side) dialog box, scroll down and select the Category header for the installed .dll (you will need to read the help or readme file that came with the .dll to determine what/where this is)
7. In the Save in box, choose where you wish to store this tool icon (the choices being the current .mxd or in the Normal.mxt (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the current .mxd option)
8. Drag and drop the desired command (tool) from the Commands (right side) dialog box to any toolbar
9. Close the Customize window
10. The icon can now be used similar to any other icon on the toolbar
1c. VB executables: These are files (sometimes including a .dll file) that need to be installed via an executable (.exe) file. As with loading .dll file from the customize dialog box, this process requires an administrator login. Installation happens outside of ArcGIS (typically, the .exe file is run from Windows Explorer). Once installed, the tool (or tools or menu) is available to all users of ArcGIS. As with .dll files, these files cannot be edited.
The basic steps for adding an .exe file are:
1. Recommended: Close ArcMap and/or ArcCatalog if they are open
2. Double click on the .exe file
3. Follow installation instructions provided with the file or via the file installer dialogs
1d. ArcGIS Extensions: Technically a subcategory of VB executables, ArcGIS Extensions are typically a more complex, packaged collection of tools and/or menus. Unlike the majority of the scripts listed above (that are usually refinements and rearrangements of existing tools), Extensions typically add functionality to the basic ArcGIS toolset (e.g. the 3D Analyst extension). Extensions are installed via an .exe and as such require an administrator login. Installation happens outside of ArcGIS (typically, the .exe file is run from Windows Explorer). Once installed, the extension is available to all users of ArcGIS. These files cannot be edited.
2. Python Scripts:
Python files are text files (typically with a .py extension). These can be edited using any text editor. The preferred application for editing is PythonWin (a stand alone editor for Python scripts that comes with ArcGIS), which provides syntax and coding help. The ModelBuilder can also be used to create a Python script by simply exporting a model to a script. Once exported, the script can be further refined (adding functionality not available in the ModelBuilder).
Python scripts for ArcGIS make use of the tools in ArcToolbox via a connection to ArcToolbox (the "Geoprocessor Object"). Once this relationship has been established, any tool in the Toolbox can be used in a script. These scripts can be executed from with ArcMap or ArcCatalog (Adding a script to an existing Toolbox) or from outside of ArcGIS (simply by running the script from Windows Explorer). If added to a Toolbox, the script typically will require the assigning of parameters (variable to receive input from the user at runtime). These parameters need to be properly assigned in terms of their order and data type, so that the script will run properly. Once added to a toolbox, the toolbox (a .tbx file) can be shared with other users, providing another means of sharing Python scripts (and saving the end user from the need to set parameters, etc.).
The adding and running of Python scripts does not require administrator privileges. These scripts can be edited as need be by the user.
The basic steps for adding a Python script to ArcToolbox are:
1. Optionally create a new toolbox for the script: right click on ArcToolbox and choose New Toolbox
2. Right-click on the desired toolbox in which to store the Python script and choose Add / Script
3. Enter a Name and Label for the script (these can be the same and do not need to correspond to the name of the script itself - the Label will be what is listed in the toolbox)
4. Optionally check the box to Store relative path names
5. Click Next
6. Browse to the location of the Python script to use
7. Click Next
8. Enter the Display Name(s) and Data Type(s) for any parameters required by the script (you may need to read the help or readme file that came with the script or the script itself to determine what parameters are required and what data types they use as well as any of the Parameter Properties that need to be set).
9. Click Finish
10. Double click on the Script in the toolbox to run it (which should open a dialog box prompting the user for the parameters)
11. Right-click the script in the toolbox and choose Properties to modify any of the above settings.
Users wishing to learn more about writing Python scripts for ArcGIS are encouraged to refer to the following sources:
(see: Writing GeoProcessing Scripts)
3. ModelBuilder Models:
ArcGIS ModelBuilder provides a graphical interface for creating geoprocessing models. These models can use any of the tools available in ArcToolbox, and can be created in either ArcMap or ArcCatalog. Once created, these models can be shared (via a toolbox) with other users. As with a Python script, models can have parameters (variables) that users enter when running the model, allowing users to use a generic model with their own data. Models (in a toolbox) can be run by simply clicking on them (as with any other tool in ArcToolbox) or by opening the model in edit mode (right-click and choose Edit which opens the model in the ModelBuilder window). From the ModelBuilder window, models can be run via the Run icon or by choosing Run from the Model menu.
Models can incorporate other models or Python scripts (just as they can use any other tool in ArcToolbox). They can also be exported to either a graphic or a Python script. Exporting to a graphic provides a quick method of documenting and sharing the model. Exporting to a Python script enables further customization of the geoprocessing (e.g. the addition of conditional loops, etc. that cannot be included in a model).
Users wishing to learn more about models and using the ArcGIS ModelBuilder are encouraged to refer to the following sources:
(see: GeoProcessing in the ArcGIS environment / Introducing model building)
(see: GeoProcessing in the ArcGIS environment / Using the ModelBuilder window)
Geoprocessing in ArcGIS.pdf (Ch. 8 & 9)
ESRI Virtual Campus (Geoprocessing with ArcGIS 9)