Using Hyperlinks

Hyperlinks allow you to access documents or web pages related to features. These hyperlinks can be accessed for each feature using the Hyperlink tool on the Tools toolbar. This topic describes how to set and use hyperlink properties for a map layer.

Hyperlinks have to be defined before you use the Hyperlink tool, and they can be one of three types:

• Document—When you click a feature with the Hyperlink tool, a document or file is opened using its appropriate application (such as Microsoft Excel).
• URL—When you click a feature with the Hyperlink tool, a web page is launched in your web browser.
• Script—When you click a feature with the Hyperlink tool, a feature value is sent to a script. This option enables the use of customized behavior.

You can define a hyperlink for the features in a layer either by using field-based hyperlinks or defining a dynamic hyperlink using the Identify tool.

Note:

An alternative, and often more flexible, tool is available that uses HTML pop-ups. Clicking features reports additional information and attributes using HTML and web methods.

Defining field-based hyperlink properties

1. Right-click the layer for which you want to set hyperlink properties and choose Properties.
2. Select the Display tab on the Layer Properties dialog box.
3. Check Support Hyperlinks using field.

   

   Note:

   The hyperlink field has to be set up before you can specify hyperlinks in this dialog box. For example, if you want particular web pages to be launched whenever a feature is clicked with the Hyperlink tool, you would first add a text field to the attribute table of this layer to contain the URLs associated with each feature. Then in this dialog box, you would check the hyperlink option, choose the field from the drop-down list of fields, and choose the URL radio button option.

   The values of the field that you choose to provide hyperlinks can include the full path to the target document or the full URL of the target web page. Alternatively, the value may just contain the name of the target document or web page, and you can use the Hyperlink Base property to specify the path or URL where the target can be found.

   You can omit the http:// part of the URL. If you want to use a different protocol than http, you must include the protocol at the beginning of the URL.

4. Select the field name you wish to use for your hyperlink and the link type—Document, URL, or Script. If you choose to use a script, use the Edit button to write your script using JScript or VBScript. Click OK.

   

   Note:

   This dialog box lets you build a script that will launch a hyperlink. The script should be coded using the rules of the scripting language selected in the Parser drop-down list. The script can include any valid statements supported by the selected scripting language.

   Fields are enclosed in square brackets [ ], irrespective of the data type of the layer's data source. The hyperlink script is written as a function, which can contain programming logic and multiple lines of code.

   The default functions utilize the ShellExecute function, which is part of the MSDN library.

   • Microsoft ShellExecute Function Reference
   • Microsoft VBScript Language Reference
   • Microsoft JScript Language Reference
   • Python Language Reference

   These links point at web pages created, owned, and maintained by Microsoft Corporation and Python Software Foundation. We cannot guarantee the availability of these pages and are not responsible for the content found on them.

5. Click OK or Apply on the Layer Properties dialog box.

Defining dynamic hyperlinks through Identify results

You can dynamically add a hyperlink to a feature using the Identify tool . With dynamic hyperlinks, you do not use an attribute field to supply the hyperlink targets. The hyperlink target you specify is associated with the identified feature. This association is stored with your layer. They are also stored with your layer if you save the layer to a file.

1. Click the Identify tool on the Tools toolbar.
2. Click the feature for which you want to define a hyperlink.
3. Right-click the feature in the Identify window and click Add Hyperlink.
4. Specify the desired hyperlink target.

Note:

The Hyperlink Base setting has no effect on dynamic hyperlinks.

You can specify any number of dynamic hyperlinks for any feature. All the dynamic hyperlinks defined for a feature are listed in the Hyperlinks pull-right list in the identify results context menu (steps 1–3 above). Also available from this menu is Manage Hyperlinks. Here, you can add and remove dynamic hyperlinks for this feature. This list does not include field-based hyperlinks, and the commands available have no effect on field-based hyperlinks.

Caution:

After deleting features from a shapefile, you may find that dynamic hyperlinks are attached to different features. This occurs because ArcMap uses the feature ID (FID) field to associate dynamic hyperlinks with features, but the FIDs of shapefiles must be recalculated when features are deleted. To ensure hyperlinks are always associated with the proper features, only use dynamic hyperlinks with geodatabase features classes (geodatabase features always have unique ID values). Field-based hyperlinks can be used with shapefiles without this limitation.

Using hyperlinks

1. On the Tools toolbar, click the Hyperlink tool . This transforms your mouse pointer into a lightning bolt.

   Note:

   Any visible features in the map that have hyperlinks defined are drawn in blue, the default color, or outlined in blue in the case of polygons. When you hover the pointer over a feature for which a hyperlink exists, the mouse pointer turns into a black lightning bolt with a flash, and you see a pop-up tip with the name of the target.

2. Click a desired feature or location in your data frame to access hyperlink information.

   

3. This will bring up the hyperlink information, such as an HTML web page. If several hyperlinks are specified for a feature, ArcMap will pop up a list of the hyperlinks when the feature is clicked with the Hyperlink tool.
4. If you have hyperlinks turned on for multiple layers, clicking a location in your data frame provides a Hyperlinks dialog box to choose a feature from one of the layers. The layer name is listed in parentheses.

   

Changing the hyperlink color for features

You can use ArcMap settings to set the color for displaying hyperlink features using the following steps:

1. Click Customize > ArcMap Options.
2. Click the General tab.
3. Check When the Hyperlink tool is selected, highlight features containing clickable content.
4. Click the color drop-down menu to specify a different color for the highlights.

   

Managing hyperlink paths

As part of a map's properties, you can specify a hyperlink base, which is the base path, or URL, used for field-based hyperlinks to documents or URLs. For example, if the hyperlink base is set to D:\Data, then the values in the field or fields used as hyperlinks to documents don't have to contain D:\Data. They can just contain the name of the file. Using this property makes it easier to manage hyperlinks because if the location of the targets change, you can simply edit this one setting instead of having to edit each value of the field providing the hyperlink targets.

The Hyperlink Base property is specified on the Map Document Properties dialog box. Click File > Map Document Properties to open. There is one Hyperlink Base property for the map document. This setting has no effect if you specify that the target values are to be sent to a macro. Also, this setting has no effect on dynamic hyperlinks.

You can override this default so that no slash is automatically added. You can find this setting by launching the Advanced ArcMap Settings utility (<install drive>:\Program Files\ArcGIS\Desktop10.2.1\Utilities) and looking in the Miscellaneous tab. Overriding the default makes it easier to work with long paths and URLs.

For example, if you want to use the hyperlink base setting with long URLs such as this one—http://www.example.com/index.cfm?parameter=1234—you have to specify http://www.example.com as the base and store everything that comes after that—index.cfm?parameter=1234—in the hyperlink field. But, by overriding the default, you can specify most of the URL as the base— http://www.example.com/index.cfm?parameter=—and just store the last part of the URL, 1234, in the hyperlink field.

If you override the default, ArcMap will still retain the slash if the hyperlink base specified in Map Document Properties ends in a slash character. So, if you override the default, you can still add a slash manually to the hyperlink base. The setting to override the default only applies to your machine and is not stored as a property in the map document you are working with.

Making hyperlinks with relative paths

Sometimes, you may want to give a map that contains hyperlinks to someone who does not have access to your network resources. Just as you can save the map with relative paths to the data, you can also specify hyperlinks that refer to a location relative to the map.

To specify a path to a document in the same folder, type the document's name. For the example below, you would type directions.bmp (that is, do not include a \ or drive letter prefix).

To specify a path through a folder immediately below the map's location in the file system, start the path with the folder name (again, no \ or drive letter prefix). For the example below, you would type Graphics\directions.bmp.

Using parameters to control how a program opens a hyperlinked document

Hyperlinks to documents can contain parameters that define how the program opens the document. For example, parameters can tell Adobe Reader to open a PDF to a specific page, allowing map features to hyperlink to different pages in the same document. Since each software package (such as Microsoft Word, Microsoft Excel, Adobe Reader, and so on) has unique commands, consult the documentation for the software package used to open the document for the parameters and syntax available to it.

Many times, these parameters will be provided for use in a command line. For example, to open a .PDF document to page 5, the command line might look like the following:

• C:\Program Files\Adobe\Reader 8.0\Reader\AcroRd32.exe /A Page=5=OpenActions c:\temp\PopulationData.pdf

where

• C:\Program Files\Adobe\Reader 8.0\Reader\AcroRd32.exe is the location of the software; /A Page=5=OpenActions is the open parameter; and c:\temp\PopulationData.pdf is the location of the file.

ArcGIS does not read these parameters like a command line. Instead, it uses a special delimiter, a ? (question mark), to separate the file path from the parameter. The hyperlink to the same document and page in ArcGIS would look like this:

• c:\temp\PopulationData.pdf ?/A Page=5=OpenActions

The ? serves as the delimiter between the path and the parameter.

Advanced hyperlink functionality

Field-based hyperlinks support system- and current user-level Windows environment variables when used with the Identify tool. Environment variables must be set on the computer prior to utilizing them for hyperlinks. To use environment variables within ArcGIS, you will need to qualify the variable with a dollar sign, not percentage signs. For example, use $VARTEST instead of %VARTEST%.

You can create a dispatch object within your script code to call functions from a custom library. This allows you to access ArcObjects through your hyperlink script via the dispatch object. In addition, you can pass IFeature and/or IFeatureLayer down to the dispatch object so that you launch the hyperlink for the appropriate feature.

An example of a hyperlink script that creates a dispatch object

access ArcObjects through your hyperlink script via the dispatch object

Function OpenLink ( {IFEATURE}, {IFEATURELAYER} )
  Dim hlauncher
  Set hlauncher = CreateObject("Hyperlink_Lib.Launcher")
  hlauncher.Launch {IFEATURE}, {IFEATURELAYER}
End Function

This example will call the function Launch from a Hyperlink_Lib library that you have created.