pdfkit/docs/forms.md

AcroForms in PDFKit

AcroForms are interactive features of the PDF format, and they make it possible to include things like text fields, buttons and actions. To include AcroForms you must call the document initAcroForm() method.

• initAcroform() - Must be called when using AcroForms

AcroForm Methods

AcroForm elements are Widget Annotations and are added using the widgetAnnotation method. Additional methods listed below are shortcut methods that call the widgetAnnotation method. The list of the available Widget Annotation document methods is:

• widgetAnnotation( name, x, y, width, height, options)
• formText( name, x, y, width, height, options)
• formPushButton( name, x, y, width, height, name, options)
• formRadioButton( name, x, y, width, height, options)
• formNoToggleToOffButton( name, x, y, width, height, options)
• formChoice( name, x, y, width, height, options)

Options Parameter

Some Widget Annotations have a color option that can be specified. You can use an array of RGB values, a hex color, or a named CSS color value for that option.

• backgroundColor - button background color
• borderColor - button border color

Other options conveniences include:

• label - set button text labels (will set <<MK <<CA (label)>> >>)
• align - set to left, center or right for text within the Widget Annotation
• Field flags that will set bits in Ff
  • readyOnly: 1,
  • required: 2,
  • noExport: 4,
  • multiline: 0x1000,
  • password: 0x2000,
  • toggleToOffButton: 0x4000,
  • radioButton: 0x8000, (will be set when calling the formRadioButton method)
  • pushButton: 0x10000 (will be set when calling the formPushButton method)
  • toggleToOffButton: 0x10000 (will be set when calling the formNoToggleToOffButton method)
  • combo: 0x20000,
  • edit: 0x40000,
  • sort: 0x80000

When using the formChoice method, set options.Opt to the array of choices.

When needing to format the text value of a Widget Annotation, the following options shortcuts are available to implement predefined JavaScript actions. Refer to the Acrobat SDK documentation for the Acrobat Forms Plugin for more information.

• format - object
  • type - value is a string with one of the following values:
    • time
    • date
    • percent
    • number
    • special
    • zip
    • zipPlus4
    • phone
    • ssn
  • params - value is a string, number or array of strings and numbers

Other Methods

The font used for a Widget Annotation is set using the document.font method.

Widget Annotations are, by default, added to the Catalog's AcroForm dictionary as an array of Fields. Fields are organized in a name heirarchy, for example shipping.address.street. You can either set the name of each Widget Annotation with the full name (e.g. shipping.address.street) or you can create parent Fields. In this example you might have a shipping field that is added to the AcroForm Fields array, an address field that refers to the shipping Field as it's parent, and a street Widget Annotation that would refer to the address field as it's parent. To create a field use the document method:

• field( name, options ) - returns a reference to the field

To specify the parent of a Field or Widget Annotation, set the parent options to the field reference.

var shippingRef = doc.field( 'shipping' );
var addressRef = doc.field( 'address', shippingRef );
doc.formText('street`,10,10,100,20,{parent:addressRef});

In support of Widget Annotations that execute PDF JavaScript, you can call the following document method:

• addNamedJavaScript( name, buffer )

Limitations

An important caveat when using AcroForms with PDFKit is that form elements must each have an appearance set using the AP attribute of the annotation. If this attribute is not set, the form element may not be visible. Because appearances can be complex to generate, Adobe Acrobat has an option to build these apperances from form values and Widget Annotation attributes when a PDF is opened. To do this PDFKit sets the AcroForm dictionary's NeedAppearances attribute to true. This could mean that the PDF will be dirty upon open, meaning it will need to be saved. It is also important to realize that the NeedAppearances flag may not be honored by PDF viewers that do not implement this aspect of the PDF Reference.

A final note on NeedAppearances is that for some form documents you may not need to generate appearances. This may be the case for text Widget Annotations that are initially blank. This is not true for push button widget annotations.

---

Here is an example that uses a few of the AcroForm field types.

// Add the link text
doc.fontSize(25)
   .fillColor('blue')
   .text('This is a link!', 20, 0);

// Measure the text
const width = doc.widthOfString('This is a link!');
const height = doc.currentLineHeight();

// Add the underline and link annotations
doc.underline(20, 0, width, height, {color: 'blue'})
   .link(20, 0, width, height, 'http://google.com/');

// Create the highlighted text
doc.moveDown()
   .fillColor('black')
   .highlight(20, doc.y, doc.widthOfString('This text is highlighted!'), height)
   .text('This text is highlighted!');

// Create the crossed out text
doc.moveDown()
   .strike(20, doc.y, doc.widthOfString('STRIKE!'), height)
   .text('STRIKE!');

// Adding go to as annotation
doc.goTo(20, doc.y, 10, 20, 'LINK', {});

The output of this example looks like this.