pdf-forms

Description

Fill out PDF forms with pdftk.

Installation

You'll need a working pdftk binary. Either get a binary package from http://www.pdflabs.com/tools/pdftk-server/ and install it, or run apt-get install pdftk if you're on Debian or similar.

After that, add pdf-forms to your Gemfile or manually install the gem. Nothing unusual here.

Usage

FDF/XFdf creation

require 'pdf_forms'
fdf = PdfForms::Fdf.new :key => 'value', :other_key => 'other value'
# use to_pdf_data if you just want the fdf data, without writing it to a file
puts fdf.to_pdf_data
# write fdf file
fdf.save_to 'path/to/file.fdf'

To generate XFDF instead of FDF instantiate PdfForms::XFdf instead of PdfForms::Fdf

Query form fields and fill out PDF forms with pdftk

require 'pdf_forms'

# adjust the pdftk path to suit your pdftk installation
# add :data_format => 'XFdf' option to generate XFDF instead of FDF when
# filling a form (XFDF is supposed to have better support for non-western
# encodings)
# add :utf8_fields => true in order to get UTF8 encoded field metadata (this
# will use dump_data_fields_utf8 instead of dump_data_fields in the call to
# pdftk)
pdftk = PdfForms.new('/usr/local/bin/pdftk')

# find out the field names that are present in form.pdf
pdftk.get_field_names 'path/to/form.pdf'

# take form.pdf, set the 'foo' field to 'bar' and save the document to myform.pdf
pdftk.fill_form '/path/to/form.pdf', 'myform.pdf', :foo => 'bar'

# optionally, add the :flatten option to prevent editing of a filled out form
pdftk.fill_form '/path/to/form.pdf', 'myform.pdf', {:foo => 'bar'}, :flatten => true

# to enable PDF encryption, pass encrypt: true. By default, a random 'owner
# password' will be used, but you can also set one with the :encrypt_pw option.
pdftk.fill_form '/path/to/form.pdf', 'myform.pdf', {foo: 'bar'}, encrypt: true, encrypt_options: 'allow printing'

# you can also protect the PDF even from opening by specifying an additional user_pw option:
pdftk.fill_form '/path/to/form.pdf', 'myform.pdf', {foo: 'bar'}, encrypt: true, encrypt_options: 'user_pw secret'

Any options shown above can also be set when initializing the PdfForms instance. In this case, options given to fill_form will override the global options.

FAQ

Umlauts / accented characters do not show up in form fields of the resulting document

First of all, make sure your data (what you fill into the form fields) is valid UTF-8.

Usually this is just a font problem (embedded fonts in your PDF form do not contain those characters). Please run pdftk your_filled_out_form.pdf dump_data_fields_utf8 and check the FieldValue of the fields where you think characters are missing.

If they show up here, this gem and PDFTK worked correctly (as the value is stored in the PDF) and it's just a problem with your PDF document. Go back to Acrobat and fix it (i.e. by embedding complete fonts / turning off optimizations that only embed the subset of characters that's actually used). If the characters indeed aren't there in the dump_data_fields_output, please open an issue and post a form and code snippet for me to reproduce. Email me your form and code snippet if it's somewhat confidential.

Prior Art

The FDF generation part is a straight port of Steffen Schwigon's PDF::FDF::Simple perl module. Didn't port the FDF parsing, though ;-)

License

Created by Jens Kraemer and licensed under the MIT License.

rustoceans / pdf-forms