README.md in fillable-pdf-0.6 vs README.md in fillable-pdf-0.7
- old
+ new
@@ -1,17 +1,21 @@
# FillablePDF
[](https://rubygems.org/gems/fillable-pdf)
+[](http://travis-ci.org/plataformatec/fillable-pdf)
FillablePDF is an extremely simple and lightweight utility that bridges iText and Ruby in order to fill out fillable PDF forms or extract field values from previously filled out PDF forms.
+## Known Bugs (Rails + Passenger Phusion only)
+if you are using Rails and hosting the app with Passenger Phusion (be it standalone or as a plugin for Apache or Nginx), the Java code within this gem simply hangs without any errors and warnings. If you need to deploy your Rails application, do not use Passenger Phusion. I have tested Puma, and it works fine. Not sure about other webservers.
+
## Installation
**Ensure that your `JAVA_HOME` variable is set before installing this gem (see examples below).**
-* OSX: `/Library/Java/JavaVirtualMachines/jdk-9.0.1.jdk/Contents/Home`
+* OSX: `/Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home`
* Ubuntu/CentOS: `/usr/lib/jvm/java-1.8.0-openjdk`
Add this line to your application's Gemfile:
gem 'fillable-pdf'
@@ -39,11 +43,11 @@
```
An instance of `FillablePDF` has the following methods at its disposal:
```ruby
-# return true if the form has any fillable fields
+fillable-pdf
# output example: true
pdf.any_fields?
```
```ruby
@@ -53,34 +57,30 @@
```
```ruby
# retrieve a single field value by field name
# output example: 'Richard'
-pdf.get_field(:full_name)
+pdf.field(:full_name)
```
```ruby
-# retrieve a numeric field type by field value
+# retrieve a field type by field name
# numeric types should
# output example: 4
-pdf.get_field_type(:football)
+pdf.field_type(:football)
# list of all field types
-Field::CHECKBOX
-Field::COMBO
-Field::LIST
-Field::NONE
-Field::PUSHBUTTON
-Field::RADIOBUTTON
+Field::BUTTON
+Field::CHOICE
Field::SIGNATURE
Field::TEXT
```
```ruby
# retrieve a hash of field name and values
# output example: {:last_name=>"Rahl", :first_name=>"Richard"}
-pdf.get_fields
+pdf.fields
```
```ruby
# set the value of a single field by field name
# result: changes the value of 'first_name' to 'Richard'
@@ -93,12 +93,12 @@
pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
```
```ruby
# rename field (i.e. change the name of the field)
-# this action also moves the field to the end of the hash
# result: renames field name 'last_name' to 'surname'
+# NOTE: this action does not take effect until the document is saved
pdf.rename_field(:last_name, :surname)
```
```ruby
# remove field (i.e. delete field and its value)
@@ -107,11 +107,11 @@
```
```ruby
# get an array of all field names in the document
# output example: [:first_name, :last_name]
-pdf.keys
+pdf.names
```
```ruby
# get an array of all field values in the document
# output example: ["Rahl", "Richard"]
@@ -120,28 +120,29 @@
Once the PDF is filled out you can either overwrite it or save it as another file:
```ruby
pdf.save
-
pdf.save_as('output.pdf')
```
Or if you prefer to flatten the file (i.e. make it non-editable), you can instead use:
```ruby
-pdf.save(true)
-
-pdf.save_as('output.pdf', true)
+pdf.save(flatten: true)
+pdf.save_as('output.pdf', flatten: true)
```
+**NOTE:** Saving the file automatically closes the input file, so you would need to reinitialize the `FillabePDF` class before making any more changes or saving another copy.
## Example
-The following example [test.rb](test/test.rb) and the input file [input.pdf](test/input.pdf) are located in the `test` directory. It uses all of the methods that are described above and generates the output file [output.pdf](test/output.pdf).
+The following example [example.rb](example/run.rb) and the input file [input.pdf](example/input.pdf) are located in the `test` directory. It uses all of the methods that are described above and generates the output files [output.pdf](example/output.pdf) and [output.flat.pdf](example/output.flat.pdf).
```ruby
+require 'fillable-pdf'
+
# opening a fillable PDF
pdf = FillablePDF.new('input.pdf')
# total number of fields
if pdf.any_fields?
@@ -157,74 +158,73 @@
pdf.set_fields(football: 'Yes', baseball: 'Yes',
basketball: 'Yes', nascar: 'Yes', hockey: 'Yes')
pdf.set_field(:date, Time.now.strftime('%B %e, %Y'))
# list of fields
-puts "Fields hash: #{pdf.get_fields}"
+puts "Fields hash: #{pdf.fields}"
puts
-# list of field keys
-puts "Keys: #{pdf.keys}"
+# list of field names
+puts "Keys: #{pdf.names}"
puts
# list of field values
puts "Values: #{pdf.values}"
puts
# Checking field type
-if pdf.get_field_type(:football) == Field::CHECKBOX
- puts "Field 'football' is of type CHECKBOX"
+if pdf.field_type(:football) == Field::BUTTON
+ puts "Field 'football' is of type BUTTON"
else
- puts "Field 'football' is not of type CHECKBOX"
+ puts "Field 'football' is not of type BUTTON"
end
puts
# Renaming field
pdf.rename_field :last_name, :surname
puts "Renamed field 'last_name' to 'surname'"
-puts "New keys: #{pdf.keys}"
puts
# Removing field
pdf.remove_field :nascar
puts "Removed field 'nascar'"
-puts "New keys: #{pdf.keys}"
-
puts
# printing the name of the person used inside the PDF
-puts "Signatory: #{pdf.get_field(:first_name)} #{pdf.get_field(:last_name)}"
+puts "Signatory: #{pdf.field(:first_name)} #{pdf.field(:last_name)}"
-# saving the filled out PDF in another file and making it non-editable
-pdf.save_as('output.pdf', true)
+# saving the filled out PDF in another file
+pdf.save_as('output.pdf')
+# saving another copy of the filled out PDF in another file and making it non-editable
+pdf = FillablePDF.new('output.pdf')
+pdf.save_as 'output.flat.pdf', flatten: true
```
-The example above produces the following output and also generates the output file [output.pdf](test/output.pdf).
+The example above produces the following output and also generates the output file [output.pdf](example/output.pdf).
- The form has a total of 8 fields.
-
- Fields hash: {:last_name=>"Rahl", :first_name=>"Richard", :football=>"Yes", :baseball=>"Yes", :basketball=>"Yes", :nascar=>"Yes", :hockey=>"Yes", :date=>"July 19, 2017"}
-
- Keys: [:last_name, :first_name, :football, :baseball, :basketball, :nascar, :hockey, :date]
-
- Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "Yes", "Yes", "July 19, 2017"]
-
- Field 'football' is of type CHECKBOX
-
- Renamed field 'last_name' to 'surname'
- New keys: [:first_name, :football, :baseball, :basketball, :nascar, :hockey, :date, :surname]
-
- Removed field 'nascar'
- New keys: [:first_name, :football, :baseball, :basketball, :hockey, :date, :surname]
-
- Signatory: Richard
+```
+The form has a total of 8 fields.
+Fields hash: {:last_name=>"Rahl", :first_name=>"Richard", :football=>"Yes", :baseball=>"Yes", :basketball=>"Yes", :nascar=>"Yes", :hockey=>"Yes", :date=>"August 30, 2019"}
+
+Keys: [:last_name, :first_name, :football, :baseball, :basketball, :nascar, :hockey, :date]
+
+Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "Yes", "Yes", "August 30, 2019"]
+
+Field 'football' is of type BUTTON
+
+Renamed field 'last_name' to 'surname'
+
+Removed field 'nascar'
+
+Signatory: Richard Rahl
+```
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
\ No newline at end of file