Changing tool dialog appearance


You can change the appearance of a tool dialog, using your company logo as the background image, for example, or adding text. You cannot customize the parameter controls, only the background image and text. The following illustration shows a customized tool dialog with a graphic of the model to be run.


A custom stylesheet applied to a dialog box

Customizing a tool's dialog requires mucking about with XML stylesheets, which control the properties of items inside tool dialog boxes. As you'd expect, there are system default stylesheets residing on your computer that are used by all tools. You'll copy these stylesheets to another folder and modify them. The location of these default stylesheets is ArcGIS\ArcToolbox\Stylesheets.

The main stylesheet you'll want to customize is MdDlgContent.xsl.

The customization procedure is as follows:

  1. Copy the <ArcGIS>\ArcToolbox\Stylesheets\MdDlgContent.xsl to another folder (<ArcGIS> is the ArcGIS install directory). You can rename it if you like, as long as you keep the .xsl extension.
  2. Modify the stylesheet using a text editor such as Notepad. Do not use a word processor such as Word, unless you understand how to save the file as raw text. Instructions on how to modify the stylesheet can be found below.
  3. In ArcToolbox, right-click a tool and click Properties. On the General tab, enter the location of your new stylesheet in the Stylesheet control. If the location is empty, the default stylesheet will be used.

You can also customize MdDlgHelp.xsl, which is the stylesheet applied to the Help panel of the tool's dialog box, by using the same procedure as above. If you have a modified Help stylesheet, you enter both the Content stylesheet and the Help stylesheet in the tool's property dialog, separating them with a semicolon. The path to the Content stylesheet must come first. If you only want to apply a customized Help stylesheet, simply place a semicolon in place of the Content stylesheet and the default MdDlgContent.xsl will be used. When just the Content stylesheet is modified, a semicolon is not necessary to make sure the default MdDlgHelp.xsl is applied.

Changing background image

There are three alternative ways of changing the background image. These alternatives vary only in the location on disk of where the image will be found. Each method involves locating and modifying the following line, which should be near the top of the stylesheet;

<xsl:variable name="BackgroundImage">url(<xsl:value-of
 select="MdElementDialogInfo/CommonPath"/>/esri.gif)</xsl:variable>

Alternative 1: Replace the bold text with the name of the new background image, as follows:

<xsl:variable name="BackgroundImage">url(<xsl:value-of
 select="MdElementDialogInfo/CommonPath"/>/esri.gif)</xsl:variable>

Change to:

<xsl:variable name="BackgroundImage">url(kelso.gif)</xsl:variable>

The tool dialog will now look for the file

C:\Documents and Settings\<user name>\Application Data\ESRI\ArcToolbox\Dlg\kelso.gif. 

Alternative 2: Change just the name of the image file. For example:

<xsl:variable name="BackgroundImage">url(<xsl:value-of
 select="MdElementDialogInfo/CommonPath"/>/esri.gif)</xsl:variable>

Change to:

<xsl:variable name="BackgroundImage">url(<xsl:value-of
 select="MdElementDialogInfo/CommonPath"/>/kelso.gif)</xsl:variable>

the tool dialog will now look for the file:

<ArcGIS>\ArcToolbox\Common\kelso.gif

where <ArcGIS> is the ArcGIS install directory.

Alternative 3: Replace the bold text with the absolute pathname to the image file. For example:

<xsl:variable name="BackgroundImage">url(<xsl:value-of
 select="MdElementDialogInfo/CommonPath"/>/esri.gif)</xsl:variable>

Change to:

<xsl:variable name="BackgroundImage">url(E:\Demos\Thiessens\Doc\kelso.gif)</xsl:variable>

The tool dialog will now look for the file:

E:\Demos\Thiessens\Doc\kelso.gif

Advanced stylesheet modifications

Stylesheets are composed of display instructions, or XSL operations, which operate on XML statements. The result of these XSL operations is a set of HTML files that, when displayed, becomes the user interface when a tool is executed via its dialog box.

You can alter the default stylesheets to change the look of your tools. Two examples are provided below to show you the types of changes you can make.

The first example focuses on how the default colors, background, and layout can be changed and shows how to add hyperlinks.

The second example illustrates the creation of an expandable panel for optional parameters.

In both examples new stylesheets are created that import the ESRI default stylesheets to fetch those display characteristics that are not overwritten in the custom stylesheets. The alternative is to copy the default stylesheets locally to the location of the toolbox and modify the local copy to override the default stylesheet applied to the tool's dialog box with your local copy by setting the path.

When the dialog of a tool is opened, the XML statements representing the user interface elements for the tool are created and written to disk. The XML statements do not indicate how these elements should be displayed; they only define which elements are involved. The XML file is called MdElements.xml and is created or re-created in the Documents and Settings\<user name>\Application Data\ESRI\ArcToolbox\Dlg folder each time the dialog box of a tool is opened. Unless the tool has been linked to custom stylesheets, the default stylesheets are applied to the MdElements.xml file. The following default stylesheets are located in your ArcGIS\ArcToolbox\Stylesheets folder on the drive where you installed ArcGIS:

These XSL stylesheets transform the XML statements (MdElements.xml) into the set of HTML files that represent the tool's dialog box. Three HTML files are created in Documents and Settings\<user name>\Application Data\ESRI\ArcToolbox\Dlg folder:

These HTML files are then displayed as the tool's dialog box.

Example 1

In this example, the font, background image, and background color are altered for the dialog box of the Standard Distance tool and a hyperlink is added. This tool is located inside the Spatial Statistics system toolbox.

Without customization, the dialog box for the Standard Distance tool resembles the following graphic:


Standard Distance tool

Using a custom stylesheet, the look of the dialog box can be altered dramatically, as shown below.


The Standard Distance tool with customization

The above example uses a custom XSL file named SSContent.xsl.

View SSContent.xsl

SSContent.xsl imports the settings of MdDlgContent.xsl. There is no need for a path to the default MdDlgContent.xsl file in this example, as both SSContent.xsl and MdDlgContent.xsl are placed in the ArcGIS\ArcToolbox\Stylesheets location. The background image (mygraphic.jpg) can be placed in the DLG folder (\Documents and Settings\<user name>\Application Data\ESRI\ArcToolbox\Dlg. Because this is the default location where the HTML files are generated from the XSL files, the graphic will be found in this location if just the name of the graphic is entered, for example, url(mygraphic.jpeg). Alternatively, a hard-coded path can be entered to the location of the graphic, such as url(C:/mydata/mygraphic.jpeg).

A third alternative is displayed in the code below. The graphic can be placed in a location that is relative to the location of the Common folder (\ArcGIS\ArcToolbox\Common), such as in the Stylesheets folder.

Variables correspond to the background color, font type, size, color, image, and image position. Display instructions are also appended to the main MdElementDialogInfo template. Once all other XML elements have been processed, this extra XSL code adds the text, "This tool is described in The ESRI Guide to GIS Analysis, Volume 2", and a Web link to ESRI Press.

Example 2

You can change the stylesheet applied to a dialog box so that parameters are grouped into expandable sections within the tool's dialog box.

In the example below, the tool has multiple optional parameters. You can apply a custom stylesheet to group all the optional parameters into an expandable section.


A tool's optional paramters

System tools are read only, but you can still modify them by first copying them to your own toolbox.

The stylesheet is called Expand.xsl, and can be used on any tool to group all its optional parameters into an expandable section. The stylesheet uses logic that examines the parameter label for the text "(optional)".

View Expand.xsl

This stylesheet only overrides certain settings, and the default stylesheet (MdDlgContent.xsl) is imported to take care of the rest. The default stylesheet resides in your ArcGIS\ArcToolbox\Stylesheets folder on the drive where you installed ArcGIS. If your custom stylesheet is placed in the same location, you can type the name of the default stylesheet to import, with a .xsl extension within your custom stylesheet. Otherwise, you'll have to use a full pathname.

By opening the tool's dialog box you'll see the applied stylesheet. Notice how the optional parameters are collected into the Optional Parameters expandable section.


Applied stylesheet

Clicking the arrow to the left of Optional Parameters expands the section to allow values for optional parameters to be supplied.


Optional parameters

If you examine the code for Expand.xsl, you'll notice that it overwrites the PropertyGroup template of MdDlgContent.xsl and uses <xsl:choose> statements to process optional and required parameters differently.