html2ps/html2pdf interactive forms

# html2ps/pdf interactive forms

Back to table of contents

## Difference between forms in HTML and PDF

I guess, if you use html2ps script, then you know how forms are defined in HTML and how form data is sent using the POST format. This script tries to emulate the browser behavior as closely as possible; nevertheless, there's several important differences.

### Field names are required

In HMTL, you may write an INPUT tag without "name" attribute and get working interactive control; often, submit and reset buttons are written this way. When using html2ps interactive forms, you must provide "name" attribute for all controls which should be rendered interactive. If you don't do it, the control will be rendered as a graphic like "Interactive forms" options disabled.

### Field names should be unique

In HTML you usually may enter several controls with the same name into the same form and get some kind of results. PDF files do not allow such fields at all. In this case, all subsequent fields sharing the same name will be rendered as non-interactive.

### Form & field names

Unlike HTML, the parameter names in POST request are not the field names. Acrobat Reader uses a "fully qualified field names" instead. It means that field is identified by composite string having the form

    <form name>.<field name>

(See also PDF Reference 1.6 Fifth Edition, pp.638–639 for more precise and detailed explanation). When posting data in POST format, dots are converted to underscores, so you would get:

    <form name>_<field name>

when processing the POSTed data.

To illustrate what I've said above, consider the following example:

    <form name="form1">
    <input type="text" name="item1" value="test"/>
    <input type="submit" name="submit" value="Submit 1st form"/>
    </form>

    <form name="form2">
    <input type="text" name="item2" value="test"/>
    <input type="submit" name="submit" value="Submit 2nd form"/>
    </form>

Usually you would get POST variables "item1" and "submit" when submitting the 1st form and "item2" and "submit" when submitting the 2nd form. When submitting the form from PDF, you'll get "form1_item1", "form1_submit" and "form2_item2", "form2_submit" correspondingly.

The name of the form is taken from "name" or "id" FORM tag attributes (note that if both attributes are specified, then "name" have the higher priority). If both these attributes are missing, then the script attemts to generate an unique name for the form; Newertheless, it is highly recommended to add "id" or "name" attributes for every form definition. The autogenerated form names may suddenly change when you change the page content. It is not guaranteed that future html2ps versions will use the same name generation rules.

Also, you must note that html2ps is less tolerant to the form definition than most browsers. You may get conversion errors or even unpredictable results when viewing generated PDF if the following conditions are not satisfied:

- Form names are unique throughout the page
- Field names are unique in the form
- Radio button values are unique inside the button group

### Button field values

In HTML, when you click on the Submit button, the posted data will include the value of "value" attribute for the button. When you're submitting form from generated PDF, you'll get an empty string as a value of this parameter. Thus, this check is a bad idea (bad, but rather popular):

    …
    if ($_POST['my_submit_button_name']) {
    …

and should be replaced by this code:

    …
    if (isset($_POST['my_submit_button_name'])) {
    …

### Image submit button click coordinates

In HTML forms, you'll get three POST varaibles after clicking on "image" submit button: <button>, <button>_x and <button>_y. When you're posting data from PDF you'll get only two last parameters!

### Unsupported field types

"file;" and "hidden" fields are not supported.

## Server-side form handling

Note: there's an PHP extension designed to work with FDF files; you may wish to check documentation at PHP.net: Forms Data Format Functions

Basically, you must use the script which accepts data in HTTP POST format and outputs result in FDF format. (Actually, in any format, but be prepared to Acrobat Reader complaints like "Cannot handle Content-Type: …") The minimal data-handling example is:

    // output an empty FPF file

    $outfdf  = fdf_create();
    $tmpname = tempnam('../temp',"FDF_");
    fdf_set_status($outfdf, "Thank you!");
    fdf_save($outfdf, $tmpname);
    fdf_close($outfdf);

    fdf_header();
    $fp = fopen($tmpname, "r");
    fpassthru($fp);
    unlink($tmpname);

It just confirms the receiving of the posted data; "Thank you!" message will be shown as a popup by Acrobat Reader. Probably you would want to actually do something with POSTed data, but is it far beyound the area of this manual.

## Compatibility list

Element | Is supported? | Notes
--- | --- | ---
Text field (<input type="text">) | Yes |
Password field (<input type="password">) | Yes |
Submit button (<input type="submit">) | Yes | Value of button "value" attribute is not posted
Reset button (<input type="reset">) | Yes |
Plain button (<input type="button">) | Yes | Renders and you may click on them, but there's no much use of buttons, as Javascript is NOT supported
Checkbox (<input type="checkbox">) | Yes |
Radio (<input type="radio">) | Yes |
Textarea (<textarea>) | Yes |
Select (<select>) | Yes |
Image (<input type="image">) | Yes |
File (<input type="file">) | No |
Hidden (<input type="hidden">) | No |