# Bookmarks

PDF bookmarks work in a similar way to a table of contents -- they provide an easy and convenient way to navigate a PDF document. Design script bookmarks let you jump to sections, views, or sheets in a PDF document, jump to a web link, play sound clips, and extract information from the design file and display it with a bookmark.

You can create the following types of bookmarks:

Bookmarks are displayed in the Adobe Reader/Acrobat Navigation pane and are typically organized in a hierarchical tree-view structure. Some bookmark entries may not have actions associated with them, such as Text Description Bookmarks. Instead, they are used as placeholders to provide structure to the bookmark hierarchy.

The software always creates a parent bookmark for each sheet in the document. This bookmark entry is set to the sheet_name keyword value. When you click on the parent bookmark entry, the viewer displays the entire sheet fitted to the screen. All other bookmarks for this sheet are created as children of the parent bookmark.

Using the Design Script keywords, you can create bookmarks that allow the Reader/Acrobat viewer to zoom to a particular section or view in a document. The section or view is defined by the accumulated rectangular range box of the element(s) that matches the design script criteria. The zoom or scale factor is defined by the element(s) accumulated range box and can be further adjusted by using the zoom_percentage keyword.

You can use the action_spec keyword to specify the position of the bookmark in the bookmark hierarchy. For more information, see Bookmark Templates.

## Area of Interest Bookmark

You can create a bookmark to a particular section or view in a document. This section or view is defined by the accumulated rectangular range box of the element(s) that matches the design script criteria.

The following table displays the required/default values for the action keywords when you create an Area of Interest Bookmark.

Keyword Value Default Value
action_item BOOKMARK Required
action_name A unique string used to identify the bookmark entry in the Bookmarks tab. Required
action_type AREA_OF_INTEREST Default value - optional
action_spec Specifies the position of the bookmark in the bookmark hierarchy. If a value is not specified, the bookmark will be placed at the very bottom of the current hierarchy. Optional
action_range Element_range | cell_range Element_range
action_instance Single_instance | Multiple_instance Single_instance

The following design script creates a bookmark to a digital signature field.

Example:

```! Create a area of interest Digital Signature Field
! The accumulated range box of the elements below
! defines the Digital Signature field in the PDF document.
if ((level eq 1) and (color eq 9) and (type eq 3)) then
action_item = field
action_name = "Chief Engineer"
action_type = digsig_field
action_spec = "John Doe, P.E."

! Create a bookmark to the Digital Signature Field
action_item = bookmark
action_name = "Signature Field"	!Bookmark name (unique)
action_type = AREA_OF_INTEREST
action_spec = "./digsig/engineer"
endif```

The design script example above creates the following bookmark.

## Document Bookmark

Document bookmarks let you jump to a particular sheet in a PDF document. The software always creates a parent bookmark for each sheet in a document, but you can create additional bookmarks that jump to other sheets in the document.

When creating a Document bookmark, the action_name keyword specifies the sheet name that the bookmark jumps to when you click the bookmark. Each sheet may be defined with a name using the sheet_name keyword.

The following table displays the required/default values for the action keywords when you create a Document Bookmark.

Keyword Value Default Value
action_item BOOKMARK Required
action_name sheet_name (Defines the destination sheet name.) Required
action_type DOCUMENT Required
action_spec Specifies the position of the bookmark in the bookmark hierarchy. Required
action_range Not applicable Not applicable
action_instance Not applicable Not applicable

Example:

```! Create a bookmark that jumps to a particular
! sheet in a document for all sheet names beginning with plan*.
if (sheet_name eq "plan*") then
action_item = BOOKMARK
action_type = DOCUMENT
action_spec = "./Related pages/Details drawing"
endif```

The design script example above creates the following bookmark.

Web Link bookmarks let you jump to a Web page. For all bookmark types, you should set the action_item keyword to bookmark. The action_name keyword specifies the URL address and not the name of the bookmark entry. The bookmark entry name is derived from the last entry in the action_spec keyword. For example, if you specify action_spec="/Related Web Links/TDOT Standards Specifications" for the action_spec keyword, TDOT Standards Specifications is the bookmark entry name.

The action_spec keyword also specifies the position of the bookmark in the bookmark hierarchy. The action_type must be set to web_url.

The following table displays the required/default values for the action keywords when you create a Web Link Bookmark.

Keyword Value Default Value
action_item BOOKMARK Required
action_name URL HTTP specification (The value defines the URL of the web link. ) Required
action_type WEB_URL Required
action_spec Specifies the position of the bookmark in the bookmark hierarchy and defines the bookmark entry name. Required
action_range Not applicable Not applicable
action_instance Not applicable Not applicable

Example:

```! Create a bookmark that jumps to a Web page.
!
action_item = BOOKMARK
action_name = "http://www.dot.state.tx.us/cst/2003SpecProj/index.htm"
action_type = WEB_URL
action_spec = "./Related Web Links/TDOT Standards Specifications"```

The design script example above creates the following Web Link bookmark.

## Sound Clip Bookmark

Sound Clip bookmarks let you play audio sound clips in a PDF document. For all bookmark types, you should set the action_item keyword to bookmark.

The action_name keyword identifies the file specification of the sound file and not the name of the bookmark entry. The bookmark entry name is derived from the last entry in the action_spec keyword.

When you create a Sound Clip bookmark, you must set the action_type keyword to play_sound. The action_spec keyword specifies the position of the bookmark in the bookmark hierarchy.

Note: If a file specification begins with a number, you need to precede the number with forward slashes or two backslashes. For example, action_name = "c:\my audio files\\2004.wav" or action_name = "c:/my audio files/2004.wav".

The following table displays the required/default values for the action keywords when you create a Sound Clip Bookmark.

Keyword Value Default Value
action_item BOOKMARK Required
action_name Specifies the file specification of the sound file. Required
action_type PLAY_SOUND Required
action_spec Specifies the position of the bookmark in the bookmark hierarchy and defines the bookmark entry name. Required
action_range Not applicable Not applicable
action_instance Not applicable Not applicable

Example:

```! Create a bookmark that plays a sound clip.
!
action_item = BOOKMARK
action_name = "c:\my audio files\instructions.wav"
action_type = PLAY_SOUND
action_spec = "./Audio Instructions/Listen Before Installing!"```

## Text Description Bookmarks

Text Description bookmarks let you display text information. Using a Text Description bookmark, you can extract text information from a DGN file and display it with a bookmark, you can hardcode a text string inside a bookmark, or you can display any of the Characters keywords in a bookmark.

For all bookmark types, you should set the action_item keyword to bookmark. For Text Description bookmarks, action_name specifies both the string to identify this bookmark item and the value for the bookmark entry. The action_type keyword must be set to text_description.

The action_spec keyword specifies the position of the bookmark in the bookmark hierarchy.

The following table displays the required/default values for the action keywords when you create a Text Description Bookmark.

Keyword Value Default Value
action_item BOOKMARK Required
action_name Unique string to identify this particular bookmark item. This value is used as the new bookmark entry. Required
action_type TEXT_DESCRIPTION Default value—optional
action_spec Specifies the position of the bookmark in the bookmark hierarchy. If a value is not specified, the bookmark will be placed at the very bottom of the current hierarchy. Optional
action_range Not applicable Not applicable
action_instance Not applicable Not applicable

The following design script creates a bookmark that displays the sheet description from the drawing's title block.

Example 1:

```! Display the sheet description from the title block.
!
if (type .eq. text) then
if ((level_name .eq. "titleblock") and (weight .eq. 1)) then
! Create a text description bookmark
action_item = BOOKMARK
action_name = characters	!Text string from the drawing.
action_type = text_description
action_spec = "./Description"
endif
endif```

The design script example above creates the following Text Description bookmark.

The following design script creates a bookmark that displays the number of sheets in a document.

Example 2:

```! Use a bookmark to display the number of sheets
! in the document.
if (sheet_name eq "index of sheets") then
! Create a text description bookmark
action_item = BOOKMARK
action_name = total_pages
action_type = TEXT_DESCRIPTION
action_spec = "./Number of pages in document"
endif```

## Bookmark Templates

You can create an XML file that defines the layout of the bookmark hierarchy. The bookmark_template keyword specifies the file specification for the XML file. For example, bookmark_template = "d:\anystreet\book.xml".

Note: If a file specification begins with a number, you will need to precede the number with forward slashes or two backslashes. For example, bookmark_template = "d:\anystreet\\2004book.xml" or bookmark_template = "d:/anystreet/2004book.xml".

You can use the action_spec keyword to specify the position of the bookmark in the bookmark hierarchy. The action_spec value is composed of bookmark hierarchical branch names, where each branch name is separated by the forward slash character (/). The period character (.) denotes the root or top of the bookmark hierarchy ("./branch name 1/branch name 2/branch name 3").

If a bookmark template is used, each branch name in the action_spec value (starting from left to right) is compared to each bookmark template title until it encounters a branch name that is not defined in the template. In this situation, it will create a new branch using the specified branch name. Using the example bookmark template (described below), the following bookmarks are created when action_spec is set to ./StormWater/Pit15/MyBookmark.

```Storm Water System
1.2 Kerb Opening (PIT15)
MyBookmark```

Empty hierarchy branches are removed from the bookmark tree. However, you can keep these empty hierarchical branches if you set the XML attribute KeepAlways value to 1 in the XML element. This feature enables you to define bookmark structures that you can populate or edit at a later time using Acrobat Professional.

Example bookmark template file:

```<?xml version="1.0" encoding="UTF-8"  ?>
<bookmark-tree>
<bookmark title="WasteWater">Waste Water Supply</bookmark>
<bookmark title="WaterSupply">Water Supply System</bookmark>
<bookmark title="StormWater">Storm Water System
<bookmark title="PIT12">1.2 Kerb Opening (PIT12)</bookmark>
<bookmark title="PIT13">1.2 Kerb Opening (PIT13)</bookmark>
<bookmark title="PIT14">1.2 Kerb Opening (PIT14)</bookmark>
<bookmark title="PIT15">1.2 Kerb Opening (PIT15)</bookmark>
<bookmark title="PIT16">1.2 Kerb Opening (PIT16)</bookmark>
<bookmark title="PIT17">1.2 Kerb Opening (PIT17)</bookmark>
<bookmark title="PIT18">1.2 Kerb Opening (PIT18)</bookmark>
<bookmark title="PIT19">1.2 Kerb Opening (PIT19)</bookmark>
<bookmark title="PIT20" KeepAlways="1">1.2 Kerb Opening (PIT20)</bookmark>
</bookmark>
<bookmark title="digsig">Digital Signatures
<bookmark title="engineer">Project Engineer</bookmark>
<bookmark title="project">Project Manager</bookmark>
</bookmark>
</bookmark-tree>```
Note: The XML file uses UTF-8 encoding to handle extended characters.