PDF Filling Built-ins

Common Built-ins provide general functionality for:

• PDF form filling

• Sorting and grouping lists of maps

The section below contains syntax and examples for PDF form filling. Documentation is also available for Sorting and Grouping Lists of Maps.

Example 1

stepdef "PDF check"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  println(pdfDocument.getText())
  for fieldIndex, field in pdfDocument.getTextFieldNames()
    println(field)
  end
  pdfDocument.setTextFieldValues(["Firstname", "Lastname", "Address"])
  pdfDocument.check("checkbox1")
  pdfDocument.uncheck("checkbox2")
  pdfDocument.setChoiceFieldValue("listbox", "Item 1")
  pdfDocument.save("/Users/user/Documents/filled_simple.pdf")
  pdfDocument.close()
end

Example 2

stepdef "PDF text"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setFont("Helvetica", 16)
             .setColor(0, 0, 0) // black
             .moveTextPositionByAmount(50, 600)
             .addText("John")
             .moveTextPositionByAmount(0, -20)
             .addText("Doe")
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

PDF Form Filling

The PDF form filling methods provide a functionality to fill editable AcroForms or write text using specified coordinates.

Get PDF Document

Gets an instance of the PDF document.

Syntax

<pdfDocument PdfObject> := Common.getPdfDocument(<pdfFilePath String>)

Returns
The PDF document

Parameter

• pdfFilePath - The path to the PDF document that will be filled

Example

stepdef "get PDF document"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
end

Save PDF

Saves the PDF document to a specified path

Syntax

<pdfDocument PdfObject>.save(<saveFilePath String>)

Parameters

• pdfDocument - The PDF document object

• saveFilePath - The file path to where the PDF document will be saved

Example

stepdef "Save the PDF"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setFont("Helvetica", 16)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

Close PDF

Closes the PDF document.

Syntax

<pdfDocument PdfObject>.close()

Parameter

• pdfDocument - The PDF document object

Example

stepdef "PDF text"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setFont("Helvetica", 16)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()

Additional functions for text fields, choice fields and checkboxes can then be applied before saving and closing the modified document.

PDF Builder Methods (Form Filling)

The PDF form filling function provides methods for:

• Getting text from the document

• Saving the document

• Closing the document

• Text fields

• Choice fields

• Checkbox fields

Get Text

Retrieves the text from the PDF document.

Syntax

<pdfText String> := <pdfDocument PdfObject>.getText()

Returns
The PDF text as a String.

Parameter

• pdfDocument - The PDF document object

Example

stepdef "Get PDF text"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    println(pdfDocument.getText())
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()    
end

Save File

Saves the PDF document to the specified path.

Syntax

<pdfDocument PdfObject>.save(<saveFilePath String>)

Parameters

• pdfDocument - The PDF document object

• saveFilePath - The path where the PDF will be saved

Example

stepdef "Save PDF"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.setTextFieldValues(["Firstname", "Lastname", "Address"])
    pdfDocument.save("/Users/user/Documents/updatedSimple.pdf")
    pdfDocument.close()
end

Close File

Closes the PDF document instance and releases the resources taken.

Syntax

<pdfDocument PdfObject>.close()

Parameter

• pdfDocument - The PDF document object

Example

stepdef "Close PDF"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setFont("Helvetica", 16)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

Text Fields

Text field methods retrieve and set text within text fields.

Get Text Field Names

Retrieves the text field names from the AcroForm as a list of Strings.

Syntax

<textFieldNames List<String>> := <pdfDocument PdfObject>.getTextFieldNames()

Returns
A list of text field names as a list of Strings.

Parameter

• pdfDocument - The PDF document object

Example

stepdef "Get PDF field names"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    println(pdfDocument.getText())
    for fieldIndex, field in pdfDocument.getTextFieldNames()
        println(field)
    end

    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()  
end

Set Text Field Values

This method does one of the following:

• Sets the text field values in the depth-first-search (DFS) order of fields, as structured in the AcroForm

• Changes the value's field, as specified by its name

Syntax

// Sets the text field values
<pdfDocument PdfObject>.setTextFieldValues(<values List<String>)
// Changes the value's field
<pdfDocument PdfObject>.setTextFieldValue(<fieldName String>, <fieldValue String> )

Parameters

• pdfDocument - The PDF document object

• values - The list of text field values

• fieldName - The name of the text field whose value will be changed

• fieldValue - The value of fieldName to be set

Examaple

stepdef "Set text field values"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.setTextFieldValues(["Firstname", "Lastname", "Address"])
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Get Text Field Value

Retrieves the text field's current value, as specified by the given name.

Syntax

<textFieldValue String> := <pdfDocument PdfObject>.getTextFieldValue(<fieldName String>)

Returns
The text field value as String.

Parameters

• pdfDocument - The PDF document object

• fieldName - The name of the field value to retrieve

Example

stepdef "Get text field value"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.getTextFieldValue(["Firstname", "Lastname", "Address"])
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Choice Fields

Choice field methods retrieve and set text within choice fields.

Get Choice Field Value

Retrieves the current value as a list of the selected values, as specified by the choice field name.

Syntax

<pdfDocument PdfObject>.getChoiceFieldValue(<fieldName String>)

Parameters

• pdfDocument - The PDF document object

• fieldName - The name of the choice field to retrieve selected values from

Example

stepdef "Get choice field value"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    println(pdfDocument.getChoiceFieldValue("Firstname"))
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Get Choice Field Names

Retrieves the choice field names from the AcroForm as a list of Strings.

Syntax

<choiceFieldNames List<String>> := <pdfDocument PdfObject>.getChoiceFieldNames()

Returns
The list of choice field name as a list of Strings.

Parameter

• pdfDocument - The PDF document object

Example

stepdef "Get choice field names"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
      for fieldIndex, field in pdfDocument.getChoiceFieldNames()
      println(field)
      end
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Get Choice Field Options

Retrieves the choice field's list of possible options, as specified by field name.

Syntax

<fieldOptions <List<String>> := <pdfDocument PdfObject>.getChoiceFieldOptions(<fieldName String>)

Returns
The list of choice field options as a list of Strings.

Parameters

• pdfDocument - The PDF document object

• fieldName - The name of the choice field to retrieve possible options from

Example

stepdef "Get choice field options"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.getChoiceFieldOptions("Firstname")
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Set Choice Field Value (By Name)

Changes the choice field's value or list of values as specified by the name(s).

Syntax

// Sets a single choice field value
<pdfDocument PdfObject>.setChoiceFieldValue(<fieldName String>, <fieldValue String>)
// Sets a list of choice field values
<pdfDocument PdfObject>.setChoiceFieldValue(<fieldName String>, <fieldValues List<String>>)

Parameters

• pdfDocument - The PDF document object

• fieldName - The list of choice field names whose values will be changed

• fieldValue (For setting a single choice field value) - The value to set for fieldName

• fieldValues (For setting a list of choice field values) - The list of values to set for the fieldName

Example

stepdef "Set choice field value"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.setChoiceFieldValue("listbox", "Item 1")
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Set Choice Field Values (in DFS Order)

Changes the choice field's values in the DFS order of fields, as structured in the AcroForm.

Syntax

<pdfDocument PdfObject>.setChoiceFieldValues(<values List<String>>)

Parameters

• pdfDocument - The PDF document object

• values - The list of values to change

Example

stepdef "Set choice field values"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.setChoiceFieldValues(["Firstname", "Lastname", "Address"])
    pdfDocument.save("/Users/user/Documents/filled.pdf")
    pdfDocument.close()
end

Checkboxes

The checkbox methods retrieve checkbox names, set their values, and can check, uncheck or confirm the state of the checkbox.

Get Checkbox Names

Retrieves the checkbox names form the AcroForm as a list of Strings.

Syntax

<checkboxNames List<String>> := <pdfDocument PdfObject>.getCheckboxNames()

Returns
The list of checkbox names as a list of Strings.

Parameter

• pdfDocument - The PDF document object

Example

stepdef "Get checkbox names"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    println(pdfDocument.getCheckboxNames())
    pdfDocument.save()
    pdfDocument.close()
end

Set Checkbox Values

Changes the checkbox's values in the DFS order of checkboxes, as structured in the AcroForm.

Syntax

<pdfDocument PdfObject>.setCheckboxValues(<values List<Boolean>>)

Parameters

• pdfDocument - The PDF document object

• values - The list of values in DSF order to set

Example

stepdef "Get checkbox names"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.setCheckboxValues([true, false, true])
    pdfDocument.save()
    pdfDocument.close()
end

Check Checkbox

Checks the specified checkbox.

Syntax

<pdfDocument PdfObject>.check(<fieldName String>)

Parameters

• pdfDocument - The PDF document object

• fieldName - The name of the checkbox to check

Example

stepdef "Check checkbox"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.check("Firstname")
    pdfDocument.save()
    pdfDocument.close()
end

Uncheck Checkbox

Unchecks the specified checkbox.

Syntax

<pdfDocument PdfObject>.uncheck(<fieldName String>)

Parameters

• pdfDocument - The PDF document object

• fieldName - The name of the checkbox to uncheck

Example

stepdef "Uncheck checkbox"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.uncheck("Firstname")
    pdfDocument.save()
    pdfDocument.close()
end

Is Checked

Retrieves the specified checkbox's boolean value, based on the checkbox's current state.

Syntax

<isChecked Boolean> := <pdfDocument PdfObject>.isChecked(<fieldName String>)

Returns
true if the checkbox is checked, false otherwise.

Parameters

• pdfDocument - The PDF document object

• fieldName - The field name whose value based on the checkbox's state to retrieve

Example

stepdef "Check checkbox is checked"
    pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
    pdfDocument.isChecked("Firstname")
    pdfDocument.save()
    pdfDocument.close()
end

PDF Text Writer

The PDF text writer function enters text into a PDF. Characteristics about the text such as font, font size and color can then be specified.

Get Text Writer

Creates the text writer instance by specifying the PDF page on which text will be entered on the specified page.

Syntax

<textWriter TextWriter> := <pdfDocument PdfDocument>.getTextWriter(<pageNumber Number>)

Returns
A TextWriter instance.

Parameters

• pdfDocument - The PDF document object

• pageNumber - The page number

  • Counting starts from 0

Example

stepdef
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  textWriter := pdfDocument.getTextWriter(2)
end

Close Text Writer

Closes the text writer instance.

Syntax

<textWriter TextWriter>.close()

Parameter

• textWriter - The text writer instance

Example

stepdef "create and close text writer"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
end

Set Font

Sets the font for the PDF. Fonts may be one of: May be one of: Courier, Courier-Bold Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Symbol, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic or ZapfDingbats

Syntax

<textWriter TextWriter>.setFont(<font String>, <fontSize Number>)

Parameters

• textWriter - The text writer instance

• font - The font being set

• fontSize (Optional) - The font size to apply to font

Example

stepdef "get PDF font"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setFont("Helvetica", 16)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
end

Set Font Color

Sets the font color.

Syntax

<textWriter TextWriter>.setColor(<red Number>, <green Number>, <blue Number>, <alpha Number>)

Parameters

• textWriter - The text writer instance

• red - The red channel number

  • Must be between 0 and 255

• blue - The blue channel number

  • Must be between 0 and 255

• green - The red channel number

  • Must be between 0 and 255

• alpha (Optional) - Adjusts the font color's opacity

  • Can range from 0 to 255

Example

stepdef "Set font color "
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setColor(0, 0, 0) // black
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

Set Position

Moves the text input position to the specified coordinates. Moves the next text to the specified coordinates.

Syntax

<textWriter TextWriter>.setPosition(<xCoordinate Number>, <yCoordinate Number>)

Parameters

• textWriter - The text writer instance

• xCoordinate - The text input position for the specified X-coordinates

• yCoordinate - The text input position for the specified Y-coordinates

Example

stepdef "Set text position "
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .setPosition(100, 200)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

New Line at Offset

Offsets the text input position to the specified coordinates.

Syntax

<textWriter TextWriter>.newLineAtOffset(<xDeltaCoordinate Number>, <yDeltaCoordinate Number>)

Parameters

• textWriter - The text writer instance

• xDeltaCoordinate - The shifted text position for the specified X-coordinates

• yDeltaCoordinate - The shifted text position for the specified Y-coordinates

Example

stepdef "shift text "
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .newLineAtOffset(100, 200)
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end

Add Text

Adds text to the PDF.

Syntax

<textWriter TextWriter>.addText(<text String>)

Parameters

• textWriter - The text writer instance

• addText - The text to add

Example

stepdef "Add text"
  pdfDocument := Common.getPdfDocument("/Users/user/Documents/simple.pdf")
  pdfDocument.getTextWriter(0)
             .addText("John")
             .moveTextPositionByAmount(0, -20)
             .addText("Doe")
             .close()
  pdfDocument.save("/Users/user/Documents/filled.pdf")
  pdfDocument.close()
end