Add Tooltips to PDF Documents Via Text Search

AutoBookmark plug-in for Adobe® Acrobat®

What is a Tooltip?
A tooltip is an informative graphic which appears when hovering over a screen element. It shows a pop-up text box displaying information. Common cases are tooltips displaying a definition of a word when hovering over specific text - or a short description of the function of a particular tool in a toolbar.
In this tutorial, we’ll demonstrate how to use an "Add Tooltips by Text Search" operation to add tooltips to a collection of search terms in a PDF. Tooltips are added as regular text highlights - use Acrobat's ‘Comment’ tool to manage them. The tooltips are generated based on a user-supplied text file that contains tooltip search text and corresponding definitions/explanations. There is another method to generate tooltips using invisible form buttons.
In the steps below, we will first look at how to create the necessary text file containing the required search text and definitions. We will then use this file to generate tooltips in a sample PDF document.
The goal is to highlight matching search text (capitalized monarch names) in a sample PDF family tree, and add pop-up tooltips:
When the cursor is hovered over highlights, the cause/location of death for the individual is displayed within a tooltip box. This is an effective way of providing more detailed information within a document, without including too much complex text in its standard visual appearance.
You need a copy of Adobe® Acrobat® along with the AutoBookmark™ plug-in installed on your computer in order to use this tutorial. Both are available as trial versions.


Step 1 - Create Tooltip Text File ↑overview
The first step is to create the input tooltip text file. This is a plain text file that consists of one or more tooltip definitions. Each definition is a comma-separated pair of two text strings; one definition per text line. The first one is the search text, the second one is the tooltip text to be shown when the highlighted word is hovered over.
Use any plain text editor or spreadsheet software such as MS Excel to create a comma-separated values (CSV) file. Every spreadsheet application has an option for exporting data in this file format. Here, we will use Excel - start the application to open a new blank workbook.
List search terms in column A (one-per-line) and tooltip text in column B. The first row of text is ignored and can be used as a header. In the example shown below, the names of each monarch are listed as search terms - each one followed by their cause of death, as well as a location and date.
Use "File > Save As..." to save the spreadsheet as a CSV file. In the "Save As" dialog, type a suitable file name and select the "CSV (comma delimited)" option from the "Save as type:" drop-down list before pressing "Save".
If using a plain text editor (such as Notepad), list search items (one-per-line) followed by a comma, then the desired tooltip text (word definition/explanation). The file can also include empty lines - any line without a comma in the text is ignored and can be used as a comment line.
Use "File > Save As..." to save the file.
In the "Save As" dialog, choose a suitable folder and select the "All Files" file type. Name the file and manually add a *.csv file extension before pressing "Save".
Handling Commas
If a search item contains a comma, then it should be enclosed within quotation marks in the tooltip file if using a text editor program such as Notepad. Here is an example of a tooltip definition with a comma in the search text:
In Excel, it is not necessary to add quotation marks. The presence of the comma is identified and the plug-in will search for this text as it is typed.
Using either of the examples above as the tooltip file would result in any occurrences of the text “Reid, Thomas Mayne" being highlighted in an input document. A tooltip displaying “Thomas Mayne Reid (4 April 1818 – 22 October 1883) was an Irish-American novelist” will pop up when the cursor is hovered over this text:
Step 2 - Open "Add Tooltips to Text" Dialog ↑overview
Open the document that you want to add tooltips to in Adobe Acrobat, and press "Plug-ins > Tooltips > Add Tooltips by Text Search...".
Step 3 - Load Tooltip Text File ↑overview
Press "Browse..." to locate the saved tooltip text file.
Locate the CSV file created in step 1, select it, and press "Open".
Step 4 - Select Processing Options ↑overview
The comma-separated search words and tooltip text are imported, and displayed in the "File Preview:" box:
Use the checkboxes available to select any necessary processing options. In this example, we will check "Match case" so that the text search is case sensitive. This means that only the capitalized occurrences of the monarch names will be highlighted and have tooltips added to them. Optionally use "Match whole words only" so that only complete words match. This avoids partial matches where search words may appear as part of larger words.
By default, matching words will be highlighted using a bright yellow color. Use the drop-down list next to "Highlight color:" to select another option. Use "Custom..." to configure a customized color.
Step 5 - Optional: Process Only Specific Pages ↑overview
Press "Page Range..." to select pages for processing.
Choose between: processing all pages of the document (default); only the currently open page; or a specific range of pages.
Optionally process only a specific page subset by using the drop-down list (e.g. odd/even pages).
Press "OK" to confirm the settings.
Step 6 - Add Tooltips ↑overview
Press "OK" to run the procedure.
A report box shows the number of tooltips added to the selected page(s). Press "OK" to close it.
Step 7 - Inspect the Results ↑overview
The matching search text has been highlighted in the input document and the tooltips have been added.
Hover the cursor over highlighted text to reveal the corresponding tooltip.
Clicking on highlighted text opens a pop-up sticky note that displays the tooltip text. Note: the color of the annotation box will match the chosen highlight color.
Step 8 - Optional: Delete Tooltips/Text Highlights ↑overview
IMPORTANT: if text is already highlighted/has a tooltip added, then a new tooltip can not be added to it. Tooltips/highlights need to be deleted first.
To remove tooltips/highlights, press "Plug-ins > Tooltips > Delete All...".
Use the dialog that opens to configure which pages you want to delete highlights from, and press "OK". All highlights in the selected page(s) will be removed.
Optional: Customize Text Highlight Colors ↑overview
It’s possible to highlight matching search items using specific colors. Use a “color=XXXX” keyword (containing a HTML hex color code) on its own line to use a custom color for all tooltip definitions that follow. There are many online resources that provide color reference tables in this format – see this W3Schools page showing a variety of color shades and their relevant codes.
For example, use color=FFFF00 to make the search entries below it in the tooltip text file a bright yellow color in the output. It is possible to use different colors for different tooltips, by listing tooltip definitions for one color after each color keyword.
Below is an example of using different color codes in the tooltip file. List search items and tooltip text below color keywords featuring a desired HTML code:
Matching text will be highlighted in this color - tooltip boxes will also match the color coding:
Optional: Add Tooltip Window Header ↑overview
Optionally, it is possible to add a header to the tooltip windows by entering a Header= keyword on a separate line. Here is an example how to add "Definition" header at the top of the popup tooltip window:
Search Text,Tooltip
Winter, "December,January,February"
Summer, "June,July,August"
Note that once header is specified it is going to be used for all consequitive tooltips. It is possible to use multiple Header keyword in the file.
Here is an example of a tooltip with a header:
Optional: Specify Search Options ↑overview
There are four search options that may also be included in the tooltip file. They provide manual control over making the search case sensitive, or one that matches whole words only. These can be specified anywhere in the file, and always apply to the whole search - it is not possible to execute these options on only one part of the file.
  • matchcase=no - do not match text case when performing a text search.
  • matchcase=yes - match text case when performing a text search.
  • wholewords=no - search terms will match even if text appears as part of a longer word.
  • wholewords=yes - match only whole words and phrases.
The example below demonstrates the use of "matchcase=yes" being included on its own line within the tooltip file. This makes it unncecessary to check the "Match text case" processing option:
Only occurrences of capitalized search text has been highlighted in the PDF:
The image below shows an example of how tooltip text files can be customized using various text search/color keywords:
Click here for a list of all step-by-step tutorials available.