Add support for fillable form elements (basic features)

[ngns]

This issues is extended with "basic features", as more advanced features and elements (like drop-downs or definition of text content types) are covered in a separate issue

As in the current flying saucer version, input elements should not only be rendered, but also be created as AcroForm elements in the resulting PDF (note that the implementation in flying saucer has some limitations though - e.g. radioboxes are not yet implemented, and css styles are a bit quirky still). In a first implementation, the following elements should be considered:

• HTML <input type="text" name="..." value="..."> : a text form field should be rendered, one line only. If a value is provided in the value attribute, it should be pre-filled with that value. The name attribute should be taken as value for the "name" property of the form field.
• HTML <textarea name="..." value="..."> : a multi-line text form field should be rendered. The hight of the form field should be created based on the css style. If no "height" style can be determined from the css, then it should be calculated based on the rows attribute value, multiplied by the line hight and paddings / line spacings. If the <textarea> element has a node child, the form field should be pre-filled with the text content of that child node. The name attribute should be taken as value for the "name" property of the form field.
• HTML <input type="radio" name="..." value="..." checked="true"> : a radio form field should be rendered. The value from the _id attribute should be taken as group-id for the radio boxes. The "name" property of the form field should be composed out of the name attribute, extended by a "." and the running number of the element within the group (e.g. if the name is "mysection.myoptions" then the form element name of the first radio button with this name will be "mysection.myoptions.1"). The "option" value of the form element is to be taken directly from the value attribute of the <input> element. The option should be selected by default, if the checked attribute in the <input> element is set respectively.
• HTML <input type="checkbox" name="..." value="..."> : a checkbox form field should be created. The name attribute should be taken as value for the "name" property of the form field. The form field value should be taken over from the value property of the <input> element. The checkbox should be checked by default, if the checked attribute in the <input> element is set respectively.

For all the above elements, basic styling for borders (width, color), background-color, inner padding to content and font settings should be applied (for checkboxes and radio buttons, the dot/check sign is rendered in the font-color - so even there it does count)

[ngns]

In order to provide some "easier" styling of the radio and checkbox elements in the pdf (there are some "flat" and "3d" defaults), special css styles may be considered. E.g.: --pdfbox-form-style: embossed; or --pdfbox-form-style: flat;. Community or maintainer feedback on this suggestions is appreciated :-) !

[scoldwell]

@danfickle do you have a time frame in which this will be implemented? Also I see you tagged the issue with pdfbox-work-needed. Is there a pdfbox jira issue I can keep track of regarding this work?

[danfickle]

In the pdf specification form fields can have an explicit appearance or a flag to tell the viewer to generate its own appearance. Ideally we would want to generate our own appearance in line with css. Unfortunately pdf box does not yet have a way to draw to appearance streams. However, work is advanced and is covered by pdf box 3353

I was planning on waiting until this landed before working on this issue but if you can handle a viewer specified appearance I can start on this issue.

Also see http://www.debenu.com/kb/appearance-streams-pdf-form-fields/ @scoldwell

[scoldwell]

Just so I understand, is it currently not possible to have this html:

<input type="text" name="fieldname" />

Translate into something like this?

http://svn.apache.org/viewvc/pdfbox/tags/2.0.2/examples/src/main/java/org/apache/pdfbox/examples/interactive/form/CreateSimpleForm.java?view=markup

[danfickle]

Yes, I remembered it as more complicated than it is. Thanks for finding an example.

[danfickle]

We can't use custom fonts in text fields until complete font embedding is fixed in PDF-BOX.

[danfickle]

OK, support for text fields (text, textarea, password) and submit inputs or buttons has landed.

Limitations:

• Viewers don't support a text encoding when uploading
• Can't use custom font in text controls because of PDF-BOX bug mentioned above.

Attributes supported:

• name (export name when sending to form)
• value (excluding textarea, default value)
• title (accessible name)
• readonly
• required
• max-length
• rows (textarea only)
• cols (textarea only)

Styles supported:

• Background and border is renderer as usual so can use any available styles such as border-color, background-color, etc.
• The only styles that can be set on the text are font (use a built-in for now) and color.

Examples:

<html>
<head>
<style>
input { color: orange; font-family: monospace; }
textarea { color: red; font-family: monospace;  }
button { color: blue; font-family: monospace; border-radius: 8px; background-color: yellow; }
</style>
</head>
<body>
<div>
<form action="http://localhost/form.php" method="POST">
 <input type="text" value="One" name="test1"   readonly="" title="Hello there!"/>
 <input type="text" value="Two" name="test2" max-length="4" />
 <input type="text" value="Three" name="test3" required=""/>
  <input type="text" value="Four" name="test4"/>
 <div><textarea name="text-area-test" rows="30" cols="50">This is a test!</textarea></div> 
 <input type="submit" value="GO!"/>
 <button type="submit">SUBMIT</button>
 <input type="password" name="notvery" value="secret"/>
</form>
</div>
</body>
</html>

Results in:

Note that Acrobat masks the password field, Mac Preview does not. Also note, that you can have multiple forms in a document and it will behave correctly.

And when submitted with Acrobat sends this to the server: test1=One&test2=Two&test3=Three&test4=Four&text-area-test=This+is+a+test%21&notvery=secret

Next up: Select fields.

[danfickle]

OK, select (without the multiple attribute) and reset controls are implemented. After implementing multiple select, I'll work on checkboxes and radio boxes. Does anyone have a strong opinion on how these should look? Should we break the browser standard and use the text color and font size for icons? Or should we just copy the (unchangeable via CSS) styling of Chrome?

Any feedback welcome.

[ngns]

Checkboxes and Radiobutton groups are kind of a b**ch in the Acrobat format. There is not a consistent and proper way of designing these:

• PDF itself knows some kind of simplified way of choosing from pre-defined styles. They allow to select the type of the tick box itself (check, cross, diamond, circle, star, square), its height & width, the background color, and the frame width (0=none, 1=thin, 2=medium, 3=thick)
• When designing form e.g. in InDesign, it is possible to add specific icons for the checked and unchecked states. These kind of "overlay" the native PDF ones. However, when ever one tries to do any modification or scripting within Adobe Acrobat (or PDFBox), these icons get entirely messed up

For sake of a balanced compromise between flexibility, compatibility and implementation effort I would opt for sticking to what Adobe Acrobat allows natively (The "static" Chrome-way is not at all usable if you want at least some possibility to make your PDF look nice or stick to some company's CI/CD). We may need to introduce some custom CSS styles, though (e.g. something like --pdf-checkbox-type: cross; --pdf-checkbox-background:#CCC; -- pdf-checkbox-border: thin;), in combination with the standard tags for width and height

What do you think?

[danfickle]

Thanks for the info. It really helped as none of this is mentioned in the PDF specification. As you say, checkboxes seem to be more than a bit of a mess. Here is what I've learned:

• Mac Preview always shows both the appearance in the PDF as well as its own check mark over the top.
• Acrobat shows an icon which apparent depends on the caption (/CA) entry of the appearance characteristics (/MK) dictionary associated with a checkbox widget annotation. According to the first link this is an index into the Zapf Dingbats font.
• Other viewers or the same viewers with different settings probably have different behavior.
• There are several cross icons, checks, etc in the Zapf font.

In conclusion, I think we need to implement both a caption (for acrobat) and an appearance stream in the PDF to be safe. Since there are many similar icons in zapf dingbats I need to know the exact indices of icons, which brings we to my plea:

@ngns - Would you be generous enough to upload a PDF here (drag it on to the comment box to upload) with all the styles you want supported? Alternatively, you could examine it with a text editor and post all the /CA entries.

A /CA entry will look something like with the number in the bracket being what we need:

<< /CA (0) >>

Thanks again.

http://stackoverflow.com/questions/15479855/pdf-appearance-streams-checkbox-not-shown-correctly-after-focus-lost http://developers.itextpdf.com/question/why-does-itext-enter-cross-symbol-when-checktype-style-check-mark

[danfickle]

<html>
<head></head>
<body>
<form method="post" action="http://localhost/form.php">
 <div>
 <input type="checkbox" name="checker" value="1" checked="" style="-fs-checkbox-style: check;" />
 <input type="checkbox" name="checker" value="2" checked="" style="-fs-checkbox-style: square;" />
 <input type="checkbox" name="checker" value="3" checked="" style="-fs-checkbox-style: diamond;" />
 <input type="checkbox" name="checker" value="4" checked="" style="-fs-checkbox-style: star;" />
 <input type="checkbox" name="checker" value="5" checked="" style="-fs-checkbox-style: circle;" />
 <input type="checkbox" name="checker" value="6" checked="" style="-fs-checkbox-style: cross;" />
</div>
</form>
</body>
</html>

will now produce: However, due to PDF-BOX 3298 I had to upgrade to PDF-BOX 2.0.3-SNAPSHOT to get checkbox styles working. So we'll have to wait for a PDF-BOX release before releasing ourselves. Custom fonts for text controls are also working with 2.0.3.

Next up are radio buttons and hidden inputs.

[scoldwell]

@danfickle Pdfbox 2.0.3 has been released now

[danfickle]

@scoldwell - Thanks for the notification, about to upgrade to 2.0.3 and do a release now.

I just landed radio controls after a frustrating couple of weeks trying to track down a bug that I now think is in Acrobat Reader rather than my code.

If you have:

 <input type="radio" name="rad" value="one"/>
 <input type="radio" name="rad" value="two"/>
 <input type="radio" name="rad" value="three"/>
 <input type="radio" name="rad" value="four"/>

The first two when submitted will have the correct value such as rad=one. However, after that three and four will return the zero based index such as rad=3. A workaround is to always use a zero based index for values:

 <input type="radio" name="rad" value="0"/>
 <input type="radio" name="rad" value="1"/>
 <input type="radio" name="rad" value="2"/>
 <input type="radio" name="rad" value="3"/>

Another problem is that the default value is not honored in Acrobat Reader, but it is in Mac Preview. For example, using the below markup, Acrobat will have all buttons empty.

<input type="radio" name="rad-two" value="0" checked=""/>
<input type="radio" name="rad-two" value="1"/>

The only form controls left are hidden, and they'll have to wait for the next release.

[scoldwell]

@danfickle I'm finally getting around to testing this with our templates (we were in the middle of a huge platform upgrade). I'm running into an issue with the name of the text fields in the html not being preserved in the PDF. For example:

<p><input name="signature.employee" type="text" size="200" /></p>

is coming out in the PDF as "OpenHTMLCtrl1"

Looking at the code, I see you're setting the mapping name of PDField to what's in the html, but using "OpenHTMLCtrl" + i to set the partial name. The problem with this is:

We use org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm.getField(String) to locate a field by its name, this fails because the PDField mapping name is not used for this lookup.

[scoldwell]

Opened #42 and #41 for the above problem as well as an enhancement request.

[danfickle]

Please see #42 for new restrictions on naming form controls.

I think this just about finishes form support. The only other thing we could do is add support for all the other input controls (color, date, etc) introduced in HTML5. It would be trivial to alias them as text controls, but I'm not sure fake support is the way to go.

If anyone has any suggestions please make them, otherwise I'll close this issue shortly.

Thanks.