Hypertext commands

Add hypertext commands in FrameMaker, define active hyperlink area in FrameMaker.

A hypertext command in a FrameMaker document, defines an active area in a document. If a user clicks on the active area in a view-only FrameMaker document or an output such as PDF or HTML, the associated hypertext command is executed.

You can create a hypertext command in a document to provide inter-activity to the reader. See Add hypertext commands to documents.

You can use hypertext commands to perform tasks such as opening a web page, displaying an alert, go to a specific pages (first, last, page number) in the current document, open and close external applications. See Available hypertext commands.

You can then save your document as view-only, PDF or publish the document using the FrameMaker multi-channel publishing solution.

Note: Hypertext commands work differently in PDF and HTML output. See PDF and HTML: Hypertext command support.

You can use hypertext commands in images added to a FrameMaker to Create an image map that defines multiple clickable areas in a single image.

Add hypertext commands to documents

Add hypertext commands in FrameMaker, learn to define active area, define an image active area, Insert hypertext command marker in FrameMaker.

To add hypertext commands to a document, you need to first Define an active area in a document and then Associate a hypertext command with an active area.

Define an active area in a document

You can associate hypertext commands to text or images in a document. When a user clicks on the active area, the area is highlighted after which the command is executed.

Create a text active area in a document

You can define a word, phrase, paragraph, or multiple adjacent words as active areas. To identify a text active area, FrameMaker uses the character format of the text. This implies that the character format of the text active area must be different from that of the surrounding text. If the character format is the same as the surrounding text, the entire text in the paragraph is set as active.

Define an active area for a word or phrase

  1. Select the word or phrase.

    You need to change the character format of the selected word or phrase.

  2. In the Format menu, go to the Characters sub-menu.

  3. In the Characters sub-menu, you can choose from the list of default character formats available in the current document catalog.

    Alternatively, open the Character Designer catalog and apply a custom character format.

Note: The following character format changes cannot be used to define a text active area: pairkerning, spread, stretch, change bars, language, and case.
Tip: If you do not want the text in active area to display differently from the surrounding text, use a different character format that has the identical formats as the surrounding text. You can save the character format of the surrounding text with a different name and then apply that character format to the active area.

Define an active area for a paragraph

Ensure that the same character format is applied to the entire paragraph.

Define separate active areas for adjacent words or phrases

You can assign different hypertext commands to adjacent words or phrases in a paragraph by applying by different or the same character format to the words or phrases. However, you need to ensure that the character formats of the words or phrases are not the same as that of the surrounding paragraph text. After this you can associate a hypertext command with each of the adjacent words or phrases. For details, see Insert hypertext command marker.

Define an image active area

You can define an active area on an image in a document. When a user clicks the image, the associated hypertext command is executed.

  1. Draw a text frame to cover the image in the document.

    Make sure that the graphic is not set to have text run around it.

    To place a text frame over the image:

    1. Open the Graphics toolbar (View > Toolbars > Graphics Toolbar).

    2. Click Text Frame in the Graphics toolbar and draw the text frame to cover the image.

  2. Set the text frame fill and pen patterns to None.

    To set the text frame properties:

    1. Right-click the text frame and choose Object Properties.

      In the Anchored Frame Properties dialog:

    2. Go to the Stroke tab and uncheck the Pen Pattern option.

    3. Go to the Fill tab and uncheck the Pattern option.

  3. Ensure that the text frame is placed above the image.

    If you place the image after placing the text frame, choose Graphics > Bring To Front to place the text frame in front of the graphic.

Create an active area on multiple pages in a document

If you create an active area on the master page of a document, the area will be active on all pages of the document. For example, you can add text to the document header and create an active area in the text in the header.

Associate a hypertext command with an active area

After you Define an active area in a document, you need to associate a hypertext command to the area. When a reader clicks the active area in your document, the hypertext command is executed.

View-only FrameMaker documents support all FrameMaker hypertext commands, PDF and HTML outputs of hypertext documents, have limited support. For details, see PDF and HTML: Hypertext command support.

Insert hypertext command marker

  1. Place the insertion point in the active area.

    Word or phrase

    At the start of the word or phrase.

    Paragraph

    At the start of the paragraph.

    Multiple adjacent words or phrases

    At the start of each separate word of phase.

    Image

    In the enclosing text frame. See Define an image active area.

  2. Open the Hypertext dialog. Insert > Hypertext.

  3. Use the Hypertext dialog to:

    Element Tag

    If you are adding a hypertext command in a structured document, select the required hypertext element tag.

    Note: This will depend on the structured application that you are using to create your structured documents.
    Command

    Select the hypertext command to execute when a user click the active area to which the current hypertext command is associated.

    See the current set of Available hypertext commands.

    Command syntax text box

    Enter the command parameters.

    Hypertext commands must always appear in lowercase. The parameters can be uppercase or lowercase, but they are case-sensitive. The entire command can be up to 255 characters long. (Each character in a Japanese font counts as two characters.)

    Note: If you enter a filename parameter for a file that is not in the same folder as the current document, specify a path to the document.
    Note: Hypertext markers support the Unicode text encoding standard.

    See the current set of Available hypertext commands.

    Validate Command upon Insertion

    FrameMaker will validate the syntax as soon as you insert the command in the document.

    Make View-Only

    Make the current document view-only.

    You can also use this option to text the hypertext commands that you insert in a document.

  4. Click New Hypertext Marker.

A hypertext marker is inserted in the document.

Note: To insert a hypertext command in a text inset, insert the command in the text inset source document.
Note: If a cross-reference is present in the same text area as a hypertext command, the cross-reference takes precedence over the hypertext command.

Edit and delete hypertext commands

Learn to edit and delete hypertext commands in FrameMaker.

Editing a hypertext command

  1. Open the Hypertext dialog and use the Find / Change dialog to find the hypertext command to edit.

    In the Find drop-down list, choose Any Marker.

    The marker will be displayed in the Hypertext dialog.

  2. Change the required options for the command and click Edit Hypertext Marker.

Deleting a hypertext command

  1. Open the Hypertext dialog and use the Find/Change dialog to find the hypertext command to edit.

    In the Find drop-down list, choose Any Marker.

    The marker will be displayed in the Hypertext dialog.

  2. Press the Delete key to delete the marker.

Available hypertext commands

Know the available hypertext commands in FrameMaker.

The sections covers the available hypertext commands to:

Display alert messages

You can display alert messages on the click on an active area by using the Alert and Alert With Title commands.

Note: In PDF output, an alert message appears as a note without a title.

Alert

Displays an alert message.

Syntax:

alert message

Example:

alert Hello world

To display a custom title with the alert message:

  1. Open a reference page for the current document (View > Reference Pages).

  2. Place a text frame on the reference page and enter the custom title in the text frame.

  3. Right-click on the text frame and choose Object Properties to display the Text Frame Properties dialog.

  4. Go to the Text Frame tab and set the Flow > Tag to AlertTitle.

Alert With Title

Displays an alert message with a user-defined title.

Syntax:

alerttitle title:message

Example:

alerttitle Message to the World:Hello world

Navigate to a named destination

You can navigate to a specific destination in the current or another FrameMaker document. To do this, you need use the Specify Named Destination command. You then point to this destination when you create any of the following commands:

Note: If you omit the Specify Named Destination command, the Jump To Named Destination and Open Document commands do not work when clicked unless they reference a filename. In that case, the other file opens, showing the first page.

Specify Named Destination

Specify a named destination location.

Syntax:

newlink linkname

Example:

newlink available_hypertext_commands

Note: The named destination name is case-sensitive and cannot contain spaces.

Jump To Named Destination

Pointer to the named destination defined by the Specify Named Destination. You can point to a named destination in the current or another FrameMaker document.

Syntax:

gotolink filename:linkname

Example to a named destination in the current document:

gotolink available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

gotolink hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension (for example .fm).

Jump To Named Destination & Fit To Page

Pointer to the named destination defined by the Specify Named Destination. You can point to a named destination in the current or another FrameMaker document. The window is then resized to fit the destination document page.

Syntax:

gotolinkfitwin filename:linkname

Example to a named destination in the current document:

gotolinkfitwin available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

gotolinkfitwin hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension (fore example .fm).

Open Document

Point to the named destination defined by the Specify Named Destination. If the destination is a different document, it opens in a new window.

Syntax:

openlink file_name:linkname

Example to a named destination in the current document:

openlink available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

openlink hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension.

Open Document & Fit To Page

Point to the named destination defined by the Specify Named Destination. If the destination is a different document, it opens in a new window. The new window is then resized to fit the document page displayed.

Syntax:

openlink file_name:linkname

Example to a named destination in the current document:

openlink available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

openlink hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension.

Navigate to a specific page

You can navigate to a specific page in the current or another FrameMaker document.

Jump to First Page / Last Page

Point to the first or last page of the current or a different document. The page is displayed in the active window.

Syntax:

gotolink filename:firstpage

gotolink filename:lastpage

Example to a named destination in the current document:

gotolink firstpage

Example to a named in another FrameMaker (.fm) document:

gotolink hypertextcommands.fm:lastpage

Important: You need to specify the destination file extension.

Jump To Page Number

Point to a specific page in the current or a different document. The page is displayed in the active window.

Syntax:

gotopage filename:pagenumber

Example to a named destination in the current document:

gotopage 7

Example to a named in another FrameMaker (.fm) document:

gotopage hypertextcommands.fm:7

Important: Use the actual page number in the document. For example, if the destination document MyDoc uses Roman numerals for page numbers and begins on page v, the command to display the third page is open page MyDoc.fm:vii.

Jump To Previous Page / Next Page

Point to the previous or next page of the current document. The page is displayed in the active window.

Syntax:

previouspage

nextpage

Example:

previouspage

nextpage

Tip: Add the previous and next page hypertext commands to on the master pages of a document to display these on every page of the document.

Navigate back

You can place hypertext commands on pages that a reader can click to go back to the page from which the reader reached the current page. This behavior is similar to the back button functionality on your web browser. For example, if you have create an active text area on a page to navigate the user to another page on the document. On the destination page, you can place a Jump Back or Jump Back & Fit to Page hypertext commands.

Note: If the stack is empty and if you have not provided a filename and linkname, FrameMaker leaves the current page displayed.

Jump Back

Navigate back to the previous page. The page is displayed in the active window.

Syntax:

previouslink filename:linkname

Example to a named destination in the current document:

previouslink available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

previouslink hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension.

Jump Back & Fit to Page

Navigate back to the previous page. The page is displayed in the active window. The new window is then resized to fit the document page displayed.

Syntax:

previouslinkfitwin filename:linkname

Example to a named destination in the current document:

previouslinkfitwin available_hypertext_commands

Example to a named in another FrameMaker (.fm) document:

previouslinkfitwin hypertextcommands.fm:available_hypertext_commands

Important: You need to specify the destination file extension.

Open documents

You can open documents as new FrameMaker documents (Open Document As New), open the document on the first or last page(Open Document At First/Last Page), or open a document on a specific page number (Open Document At Page Number).

Open Document As New

Opens a document (defined in the file name argument) as a new, unnamed document. The document displays in a new window, leaving the active window open.

Syntax:

opennew filename

Example:

opennew hypertextcommands.fm

Important: You need to specify the destination file extension.

Open Document At First/Last Page

Opens a document at the first or last page of the document. The page appears in a new window (leaving the active window open) only if the page is in a different document.

Syntax:

openlink filename:firstpage

openlink filename:lastpage

Example:

openlink hypertextcommands.fm:firstpage

Important: You need to specify the destination file extension.

Open Document At Page Number

Opens a document at a specific page. The page appears in a new window (leaving the active window open) only if the page is in a different document.

Syntax:

openpage filename:pagenumber

Example:

openpage hypertextcommands.fm:7

Important: You need to specify the destination file extension.

Button Matrix

Defines a contiguous set of clickable areas in an image and associates one hypertext command with each area.

For example, you can take a screen capture of a toolbar in an application and then assign one hypertext command to each button on the toolbar. The hypertext command then navigates the reader to the corresponding help for the associated button on the toolbar image.

Syntax:

matrix rows columns ReferencePageFlowName

Example:

matrix 1 3 button_matrix_flow

rows

Number of rows of buttons

columns

Number of buttons in a row

ReferencePageFlowName

Text frame created on the document reference page that defined the hypertext command for each button in the matrix.

Define a button matrix

Define a button matrix to the map the three icons in the following image to three corresponding hypertext commands:

Button matrix image
Button matrix image in FrameMaker

  1. Go to the reference page for the current document (View > Reference Pages).

  2. Define a text frame on the reference page and set the value of the flow tag to button_matrix.

    The flow tag value is used to map the image text frame (Step 1) to the text frame on the reference page.

    1. Open the Text Frame Properties dialog.

      Right-click on the text frame and choose Object Properties.

    2. Go to the Text Frame tag and enter button_matrix in the Tag field.

  3. In the text frame, enter the hypertext command for each button matrix.

    For example, you can use the Jump To Named Destination command to navigate the reader to a named destination when the user clicks on a button in the matrix.

    gotolink first_button_help 
gotolink second_button_help 
gotolink third_button_help

  4. Add the above image to a FrameMaker document and Define an image active area.

  5. In the text frame, add the following button matrix hypertext command:

    matrix 1 3 button_matrix

    The image contains one row of icons and three columns. Also, the text frame flow tag, on the reference page, is defined as button_matrix (Step 2).

    The hypertext command defined on each line in the reference page text frame (Step 3) corresponds to the command to be executed for each button on the image (Step 4).

    This means that for the following button matrix hypertext command, the reference page text frame (button_matrix_flow) must contain hypertext commands on six lines:

    matrix 2 3 button_matrix_flow

  6. You need to Specify Named Destination

  7. To test the button matrix, click Make View-Only in the Hypertext dialog.

If you plan to create PDF or HTML output for FrameMaker document containing a button matrix, ensure PDF and HTML: Hypertext command support.

Go to URL

Launches browser and displays the specified web page.

Syntax:

message URL url

Example:

message URL http://www.adobe.com

Open external applications and files

You can use the hypertext command to open external applications and files.

Syntax:

message system application name or path, window state

Note: The window state argument is set to SW_SHOWNORMAL. If you omit this argument, the external application opens in the last exited state.
Example:

To open Microsoft Word in the maximized window state:

message system winword, SW_MAXIMIZE

Example:

To open Microsoft Word in the minimized window state:

message system winword, SW_MINIMIZE

Example:

To open a specific PDF document, specify the complete path to the document:

message system c:/hypertextdocuments.pdf

The PDF opens in the default application.

To specify the application to open the file:

message system acrobat c:/hypertextdocuments.pdf

The above examples specify the application name. You can also specify the complete path to the application .exe file. For example, if you have multiple versions of an application installed, usually the latest version is the default. You can open a previous version by specifying the complete path to the .exe for the version.

Example:

To open an application by specifying the complete path to the application .exe file:

message system "C:\Program Files\Adobe\Adobe FrameMaker 2019\FrameMaker.exe"

Note: Use double-quotes if the file path contains spaces.

Window states

The following table lists the available window state options:

State

Definition

SW_HIDE

Hides the window and activates another window

SW_MAXIMIZE

Maximizes the specified window

SW_MINIMIZE

Minimizes the specified window and activates the next window in the Alt+Tab order

SW_RESTORE

Activates and displays the window (If the window is minimized or maximized, Windows restores it to its original size and position.)

SW_SHOW

Activates the window and displays it in its current size and position

SW_SHOWDEFAULT

Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application

SW_SHOWMAXIMIZED

Activates the window and displays it as a maximized window

SW_SHOWMINIMIZED

Activates the window and displays it as a minimized window

SW_SHOWMINNOACTIVE

Displays the window as a minimized window (The active window remains active.)

SW_SHOWNA

Displays the window in its current state (The active window remains active.)

SW_SHOWNOACTIVATE

Displays a window in its most recent size and position (The active window remains active.)

SW_SHOWNORMAL

Activates and displays a window (If the window is minimized or maximized, Windows restores it to its original size and position.)

If you omit the windowstate value, the window state is set to SW_SHOWNORMAL. For more information on window states, see the documentation for the Windows software development kit.

Close FrameMaker and FrameMaker documents

You can use hypertext commands to close the current document (Close Current Document) and close all open view-only document (Close All Hypertext Windows). You can also create a hypertext command to exit FrameMaker (Exit FrameMaker).

Close Current Document

Close the current active FrameMaker document.

Syntax:

quit

Close All Hypertext Windows

Close all open view-only FrameMaker documents.

Syntax:

quitall

Exit FrameMaker

Exit the current instance of FrameMaker.

Syntax:

exit

PDF and HTML: Hypertext command support

Know the hypertext command support in FrameMaker.

View-only FrameMaker documents support all hypertext commands.

PDF and HTML outputs of hypertext documents, have limited support.

The following table describes the PDF and HTML support:

Command

PDF

HTML

Alert, Alert with Title

Appears as a note, with no title

NO

Jump to Named Destination

YES

YES

Jump to Named Destination & Fit to Page

Works as described, but doesn’t fit to page

Works as described, but doesn’t fit to page

Jump to First Page, Jump to Last Page, Jump to Page Number, Jump to Previous Page, Jump to Next Page

YES

NO

Jump Back, Jump Back & Fit to Page

NO

NO

Open Document

YES

YES

Open Document & Fit to Page, Open Document as New, Open Document at First Page, Open Document at Last Page, Open Document at Page Number

Works as described, but doesn’t fit to page or open a separate window

Works as described, but doesn’t fit to page or open a separate window

Pop-up menu

NO

NO

Button Matrix

NO

Works as described, if the text frame containing the command is in an anchored frame in the main text flow

Message URL

Works when PDF is opened in browser; however, the link sometimes does not work in Acrobat

YES

Message Client

NO

NO

Close current window, Close All Hypertext Windows, Exit Application

NO

NO

Create an image map

Understand how to use the hypertext commands to create different clickable regions in a single image through image map in FrameMaker.

You can use the hypertext commands to create different clickable regions in a single image. In the following procedure, create three clickable regions around the rectangles in the following flowchart:

Clickable image map
Creating a clickable imagemap in FrameMaker

  1. Define an image active area for each rectangle.

  2. Insert a Jump To Named Destination hypertext command in the text frame for each image active area.

  3. Use the Specify Named Destination hypertext command in the three destinations for each of the three clickable regions.

  4. To test the image map in FrameMaker, click Make View-Only.

In this example, the Named Destination hypertext command is defined in each of the clickable regions. You can use any combination of the Available hypertext commands.

Note: All available hypertext commands function in the FrameMaker view-only documents. However, if you create PDF of HTML output from FrameMaker, you will need to check the PDF and HTML: Hypertext command support.

April 29, 2020

Legal Notices | Online Privacy Policy