1<html> 2<head> 3<title>html2ps/html2pdf interactive forms</title> 4<link rel="stylesheet" type="text/css" medial="all" title="Default" href="css/help.css"/> 5</head> 6<body> 7<h1>html2ps/pdf interactive forms</h1> 8<a href="index.html">Back to table of contents</a> 9 10<h2>Difference between forms in HTML and PDF</h2> 11<p>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 12tries to emulate the browser behavior as closely as possible; nevertheless, there's several important differences. 13 14<h3>Field names are required</h3> 15<p>In HMTL, you may write an INPUT tag without "name" attribute and get working interactive control; often, submit and reset buttons 16are written this way. When using html2ps interactive forms, you <strong>must</strong> provide "name" attribute for all 17controls which should be rendered interactive. If you don't do it, the control will be rendered as a graphic like "Interactive forms" options 18disabled. 19 20<h3>Field names should be unique</h3> 21<p>In HTML you usually <i>may</i> enter several controls with the same name into the same form and get 22some kind of results. PDF files do not allow such fields at all. In this case, all subsequent fields 23sharing the same name will be rendered as non-interactive. 24</p> 25 26<h3>Form & field names</h3> 27<p>Unlike HTML, the parameter names in POST request are not the field names. Acrobat Reader uses a "fully qualified field names" 28instead. It means that field is identified by composite string having the form 29<pre class="code"> 30<form name>.<field name> 31</pre> 32(See also <em>PDF Reference 1.6 Fifth Edition, pp.638–639</em> 33for more precise and detailed explanation). When posting data in POST format, dots are converted to underscores, so you would get: 34<pre class="code"> 35<form name>_<field name> 36</pre> 37when processing the POSTed data. 38</p> 39 40<p>To illustrate what I've said above, consider the following example: 41<pre class="code"> 42<form name="form1"> 43<input type="text" name="item1" value="test"/> 44<input type="submit" name="submit" value="Submit 1st form"/> 45</form> 46 47<form name="form2"> 48<input type="text" name="item2" value="test"/> 49<input type="submit" name="submit" value="Submit 2nd form"/> 50</form> 51</pre> 52Usually you would get POST variables "item1" and "submit" when submitting the 1st form and 53"item2" and "submit" when submitting the 2nd form. When submitting the form from PDF, you'll get 54"form1_item1", "form1_submit" and "form2_item2", "form2_submit" correspondingly. 55 56</p> 57 58<p>The name of the form is taken from "name" or "id" FORM tag attributes (note that if both attributes are specified, then 59"name" have the higher priority). If both these attributes are missing, then the script attemts to generate an unique name for the form; 60Newertheless, it is <strong>highly</strong> recommended to add "id" or "name" attributes for every form definition. The 61autogenerated form names may suddenly change when you change the page content. It is not guaranteed that future html2ps versions will 62use the same name generation rules.</p> 63 64<p>Also, you must note that html2ps is less tolerant to the form definition than most browsers. You may get conversion errors or even 65unpredictable results when viewing generated PDF if the following conditions are not satisfied: 66<ul> 67<li>Form names are unique throughout the page</li> 68<li>Field names are unique in the form</li> 69<li>Radio button values are unique inside the button group</li> 70</ul> 71</p> 72 73<h3>Button field values</h3> 74<p> 75In HTML, when you click on the Submit button, the posted data will include the value of "value" attribute for the button. 76When you're submitting form from generated PDF, you'll get an <strong>empty string</strong> as a value of this parameter. Thus, 77this check is a bad idea (bad, but rather popular): 78<pre class="code"> 79… 80if ($_POST['my_submit_button_name']) { 81… 82</pre> 83and should be replaced by this code: 84<pre class="code"> 85… 86if (isset($_POST['my_submit_button_name'])) { 87… 88</pre> 89</p> 90 91<h3>Image submit button click coordinates</h3> 92<p> 93In HTML forms, you'll get three POST varaibles after clicking on "image" submit button: <button>, <button>_x and <button>_y. 94When you're posting data from PDF you'll get only two last parameters! 95</p> 96 97<h3>Unsupported field types</h3> 98<p> 99"file;" and "hidden" fields are not supported. 100</p> 101 102<h2>Server-side form handling</h2> 103 104<strong>Note:</strong> there's an PHP extension designed to work with FDF files; you may wish to check documentation at 105 PHP.net: <a title="Opens in new window" target="_blank" href="http://php.net/manual/en/ref.fdf.php">Forms Data Format Functions</a> 106 107<p>Basically, you must use the script which accepts data in HTTP POST format and outputs result in FDF format. (Actually, in any format, 108but be prepared to Acrobat Reader complaints like "Cannot handle Content-Type: …") 109The minimal data-handling example is: 110<pre class="code"> 111// output an empty FPF file 112 113$outfdf = fdf_create(); 114$tmpname = tempnam('../temp',"FDF_"); 115fdf_set_status($outfdf, "Thank you!"); 116fdf_save($outfdf, $tmpname); 117fdf_close($outfdf); 118 119fdf_header(); 120$fp = fopen($tmpname, "r"); 121fpassthru($fp); 122unlink($tmpname); 123</pre> 124It just confirms the receiving of the posted data; "Thank you!" message will be shown as a popup by Acrobat Reader. 125Probably you would want to actually do something with POSTed data, but is it far beyound the area of this manual. 126 127<h2>Compatibility list</h2> 128<table> 129<thead> 130<tr class="odd"> 131<th>Element</th> 132<th>Is supported?</th> 133<th>Notes</th> 134</tr> 135</thead> 136 137<tbody> 138<tr class="even"> 139<td>Text field (<input type="text">)</td> 140<td class="yesno">Yes</td> 141<td></td> 142</tr> 143 144<tr class="odd"> 145<td>Password field (<input type="password">)</td> 146<td class="yesno">Yes</td> 147<td></td> 148</tr> 149 150<tr class="even"> 151<td>Submit button (<input type="submit">)</td> 152<td class="yesno">Yes</td> 153<td>Value of button "value" attribute is not posted</td> 154</tr> 155 156<tr class="odd"> 157<td>Reset button (<input type="reset">)</td> 158<td class="yesno">Yes</td> 159<td></td> 160</tr> 161 162<tr class="even"> 163<td>Plain button (<input type="button">)</td> 164<td class="yesno">Yes</td> 165<td>Renders and you may click on them, but there's no much use of buttons, as Javascript is NOT supported</td> 166</tr> 167 168<tr class="odd"> 169<td>Checkbox (<input type="checkbox">)</td> 170<td class="yesno">Yes</td> 171<td></td> 172</tr> 173 174<tr class="even"> 175<td>Radio (<input type="radio">)</td> 176<td class="yesno">Yes</td> 177<td></td> 178</tr> 179 180<tr class="odd"> 181<td>Textarea (<textarea>)</td> 182<td class="yesno">Yes</td> 183<td></td> 184</tr> 185 186<tr class="even"> 187<td>Select (<select>)</td> 188<td class="yesno">Yes</td> 189<td></td> 190</tr> 191 192<tr class="odd"> 193<td>Image (<input type="image">)</td> 194<td class="yesno">Yes</td> 195<td></td> 196</tr> 197 198<tr class="even"> 199<td>File (<input type="file">)</td> 200<td class="yesno">No</td> 201<td></td> 202</tr> 203 204<tr class="odd"> 205<td>Hidden (<input type="hidden">)</td> 206<td class="yesno">No</td> 207<td></td> 208</tr> 209 210</tbody> 211 212</table> 213 214</body> 215</html> 216