Submit and save PDF forms to an external destination

Form submission is an action performed on a form element in a PDF document that will let you save forms to an external destination. It’s usually triggered by a submit button, and it’s a method of taking user input from the form described in the PDF and sending it as data to a given location. This data can be all the form fields in the form or just a subset of them.

For more details about PDF actions, see our related guide.

Submission method

It’s possible to handle the click of a form submit button in Nutrient to implement your own submission provider. This is done with the addDocumentActionListener provided in PdfFragment. The following example shows how it’s possible to filter for a specific action. SubmitFormAction can provide the form fields, the URI, and the form flags given by the PDF document:

pdfFragment.addDocumentActionListener { action ->
    if (action.type == ActionType.SUBMIT_FORM) {
        val submitFormAction = action as SubmitFormAction
        // Do something here.
        ...

        // Return `true` to show the action has been handled.
        return@addDocumentActionListener true
    }
    return@addDocumentActionListener 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 a variety of formats for form submission. The format that should be used is provided by flags defined on SubmitFormAction.

FDF

The Forms Data Format (FDF) is the default format for form submission, and it’s described as a subset of PDF. The structure of FDF is essentially the same as that of a PDF document, but with only the form elements present. This format can be used to import data back into a PDF at a later date. Adobe also provides the Acrobat SDK, which can be used to parse the FDF format on the server side or elsewhere.

The following shows an example of the FDF format. filePath will reflect the path where the file was sent from. Here you can also see Fields with the given key and value, TextField1 and TestText, respectively:

%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

The HTML format can be chosen to create a GET or POST request to supply to a particular server. The form fields will be converted to key-value pairs, with the name being the ID of the form field and the value being the user input. This format adheres to the HTML 4.01 Specification.

The body of the HTML request will hold the values sent from the form. The following shows how two form fields will be generated — note that it’s delimited by an ampersand. This can be parsed by most web server technologies with little work:

TextField1=TestText&TextField2=TestText2

XFDF

XFDF is similar to the FDF, but it’s represented by an XML-based format. This is a standard provided by Adobe and is therefore supported by Adobe Acrobat and various other third-party products. See our XFDF guide for more details.

XFDF will output a file with XML notation. It’ll hold a collection of fields, each of which can have a collection of values. Here you can see that the form field TextField1 has a value element of 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

It’s also possible to submit an entire PDF document. This option is useful when the recipient has no reference to the original document. As the entire PDF is being transmitted with this format, it’s a highly wasteful process, especially with complex and large documents.