Form Submission

Form submission is an action performed on a form element from a PDF document, usually triggered by a submit button. It is 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 these.

See our PDF Actions guide for more details about PDF actions.

Submission Method

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

Copy
1
2
3
4
5
6
7
8
9
10
11
12
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
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pdfFragment.addDocumentActionListener(new DocumentActionListener() {
    @Override
    public boolean onExecuteAction(@NonNull Action 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

It is possible to send the data in a variety of formats to allow the recipient parse the data in a known format. This format is provided by the action flags within the PDF document.

These flags can be found in SubmitFormAction and the format should be chosen based on this information.

FDF

This is the default format for form submission, which is described as a subset of PDF. The structure of FDF is essentially the same as a PDF document, although only the form elements are present. This format can be used to import the data back into the PDF at a later date. Adobe also provides a FDF Toolkit which can be used to parse the FDF format on the server side or else where.

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.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
%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 abides by the HTML 4.01 Specification.

The body of the html request will hold the values sent from the form. The following shows how 2 form fields will be generated, not that it is delimited by an ampersand. This can be parsed by most web server technologies with little work.

1
TextField1=TestText&TextField2=TestText2
XFDF

XFDF is similar to the FDF, but is represented in XML-like format. This is a standard is provided by Adobe and therefore supported by Adobe Acrobat and various other 3rd-party products. See our XFDF Overview guide for more details.

XFDF will output a file with xml notation. It will hold a collection of fields each of which can have a collection of values. Here you can see the form field TextField1 has a value element of TestText

Copy
1
2
3
4
5
6
7
8
<?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 is also possible to submit the whole PDF document. This option is useful when the recipient has no reference to the original document. As the whole PDF is being transmitted with this format, it is a highly wasteful process, especially with complex and large documents.