![](/uploads/1/2/5/7/125754647/494092849.jpg)
By V. Subhash
Most people associate JavaScript with Web browsers and HTML pages. (Not many people remember that Internet Explorer supported VBScript as an alternative for JavaScript.) JavaScript has also been used on the server-side in Classic ASP as an alternative for VBScript. JavaScript on the server-side is not a recent phenomenon with Node.js and other technologies. The well-known Adobe Flash player runs a form of JavaScript called ActionScript. At least most virus writers know that JavaScript can be run from your Windows command prompt.
Although JavaScript requires a scripting host application, it is not tied to any particular implementation. The language is developed and standardized by the ECMA independently of the scripting hosts.
Note: Your browser does not support JavaScript or it is turned off. Press the button to proceed.
The scripting host in a Web browser exposes the 'host objects' such as
window
, document
(DOM) and location
objects to the JavaScript engine. Similarly, in Adobe Reader, Adobe Acrobat and other applications, the viewer exposes several host objects to the JavaScript engine. These host objects are described in two documents:HTML+JavaScript or DHTML was once sold to the general public as 'HTML with steroids'. JavaScript can indeed super-charge your PDF documents. In this article, we will see a bit of what you can do with it. I have used PDFOne .NET to add JavaScript to PDF documents. You can do the same with any PDF library such as PDFOne (for Java) and PDFtoolkit VCL.
A 'Hello, World!' Example
This code snippet uses the
app
object's alert()
method. This alert has been added to the document's 'Open' viewer application event. There are other situations where you can add such JavaScript scripts - 'close', 'save', or 'print'.Let us look up the
app
object in the API Reference.Now, using the API reference, the above alert can be made less foreboding.
Add JavaScript to PDF objects
JavaScript scripts can be added to PDF objects such as annotations, form fields and even bookmarks. In the following example, a JavaScript script has been added to a link annotation.
This JavaScript script uses the
this
object where it refers to the Document
object. Document
has a numPages
property for providing the page count.BTW,
this
refers to different things in different places. Please read the documentation to avoid making mistakes. Another thing to note is that in Adobe Reader, the document is considered read-only with limited scope for modification. Any JavaScript code that tries to make permanent changes to a document will fail or require the end-user to save change to a new file.I know what you are thinking. What if you commit errors in your JavaScript scripts? Well, you can check the console.
JavaScript Error Console
Adobe Reader and Adobe Acrobat have an error console. You can enable it from Preferences from the menu or launch it using its namesake
console
object.How to get something?
Web programmers are familiar with the infamous
document.getElementById()
method. Does Acrobat JavaScript have something similar? There are several. The following example uses the getField()
method to grab a push button form field and add some behaviour to it at startup.PDF Form Validation With JavaScript
After you 'get' a form field, you can evaluate its value using the
valueAsString
property. If you find the form fields to be valid, you can submit the form using Document.submitForm()
method.Caveat emptor
Running JavaScript in PDF documents is great, no doubt, but you should not rely on it without a fallback mechanism. For example, if you are using JavaScript to do form validation, then you still need to do server-side validation. Not all PDF viewer applications have a JavaScript engine. The PDF/A standard expressly forbids JavaScript. Users may also disable JavaScript in their viewer application. Digital signatures may also add their own complications to the mess. Worst of all, it is not all that easy to add JavaScript or debug it. Gnostice wishes you good luck in your personal forays into AcroJS.
Further Reading
On this page:
Important Information about Techniques
See Understanding Techniques for WCAG Success Criteria for important information about the usage of these informative techniques and how they relate to the normative WCAG 2.0 success criteria. The Applicability section explains the scope of the technique, and the presence of techniques for a specific technology does not imply that the technology can be used in all situations to create content that meets WCAG 2.0.
Applicability
This technique relates to:
- Success Criterion 3.3.1 (Error Identification)
- Success Criterion 3.3.3 (Error Suggestion)
User Agent and Assistive Technology Support Notes
See User Agent Support Notes for PDF22. Also see PDF Technology Notes.
Description
The objective of this technique is to notify the user when user input to a field that requires a specific, required format (e.g., date fields) is not submitted in that format.
If the required format is not used, an alert dialog describes the nature of the error in text. This may be accomplished through scripting created by the author (see, for example, SCR18: Providing client-side validation and alert). User agents, such as Adobe LiveCycle can provide automatic alerts (as described in the examples below).
Note: Once the user dismisses the alert dialog, it may be helpful if the script positions the keyboard focus on the field where the error occurred, although some users may expect the focus to remain on the last control focused prior to the alert appearing. Authors should exercise care to ensure that any movement of the focus will be expected. For example, if the alert announces an error in a phone number format, positioning the focus on the phone number field when the alert is dismissed can be regarded as helpful and expected. In some cases, however, this may not be possible. If multiple input errors occur on the page, an alternative approach to error notification should be implemented.
![Livecycle Livecycle](http://www.w3.org/TR/2012/NOTE-WCAG20-TECHS-20120103/working-examples/PDF23/lc-blank.jpg)
Ensuring that users are aware an error has occurred, can determine what is wrong, and can correct it are key to software usability and accessibility. Meeting this objective helps ensure that all users can complete for-based transactions with ease and confidence.
Labels for required formats in form controls
It is also important that users are aware that an error may occur. You can incorporate this information in labels; for example, 'Date (MM/DD/YYYY).' See PDF10: Providing labels for interactive form controls in PDF documents.
Examples
Example 1: Providing validation for an input field format using Adobe Acrobat 9 Pro
This example is shown with Adobe Acrobat Pro. There are other software tools that perform similar functions. See the list of other software tools in PDF Authoring Tools that Provide Accessibility Support.
Many fields -- telephone number, postal code, date -- must have data entered in a specific format or pattern.
- Access the context menu for the form control that requires a specific format.
- Select Properties...
- In the Format tab, select the Format Category (in this case, Date). The Date Options appear.
- Select the format for this form control (in this case, mm/dd/yyyy).
- In the General tab, specify 'Date (mm/dd/yyyy)' for the Name and Tooltip for the control.
When a user types a recognized date format, it is converted automatically to the specified format. If the date format or value is not recognized, an error alert appears and provides further information, as shown in the image below.
This example is shown in operation in the working example of Required Fields in Acrobat.
Example 2: Providing validation for an input field format using Adobe LiveCycle Designer ES 8.2.1
This example is shown with Adobe LiveCycle Designer. There are other software tools that perform similar functions. See the list of other software tools in PDF Authoring Tools that Provide Accessibility Support.
- Select the form control that has a required format.
- In the Object palette, click the Validation Pattern... button.
- Because this is a date field the Patterns-Date Field dialog appears. Select the pattern or format you want users to enter. Then click OK.
- In the Object palette, use the Validation Pattern Message box to type a warning message. Be sure to include the required pattern. This message appears when a user tries to submit the form using an invalid date format.
This example is shown in operation in the working example of Required Fields in LiveCycle Designer.
Example 3: Validating a required date format in a PDF form using JavaScript using Adobe Acrobat Pro 9
This example is shown with Adobe Acrobat Pro. There are other software tools that perform similar functions. See the list of other software tools in PDF Authoring Tools that Provide Accessibility Support.
The following JavaScript code illustrates the use of a script to validate form fields, in this case, a date field. To add this script to the form field, open the Text Field Properties dialog, as shown in Example 1, and select Edit in the Validate tab:
Resources
Resources are for information purposes only, no endorsement implied.
Related Techniques
Tests
Procedure
For each form field that requires specific input, verify that validation information and instructions are provided by applying the following:
- Check that the format or value that is required is indicated in the form control's label.
- Use an erroneous format or value and move off the field: make sure that an alert describing the error is provided.
Expected Results
- #1 and #2 are true.
If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.
This Web page is part of Techniques and Failures for Web Content Accessibility Guidelines 2.0 (see the latest version of this document). The entire document is also available as a single HTML file. See the The WCAG 2.0 Documents for an explanation of how this document fits in with other Web Content Accessibility Guidelines (WCAG) 2.0 documents. To send public comments, please follow the Instructions for Commenting on WCAG 2.0 Documents.
Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
![](/uploads/1/2/5/7/125754647/494092849.jpg)