Validating Required PDF Fields

How to validate required fields before sending the PDF form with an email button

Photo by Glenn Carstens-Peters on Unsplash

In my last article I described how to create a button that sends a completed PDF fillable form by email. I outlined two methods and suggested the second document method is the preferred method for sending the form as an email attachment:

1. submitForm( )

2. mailDoc( )

What If You Want To Validate Fields Before Sending?

The submitForm( ) method will not send, and will display a warning message, if any "required" fields have a null value. The required property of the field is located in the General tab of the field properties:

Required property of a PDF form field

The warning message does not specify which fields are missing data (keep reading for a more customized field validation strategy):

However, the missing fields get highlighted in red. Check box and radio button fields that are not selected have a value of "Off" (not null), so if these are required and unselected they won’t be caught in the field validation.

Also, there seems to be a glitch with Adobe software right now when the required property of dropdown and list box fields is set to true and the values are null. They are passing the submitForm( ) validation test when they shouldn’t be. BTW, the Acrobat UI does not have a way to add null entries to dropdown and list box fields. A workaround is to enter a single space. However, a space is a value so this selection does not produces a non-null value. Null entries must be set with a script as outlined in the following article:

Another to way set null entries in dropdowns and list box fields is to use the Dropdown Filler plugin tool I developed.

submitForm( ) Validation Issues

To summarize, the following issues were identified when using the required field property to validate fields for missing data when with the submitForm( ) method:

1. The warning message does name the required fields that contain missing data.

2. Required check box and radio button fields will pass the validation test when they are not selected.

3. Adobe has glitch that is causing required dropdown and list box fields to pass the validation test when they shouldn’t.

Another Method Using mailDoc( )

If using mailDoc( ), the preferred method for sending completed PDF forms as email attachments, the problems with submitForm( ) validation are of no concern, but noteworthy nonetheless. The mailDoc( ) method does not validate required fields so you have to build your own validation script. I’ll walk you through the steps to building a custom validation script for your email button that doesn’t have any of the three issues previously mentioned.

The first step is to define a counting variable and set its value to zero:

var num=0;

Step two is to create an array of mandatory ("required") field names:

var aray=["First Name", "Last Name", "Email", "Applicant Type", "Checklist"];

The field names should have relevant meaning because they’ll be named in the warning message. For example, if First Name was not completed, you wouldn’t want the warning message to say "Field Text 21.5 is mandatory". Step three is to loop through the array of field names and test the fields for null values.

for(var i=0; i<aray.length; i++)
{
if(!this.getField(aray[i]).value)
{/*do something if the test in the line above is true (no value)*/}
}

The do something in the script above is:

1. Increment the counting variable.

2. Pop up a warning message.

3. Set the focus to the empty field that was detected (optional and helpful to the end user).

4. Break the loop. Without this step, the warnings will continue to pop up for each null value field. This would get vary annoying for the end user if five popups appeared in succession, and also make it difficult to keep track of the fields that still need to be completed.

var num=0;
var aray=["First Name", "Last Name", "Email", "Applicant Type", "Checklist"];
for(var i=0; i<aray.length; i++)
{
if(!this.getField(aray[i]).value)
{
app.alert(aray[i] + " is mandatory.",1);
num++;
this.getField(aray[i]).setFocus(); 
break;
}
}

The 1 after mandatory.”, is for the icon in the alert message. There are several options. Try these by running the following lines one at a time in the console:

app.alert("",0); // an X
app.alert("",1); // an exclamation point
app.alert("",2); // a question mark
app.alert("",3); // an information "i"
app.alert("",4); // No icon (undocumented)

If multiple fields in the array are empty, the script will only pop one warning each time the button is clicked until all fields contain values. Continuing the script, it will now test the counting variable value and proceed to send the email if the variable is still zero (it will be 1 if the loop failed the tests):

if(num==0){this.mailDoc({cTo:"email@something.com",cSubject:"Returned Form"});}

Suppose the Checklist field is a group of radio buttons or check boxes. If none of the group is checked off, the field will have a value of "Off", which is a value, so the test will pass. To avoid this you can modify the script so it tests this field for a value of "Off" instead of no value (null). Here’s the entire script:

var num=0;
var aray=["First Name", "Last Name", "Email", "Applicant Type", "Checklist"];
for(var i=0; i<aray.length; i++)
{
if(!this.getField(aray[i]).value || (aray[i]=="Checklist" && this.getField(aray[i]).value=="Off"))
{
app.alert(aray[i] + " is mandatory.",1);
num++;
this.getField(aray[i]).setFocus(); 
break;
}
}
if(num==0){this.mailDoc({cTo:"email@something.com",cSubject:"Returned Form"});}

If you have any questions about this post, or if you would like to save $100 on my Acrobat Pro JavaScript eLearning course, please ask in the comment section below.