The dialog boxes of tools (system tools or custom tools) are similar in style because they have a default Extensible Stylesheet Language (XSL) stylesheet applied to them—they have the same background image, font, colors, and layout. 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.
How are default stylesheets applied?
You can alter the default stylesheets so you can change the look of your tools, depending on personal preference. Two examples are provided to show you the types of changes you can make. Note that the XSL files used in the examples can be copied from the online Help system if desired.
The first example focuses on how the default colors, background, and layout can be changed and explains 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 for 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, modify your local copy, then override the default stylesheet applied to the tool's dialog box with your local copy by setting the path.
Learn more about overriding the default stylesheet applied to a tool's dialog box
When the dialog box of a tool is opened, the XML statements representing the user interface elements for the tool are created. 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 or re-created in the Documents and Settings\<user name>\Application Data\ESRI\ArcToolbox\Dlg folder:
These HTML files are then displayed as the tool's dialog box.
Customizing the default stylesheets
You can override the default MdDlgContent.xsl and MdDlgHelp.xsl stylesheets that are applied to any tool's dialog box, provided the tool does not reside inside a read-only toolbox.
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.
Using a custom stylesheet, the look of the dialog box can be altered dramatically, as the following graphic shows.
The default stylesheet that is applied to a tool's dialog box can be changed on the General tab of the tool's Properties dialog box. Right-click the tool and click Properties to open the Properties dialog box.
In this example, the name of a custom XSL file called SSContent.xsl is entered in the Stylesheet text box on the General tab of the tool's properties dialog box. By simply typing the name of the custom stylesheet, the path to the location of the default stylesheets (ArcGIS\ArcToolbox\Stylesheets) is used. To follow this technique, place your custom stylesheet or stylesheets in this location.
The contents of SSContent.xsl are displayed in the example that follows. In this example, this file is used in place of MdDlgContent.xsl. It imports the settings of MdDlgContent.xsl if they are not changed in SSContent.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\username000\Application Data\ESRI\ArcToolbox\ Dlg or \WINNT\Profiles\username000\ Application Data\ESRI\ArcToolbox\Dlg [on Windows NT]). As 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.
Learn more about custom stylesheets (SSContent.xsl)
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.
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.
System tools are read only, but you can still modify them by first copying them to your own toolbox.
The modified code within a custom stylesheet (expand.xsl) that can be applied is displayed in the section that follows. 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.
Learn more about creating your own toolboxes
Learn more about copying a tool from one toolbox to another
In this example, the stylesheet expand.xsl is specified in the Stylesheet text box on the General tab of the tool’s Properties dialog box. Since there is no path, this file should be saved in the location \ArcGIS\ArcToolbox\Stylesheets.
Learn more about custom stylesheets (expand.xsl)
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.
Clicking the arrow to the left of Optional Parameters expands the section to allow values for optional parameters to be supplied.
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.
Options for customizing stylesheets
There are a number of options you can implement so others will see your stylesheet customizations when you distribute your tools, including the options that follow.
- Copy the default stylesheets—MdDlgContent.xsl, MdDlgHelp.xsl, or both—from your \ArcGIS\ArcToolbox\Stylesheets folder to another location on your local drive. This is usually the same location as the toolbox or the geodatabase if the toolbox is stored inside a geodatabase.
- Modify the stylesheets as desired, then use them in place of the default stylesheets by specifying the location to the files in the Stylesheet text box on the General tab of the tool's properties dialog box.
Learn more about specifying custom stylesheets in the Stylesheet text box
- Set relative paths on the General tab of the tool’s properties dialog box.
- Zip the folder containing the toolbox and the data, then send the ZIP file.
Learn more about archiving your work
- Type the name of your custom stylesheet or stylesheets in the Stylesheets text box on the General tab of the tool's Properties dialog box.
- Put your custom stylesheets in the same location on disk as the default stylesheets: \ArcGIS\ArcToolbox\Stylesheets.
- Instruct users of your tools to place your custom stylesheets in the Stylesheets folder on their machine. From then on, your stylesheets will always be applied when your tools are run.
- Type the name and the path to your custom stylesheet or stylesheets in the Stylesheets text box on the General tab of the tool's Properties dialog box.
- Set relative paths on the General tab of the tool's Properties dialog box.
- In your custom stylesheet files, hard code the location to import the default stylesheet from—for example, <xsl:import href = "C:\Program Files\ArcGIS\ArcToolbox\Stylesheets\ MdDlgContent.xsl" />. This path may have to be modified by receivers of your tool if they installed ArcGIS in a different location.