Popups and Browse Windows Part II
The response window
Like the alert warning popup described in my last article, the response window has one mandatory input parameter, cQuestion, the question or instructional text for the user when completing this one-field popup window.
The popup presents the user with two buttons, OK and Cancel. OK returns the the value the user entered into the text field, while Cancel returns the word null.
Closing the window with the X in the upper right corner will also return the word null. Notice the message Warning: JavaScript Window? Like the alert box, the JavaScript warning does not appear when the script is executed from a privileged context (Action, Console, or trusted function in a Folder Level Script).
The word ECMAScript is replaced by the cTitle parameter when used.
app.response Input Parameters
cQuestion - The question to be posed to the user.
cTitle - The title of the dialog (optional).
cDefault - A default value to the answer to the question (optional).
bPassword - If true the user's response shows asterisks to hide the response (optional, default is false).
bPassword: true cLabel - a short string to appear in front of the text field.
The following script uses the parameter names as the inputs (except bPassword which is false) to demonstrate:
app.response("cQuestion","cTitle","cDefault",false,"cLabel")
The parameter labels can be excluded because they are listed in order. The same script, written with the parameter labels included would look like this:
app.response({cQuestion:"cQuestion",cTitle:"cTitle",cDefault:"cDefault",
bPassword:false,cLabel:"cLabel"})Filling Fields With The User's Response
The response box can be used to fill a form field with the answer from the user. This is especially common for a one-input dynamic stamps.
I received countless communications on the video above when someone's script “doesn’t work”. They send me the script with numerous response boxes in a row for numerous fields. That's not why the scripts don't work. It is usually a misspelled field name or a typo.
A friendly reminder that JavaScript is case sensitive.
The point is that it is very annoying for the end user to have to dismiss several response boxes while not being able to see previous answers and not being able to return to them. The more user friendly way to script a dynamic stamp with multiple inputs is to use a popup dialog where all fields are presented in the same window. The popup dialog is probably the most complex object to code in the PDF form world:
Here's the script to fill in a field called Name using the answer from the app.response method:
this.getField("Name").value=app.response("Enter your name:");The problem with the script above is that if the user clicks the cancel button on the response box, or closes the window with the x in its top right, as previously mentioned, the field value will display the word null (which was returned from the response box script). The way to avoid this is to test the result for a null value and only fill the field if the response is not null.
var rslt=app.response("Enter your name:");
if(rslt){this.getField("Name").value=rslt}The curly brackets in the last line are optional.
//No curly brackets
var rslt=app.response("Enter your name:");
if(rslt) this.getField("Name").value=rslt;It's my habit to always use them because it helps me keep my code blocks organized, especially when writing lengthy scripts with lots of conditional statements. Another way to write if(rslt) from the script above is:
var rslt=app.response("Enter your name:");
if(rslt!=null) this.getField("Name").value=rslt;I prefer the shorter way, which translates to if there is a result from the response box, to the slightly longer way, which translates to if the result from the response box does not equal null. Both produce exactly the same result in the script.
Using The Response Box To Obtain An Email Address To Email A PDF Form
A response box can be used to pass the user-entered email address into the cTo parameter of the mailDoc method.
var rtn = app.response("Enter your email address","SEND EMAIL","",false,"Email:");
if(rtn)
{
this.mailDoc({cMsg:"Attached is the requested form.",
cTo:rtn,
cSubject:"Returned Form"});
}Notice that parameter labels were not used in the response method, cLabel was omitted, and cTitle (the last parameter was used). When omitting parameter labels, all parameters must be present, even optional ones, in the correct order between the first parameter, and last one used. The way to exclude cTitle and still have the script function properly is to use an empty string for the cTitle parameter.
Bonus: Validate Email Address
This method is undocumented. That means that you won't find it in the official JavaScript documentation for Adobe Acrobat. While it works now, that might not always be the case. The following script checks the email address entered by the user and pops up a warning if the email address is not valid (including a null result), which stops the rest of the email script from proceeding.
Forgive me for being extremely obvious to most readers, but when I say “if the email address is not valid” the script is not actually checking the email against some infinitesimal email database. It is simply checking to make sure the structure is correct. That is, something@something.something
Here's the undocumented email validation script you can run in the console, in which an invalid email structure will return false and a valid email structure will return true.
eMailValidate("something@something.something");//returns true
/*omit the @ or the period and it returns false*/
eMailValidate("somethingsomething.something");//returns false
eMailValidate("something@somethingsomething");//returns false
Putting It All Together
var rtn = app.response("Enter your email address","SEND EMAIL","",false,"Email:");
if(eMailValidate(rtn))
{
this.mailDoc({cMsg:"Attached is the requested form.",
cTo:rtn,
cSubject:"Returned Form"});
}
else
{
app.alert("Invalid email address. Please try again.",1);
}Thank you for reading and thank you for subscribing. Please join me next week as I continue this popup/browse series.