PDF Ravager

JRuby-only DSL for filling out AcroForms PDF or XFA documents.

This library uses a combination of a simple DSL and a minimal façade over a pre-AGPL version of the Java iText library to aid in filling out AcroForms PDF or XFA documents.

require 'pdf_ravager'

data = { name: 'Bob', gender: 'm', relation: 'Uncle' }

template = PDFRavager::Template.new do |p|
  p.text      'name', data[:name]
  p.rich_text 'name_stylized', "<b>#{data[:name]}</b>"
  p.radio_group 'sex' do |rg|
    rg.fill 'male'   if data[:gender] == 'm'
    rg.fill 'female' if data[:gender] == 'f'
  end
  p.check 'related' if data[:relation]
  p.checkbox_group 'relation' do |cg|
    case data[:relation]
    when 'Mom', 'Dad'
      cg.check 'parent'
    when 'Brother', 'Sister'
      cg.check 'sibling'
    else
      cg.check 'other'
    end
  end
end

template.ravage '/tmp/info.pdf', out_file: '/tmp/info_filled.pdf'
# if you'd like the populated form to be read-only:
template.ravage '/tmp/info.pdf', out_file: '/tmp/info_filled.pdf', read_only: true

Although not recommended due to the pollution of the global namespace, in the interest of brevity you can introduce a shorthand pdf method that is equivalent to PDFRavager::Template.new by requiring pdf_ravager/kernel instead of pdf_ravager:

require 'pdf_ravager/kernel'

data = {name: 'Bob', gender: 'm', relation: 'Uncle' }

template = pdf do |p|
  p.text 'name', data[:name]
  # ...
end

Note: pdf has been deprecated and will be removed in a future release.

By default, PDF Ravager uses a :smart strategy for populating PDFs which first attempts to fill fields using the :acro_forms strategy, then applies the :xfa strategy to fields that were unable to be populated with :acro_forms. If you know which strategy you want ahead of time (e.g. your form is strictly a static AcroForm or a dynamic XFA), you can set it in the template initializer like so:

template = PDFRavager::Template.new(strategy: :xfa) do |p|
  # ...
end

Valid options are:

• :smart
• :acro_forms
• :xfa

To query and modify a form's field names, use a tool such as Adobe LiveCycle.

Rich text is specific to XFA forms. To understand how it should be used, see the "Rich Text Reference" section of Adobe's XFA standard. Rich Text is defined there as a subset of XHTML and CSS which uses some custom restrictions and extensions by Adobe. The minimum XHTML and CSS elements that a standards-compliant XFA processor (e.g. Adobe Reader) must support are also listed there and can be used as a guide.

Note: Rich text values are not HTML-escaped or sanitized in any way. It is suggested that you call CGI.escape_html on user-supplied input.

Because there is no such thing as a "checkbox group," the checkbox_group syntax is simply syntactic sugar for calling check with the group name and a . prepended to the name. For example,

pdf do |p|
  p.checkbox_group 'relation' do |cg|
    cg.check 'parent'
  end
end

is equivalent to

pdf do |p|
  p.check 'relation.parent'
end

Copyright (c) 2012-2016 Abe Voelker. Released under the terms of the MIT license. See LICENSE for details.

The version of iText vendored is licensed under the LGPL. Note that this version of iText was never officially released by iText Software, but is a custom build provided by Yuvi Masory (kind thanks to them for that).