Keywords for Active Renditions
Using Design Scripts you can create active renditions (content-rich PDF documents) that can contain Bookmarks, Internal Document Links, Web URL Links, Attachments, Digital Signature Fields, and Multimedia. This is accomplished using the action keywords. The order in which the action keywords occur in the design script is extremely important.
Action Keyword | Order |
---|---|
action_item | 1st |
action_name | 2nd |
action_instance | 3rd (when specified) |
You can also use the property publishing keywords to publish object metadata to PDF documents, known as property publishing. Property publishing is the process of publishing object metadata that is associated with a graphical entity in a PDF document. With Acrobat 7.0 or later, you can view the metadata information associated with a graphical entity using Acrobat's Object Data Tool.
The following action keywords include a description of the keyword function, the types of elements the keyword affects (if applicable), the valid data type(s) (if applicable), and an example of how to use the keyword.
action_item
Specifies the type of action item you want to create (bookmark, link, attachment, digital signature field, or multimedia), and is a required field when defining an active rendition. This keyword must occur before any of the other action keywords.
The following constants are valid for the action_item keyword:
- Field - Specifies that you want to create a digital signature field. A digital signature field is a location where user input is collected.
- Bookmark - Specifies that you want to create a bookmark. A bookmark is a single line item in the Table of contents. Bookmarks allow for quick navigation to a point of interest on a sheet, or they can also perform actions such as playing a sound or opening a URL. Another keyword of interest when using a bookmark may be bookmark_template in the Global Keywords section.
- Link - Specifies that you want to create a link. A link is a rectangular region on a sheet that has navigation action associated with it, like a Web URL or an Inter-Document link.
- Marker - Specifies that you want to create a marker. A marker denotes an area of interest on a sheet that marks a destination for navigation. A marker is identified by a unique name. The software automatically prepends the sheet_name to the marker name. The fully qualified marker name is sheet_name.marker_name. Other keywords of interest when using a marker may be zoom_percentage in the Global Keywords section.
- Attachment - Specifies that you want to create a file, sound, or movie attachment.
- Media - Specifies that you want to create a multimedia movie or sound clip.
Syntax:
ACTION_ITEM = <LINK | BOOKMARK | MARKER | MEDIA | FIELD | ATTACHMENT>
action_type
Specifies the type of action you want to associate with the action_item assignment, and is a required field when defining an active rendition.
The following constants are valid for the action_type keyword:
- AREA_OF_INTEREST - Specifies that you want the action type to be an area of interest. Used in an Area of Interest Bookmark to define 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.
- DESTINATION - Specifies that you want the action type to be a destination. Used when you are creating a marker as shown in the code snippet below. The name of the current sheet (sheet_name) is prepended to the action_name to associate it with the sheet. For example, if action_name="Air Handler" and the name of the sheet is Plumbing Schematics the resulting unique name for the destination would be Plumbing Schematics.Air Handler.
If((level_name eq "one") and (type eq shape)) then action_item = marker action_name = "Air Handler" action_type = destination endif
- DIGSIG_FIELD - Specifies that you want the action type to be a digital signature field. Used in Digital Signature Fields.
- DOCUMENT - Specifies that you want the action type to be a document. Used when defining Document Bookmarks and Internal Document Links.
- FILE_ATTACHMENT - Specifies that you want the action type to be a file attachment. Used in File Attachments to attach and embed files inside a PDF document.
- MOVIE_ATTACHMENT - Specifies that you want the action type to be a movie clip. Used in Movie Attachments to embed a movie in a PDF document.
- PLAY_MEDIA - Specifies that you want the action type to be a multimedia movie or sound clip. Used in Multimedia.
- PLAY_SOUND - Specifies that you want the action type to be a sound clip. Used in Sound Clip Bookmarks.
- SOUND_ATTACHMENT - Specifies that you want the action type to be a sound attachment. Used in Sound Attachments to embed sound inside a PDF document.
- TEXT_DESCRIPTION - Specifies that you want the action type to be text description. Used in Text Description Bookmarks to display text information.
- WEB_URL - Specifies that you want the action type to be a Web URL. Used with Web Link Bookmarks and Web URL Links.
Syntax
ACTION_TYPE = <WEB_URL | DESTINATION | DOCUMENT | PLAY_SOUND | PLAY_MEDIA | DIGSIG_FIELD | AREA_OF_INTEREST | FILE_ATTACHMENT |SOUND_ATTACHMENT | MOVIE_ATTACHMENT | TEXT_DESCRIPTION>
action_name/action_spec
Action_name and action_spec values are not preset constants. Rather, they are unique values that correspond to the action_item and action_type being defined.
Action_name is typically the internal, unique name used to identify the object being defined by action_item. The exception is when you are identifying a Web Link bookmark or a Sound Clip bookmark. For Web Link bookmarks, the action_name keyword identifies the URL. For sound clip bookmarks, the action_name identifies the file specification of the sound file. Action_name is a required field when defining an action_item.
Action_spec specifies the position of the bookmark in the bookmark hierarchy, the file specification for media or attachment items, the string that is displayed when the user hovers over the digital signature field in Adobe Acrobat, and the explicit name of the marker (i.e. sheet_name.marker_name) for a link. This is a required field when defining an action_item, except for marker items.
Syntax:
action_name = string action_spec = string
The following table provides a list of acceptable values for each corresponding action_type.
ACTION_TYPE | ACTION_NAME | ACTION_SPEC |
---|---|---|
AREA_OF_INTEREST | Unique string used to identify a bookmark item. | Specifies the position of the bookmark in the bookmark hierarchy. |
DESTINATION | Unique name for a marker. | Not applicable |
DIGSIG_FIELD | Unique string used to identify a digital signature. | String that is displayed when the user hovers over the digital signature field in Acrobat. |
DOCUMENT | Unique string used to identify a sheet name in a Document Bookmark. | Specifies the position of the bookmark in the bookmark hierarchy. For links, it specifies the explicit name of the marker (i.e. sheet_name.marker_name). |
FILE_ATTACHMENT | Unique name for a file attachment. | File specification. |
MOVIE_ATTACHMENT | Unique name for a movie attachment. | Movie file specification. |
PLAY_MEDIA | Unique name for a movie or sound clip. | Movie or sound file specification. |
PLAY_SOUND | File specification of a sound file. | Specifies the position of the bookmark in the bookmark hierarchy. |
SOUND_ATTACHMENT | Unique name for a sound attachment. | Sound file specification. |
TEXT_DESCRIPTION | Unique string to identify a bookmark item. | Specifies the position of the bookmark in the bookmark hierarchy. |
WEB_URL | Unique name used as an identifier for a link. URL HTTP specification for a bookmark. | Specifies the position of the bookmark in the bookmark hierarchy and defines the bookmark entry name. For Web URL links, it specifies the URL address. |
action_range
Specifies whether the range when determining the rectangular area in creating a link, field, marker, attachment, media, or an area of interest bookmark is based on the range of the current element or the range of the cell associated with the current element. The default value is element_range.
The following constants are valid for the action_range keyword:
- ELEMENT_RANGE - Specifies that the rectangular area in creating an active rendition is based on the range of the current element.
- CELL_RANGE - Specifies that the rectangular area in creating an active rendition is based on the cell associated with the current element.
Syntax
ACTION_RANGE = <ELEMENT_RANGE | CELL_RANGE>
action_instance
Specifies whether the rectangular area (for a link or area of interest bookmark) is calculated using the current cell or element range or calculated based on the sum of all matching cell or element ranges.
The following constants are valid for the action_instance keyword:
- SINGLE_INSTANCE - Specifies that the rectangular area for a link or area of interest bookmark is calculated based on the sum of all matching cell or element ranges.
- MULTIPLE_INSTANCE - Specifies that the rectangular area for a link or area of interest bookmark is calculated using the current cell or element range.
Syntax
ACTION_INSTANCE = <SINGLE_INSTANCE | MULTIPLE_INSTANCE>
Example 1:
! Create a bookmark to a sheet in a document. ! if (first_time eq true) then if (sheet_name .ne. "details") then action_item = bookmark action_name = "details" action_type = document action_spec = "./Drawing Sheet" endif endif
Example 2:
! In the Table of Contents sheet, link ! all text in the index to the corresponding ! sheet name in the document. if (sheet_name eq "Table of Contents") then if ((type eq text) and (color eq 3)) then ! Define the rectangular region around the current ! text string that points/links to the corresponding ! sheet in the document by the same name. action_item = link action_name = characters action_type = document action_spec = characters endif endif
Example 3:
! Create a bookmark to the equipment ! items and associate a maintenance video with ! the appropriate equipment. ! Identify the type of equipment to be addressed if ((type eq 2) and (cellname eq "Sprinkler Head")) then ! Identify the tag set tag_set="equipment information" tag_name="serial number" ! Define a Bookmark under the sheetname for this page ! that will navigate to the piece of equipment. Use the ! sheet_name and TAG_CHAR to form the action item name. action_item = bookmark action_name = sheet_name + "." + TAG_CHAR action_type = AREA_OF_INTEREST action_spec = "." + sheet_name + "./" + TAG_CHAR ! Define a multimedia sound clip that describes ! how to install the equipment. action_item = media action_name = "Maintenance Instructions" action_type = PLAY_MEDIA action_spec = "c:\equipment\videos\sprinkler.wav" endif
Global Keywords
The following keywords can be used as assignment statements, except for the first_time keyword.
- first_time - This comparison keyword lets you execute a segment of a design script one time. This keyword (flag) is TRUE the first time the design script is called, and then the value is set to FALSE. The value cannot be reset. A good use for this keyword is when you specify a bookmark template. See the example at the end of this section. Note: When the system processes a design script, each element in the design file is processed in a top-down order until each element is processed. If the first element in the design file executes the first_time code snippet, the remaining elements will be processed but they will skip the first_time code snippet.
- sheet_name - Specifies the name of the current sheet and associated bookmark for the current page being plotted. The default value is the name of the print definition.
Syntax
sheet_name = string
- ignore_engineering_links - Specifies that if an engineering link is encountered do not include it as a link in the active rendition. The default value is FALSE.
Syntax
ignore_engineering_links = <TRUE|FALSE>
- bookmark_template - An XML file that defines the layout of the bookmark hierarchy.
Syntax
bookmark_template = file specification to an XML file
- zoom_percentage - Lets you to control how the surrounding region is displayed when you click on an area of interest bookmark or a link to a marker. If you specify a zoom percentage of 100, the rectangular region is fitted into the Acrobat viewer's current window area. A value of 150 designates an area 50 percent larger than the exact boundary of the marker or rectangular region. The default value for zoom percentage is 120. The order in which the zoom_percentage keyword appears in the design script is very important. The zoom_percentage keyword needs to follow the action_item and action_name keywords.
Syntax
zoom_percentage = integer (where 100 is 100%)
Example:
if (first_time eq true) then ! Load the bookmark template bookmark_template = "d:\anystreet\mybookmarktemplate.xml" if (cellname eq "steps") then action_item = BOOKMARK action_name = "Step Detail" zoom_percentage = 150 action_type = AREA_OF_INTEREST action_spec = "./details/steps" endif
Property Publishing Keywords
The following keywords are used to publish object metadata to PDF. To view the object metadata in a PDF document, click the Model Tree in Adobe Acrobat or Reader.
- propertycontainer_name - Lets you specify a container name for the active property. When assigned a string value, subsequent property_maptoelement actions cause the active property to be placed under the given container name. Containers may not be nested. By default, the design-script-defined properties are placed under a top-level sheet name node in the model tree.
Syntax:
propertycontainer_name = "string"
- property_name - Specifies that you are creating a property object name. All property object names must be unique.
Syntax:
property_name = "string"
- property_setvalues - Specifies that you are creating attributes and values for a property object. This keyword can also be used to modify or update an attribute value.
Syntax:
property_setvalues = "attribute = value" property_setvalues = "attribute1 = value1;attribute2 = value2"
- property_maptoelement - Associates the current graphical element with the active property object.
Syntax:
property_maptoelement = true property_maptoelement = false
- property_setqueryvalues - Specifies that you want to query a property object's attribute value.
Syntax:
property_setqueryvalues = "string"
- property_getvalue - Specifies that you want to get a property object's attribute value.
Syntax:
property_getvalue ="string"
- property_deleteattributes - Specifies that you want to delete a property object's attribute for the active property object.
Syntax:
property_deleteattributes = "string" property_deleteattributes = "string1;string2"
Example 1:
!Specify property name, set property values, !delete property value, and map to element. propertycontainer_name = "Ward 1" if ((type eq shape) and (level_name eq 'ward 1')) then property_name = "Ward 1" property_setvalues = "City=Dacula" property_setvalues = "Ward Name=Otonabee;Ward Zone=1" property_setvalues = "Mayor=J. Doe" Property_SetValues = "Useless=Stuff" !Delete property value Property_DeleteAttributes = "Useless" property_maptoelement = true endif ! Set up Ward 2 propertycontainer_name = "Ward 2" if ((type eq shape) and (level_name eq 'ward 2')) then property_name = "Ward 2" property_setvalues = "City=Snellville" property_setvalues = "Ward Name=Wantonabee;Ward Zone=2" property_setvalues = "Mayor=J. Smith" property_maptoelement = true endif
The following image shows how the propertycontainer_name keyword values (Ward 1 and Ward 2) display inside the Adobe Reader/Acrobat Model Tree. Also, note that the Useless property (property_setvalues = "Useless=Stuff") does not display in the Model Tree since it was deleted (Property_DeleteAttributes = "Useless").
Example 2:
! Query an object's attribute value. if (type == line) then property_name = "Ward 1" property_setqueryvalues = "City" if (property_getvalue=="Dacula") color = "red" endif endif