Submit and save PDF forms to an external destination

Form submission sends user input from PDF form fields to an external destination. A submit button usually triggers this action. A submission can include all fields or a subset.

For field types, refer to the form fields guide. For action details, refer to the PDF actions guide.

Submission method

To implement custom submission, register an action listener with PdfFragment using addDocumentActionListener. Filter for submission actions in the listener.

SubmitFormAction provides the document’s form fields, destination URI, and submission flags. The following example handles a submission action:

pdfFragment.addDocumentActionListener(object : DocumentActionListener {
    override fun onExecuteAction(action: Action): Boolean {
        if (action.type == ActionType.SUBMIT_FORM) {
            val submitFormAction = action as SubmitFormAction
            // Do something here.

            // Return `true` to show the action has been handled.
            return true
        }
        return false
    }
})

pdfFragment.addDocumentActionListener(action -> {
    if (action.getType() == ActionType.SUBMIT_FORM) {
        SubmitFormAction submitFormAction = (SubmitFormAction) action;
        // Do something here.

        // Return `true` to show the action has been handled.
        return true;
    }
    return false;
});

Format

The PDF specification defines several submission formats. Flags on SubmitFormAction specify the format.

FDF

Forms Data Format (FDF) is the default submission format. FDF uses a subset of the PDF structure containing only form elements. Use FDF to import form data back into a PDF later. Adobe’s Acrobat SDK(opens in a new tab) can parse FDF on a server or in other environments.

In the following example, filePath identifies the source file’s path. The Fields entry contains the key TextField1 and the value TestText:

%FDF-1.2
1 0 obj
<<
  /FDF <<
    /F <<
      /F(${filePath})/Type/Filespec/UF(${filePath})
    >>
    /Fields [<</T(TextField1)/V(TestText)>>]
  >>
>>
endobj

trailer
<</Root 1 0 R>>
%%EOF

HTML

Use HTML format to send a GET or POST request to a server. This format represents fields as key-value pairs: Each key identifies a field, and each value contains the user’s input. The format follows the HTML 4.01 specification(opens in a new tab).

The following example encodes two fields with an ampersand separator. Most web servers can parse this format:

TextField1=TestText&TextField2=TestText2

XFDF

XFDF is Adobe’s XML-based format for form data. Adobe Acrobat and other third-party products support it. For details, refer to the XFDF guide.

An XFDF file contains fields, each with one or more values. In this example, TextField1 contains the value TestText:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xml:space="preserve" xmlns="http://ns.adobe.com/xfdf/">
  <fields>
    <field name="TextField1">
      <value>TestText</value>
    </field>
  </fields>
</xfdf>

PDF

Submit the entire PDF when the recipient doesn’t have the original document. This format transfers the whole document rather than only field data, increasing transfer size for large or complex PDFs.