PDF Acrobat Operations That Can Only Be Done With JavaScript

When something can't be done with the Acrobat User Interface, a script can be used.

Photo by Gabriel Heinzer on Unsplash

In my last column, PDF Form Reset Tricks, I mentioned how almost every field property of every field type can be set using a script, instead of using the Acrobat Pro user interface (UI).  All you need to do is run the script in the JavaScript console (I feel like I just gave myself an idea for a future post. Let me know in the comments what subjects you would like me to cover in future articles.).  There are other things that can't be done with the UI and can only be done with a script.

---

                Take the Acrobat Pro/JavaScript eLearning Course Acrobat Like a Pro

---

An Empty Dropdown Field Item

When I create dropdown fields in PDF forms, I usually set the default item to be nothing, or empty.  I don't like redundant instructions like "Please make a selection" as the default.  It's a dropdown field.  That's what you do – you make a selection.

It's not possible to insert a nothing item into a dropdown list using the Acrobat UI.  There's supposedly a "workaround", which is to use a single space in place of nothing.  However, if you have any scrips that test the field for whether it has a value, it won't work because a single space is a value, while nothing is not.  For example, assume the field's name is "Dropdown1".  If the default is a single space and the current value is the default the following script, meaning "Dropdown1" has no value, will return false:

!this.getField("Dropdown1").value;

If the default is nothing, and the current value is the default, the script above will return true (true that the field "Dropdown1" has no value.  Sure, you can test for a value of single space instead of no value, but things can get messy very quickly.

setItems Method

The setItems() method for list box and combo box (dropdown) fields takes an array of values as the input parameter.  Simply use an empty string as the first array element to get a nothing item when running the script in the console:

this.getField("Dropdown1").setItems(["","A","B","C","D"]);

If the field will have export values that are different from the display values, an array of arrays can be input, where the first element of each array is the display value and the second element is the export value:

this.getField("Dropdown1").setItems([["",""],["A",25],["B",50],["C",75],["D",100]]);

Shameless Plug

www.pdfautomationstation.com sells a Dropdown Filler tool that allows you to set the items of a dropdown or list box field by simply copying and pasting an Excel column into popup window.  Pasting two columns will result in different export and display values.  Simply use an empty Excel cell at the top of the column for a nothing value.

Multiline Tooltip

There's an option in the General tab of the field properties of every PDF field type called Tooltip, that allows you enter text that will be displayed when the user hovers over the field with the mouse.  The Tooltip field in the UI is a single line field.  Suppose you created a button field with an information icon so the user could hover over it for instructions.  And suppose you wanted your instructions broken down into different lines line this:

Instructions

1)   Do this.
2)   Do that.
3)   Do this and that.
4)   Do this, that, and the other thing.

Is it possible to create a tooltip with multiple lines?  Unfortunately, it's not possible with the Acrobat UI.  If you enter too much text into the field, the tooltip will wrap the text, creating a multiline tooltip, but you have no control over where the text wraps.  If you try to copy and paste multiple lines of text into the tooltip field, it will only accept the first line of text.

The good news is that you can create a multiline tooltip and have complete control over the line breaks by using a script to set the tooltip, and using the special character combinations of either \r (carriage return) or \n (new line) to create the line breaks.  The tooltip field property is called userName in JavaScript.  Suppose your field is called Button1.  Run the following script in the console and the result will be a multiline tooltip with controlled line breaks:

this.getField("Button1").userName=
"Instructions\r\r"+
"1) Do this.\r"+
"2) Do that. \r"+
"3) Do this and that. \r"+
"4) Do this, that, and the other thing."

OR

this.getField("Button1").userName=
"Instructions\n\n"+
"1) Do this.\n"+
"2) Do that. \n"+
"3) Do this and that. \n"+
"4) Do this, that, and the other thing."

Conclusion

I've outlined two things that you can only do with a script when creating PDF forms.  I'm sure there are many more.  This one reason to learn JavaScript if you work with PDFs.  See you next time…

Learn JavaScript by Subscribing to PDF Automation Station