README.md in fillable-pdf-0.9.5 vs README.md in fillable-pdf-0.9.5.1
- old
+ new
@@ -4,10 +4,11 @@
[](https://rubygems.org/gems/fillable-pdf)
[](https://github.com/vkononov/fillable-pdf/actions)
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.
+[](https://www.buymeacoffee.com/vkononov)
## Known Issues
1. Phusion Passenger's [smart spawning](https://www.phusionpassenger.com/library/indepth/ruby/spawn_methods/#the-smart-spawning-method) is not supported. Please see [Deployment with Phusion Passenger + Nginx](#deployment-with-phusion-passenger--nginx) for more information.
@@ -20,13 +21,39 @@
gem 'spring-watcher-listen'
```
4. Read-only, write-protected or encrypted PDF files are currently not supported.
-5. Adobe generated field arrays (i.e. fields with names such as `array.0` or `array.1.0`) are not supported.
+5. Adobe generated field arrays (i.e. fields with names such as `array.0` or `array.1.0`) are not supported.
+## Troubleshooting Issues
+
+### Blank Fields
+
+* **Actual Result:**
+
+ 
+
+* **Expected Result:**
+
+ 
+
+If only of the fields are blank, try setting the `generate_appearance` flag to `true` when calling `set_field` or `set_fields`.
+
+### Invalid Checkbox Appearances
+
+* **Actual Result:**
+
+ 
+
+* **Expected Result:**
+
+ 
+
+If your checkboxes are showing incorrectly, it's likely because iText is overwriting your checkbox appearances. Try setting the `generate_appearance` flag to `false` when calling `set_field` or `set_fields`.
+
## Installation
**Prerequisites:** Java SE Development Kit v8, v11
- Ensure that your `JAVA_HOME` variable is set before installing this gem (see examples below).
@@ -128,23 +155,25 @@
```ruby
# output example: 10
pdf.num_fields
```
-* `field`
+* `field(key)`
*Retrieves the value of a field given its unique field name.*
```ruby
pdf.field(:full_name)
+ pdf.field('full_name')
# output example: 'Richard'
```
-* `field_type`
+* `field_type(key)`
*Retrieves the string type of a field given its unique field name.*
```ruby
pdf.field_type(:football)
+ pdf.field_type('football')
# output example: '/Btn'
# list of all field types
Field::BUTTON ('/Btn')
Field::CHOICE ('/Ch')
@@ -154,66 +183,86 @@
You can check the field type by using:
```ruby
pdf.field_type(:football) == Field::BUTTON
+ pdf.field_type('football') == Field::BUTTON
```
* `fields`
*Retrieves a hash of all fields and their values.*
```ruby
pdf.fields
# output example: {first_name: "Richard", last_name: "Rahl"}
```
-* `set_field`
- *Sets the value of a field given its unique field name and value.*
+* `set_field(key, value, generate_appearance: nil)`
+ *Sets the value of a field given its unique field name and value, with an optional `generate_appearance` directive.*
```ruby
pdf.set_field(:first_name, 'Richard')
+ pdf.set_field('first_name', 'Richard')
# result: changes the value of 'first_name' to 'Richard'
```
-* `set_fields`
- *Sets the values of multiple fields given a set of unique field names and values.*
+ Optionally, you can choose to override iText's `generateAppearance` flag to take better control of your field's appearance, using `generate_appearance`. Passing `true` will force the field to generate its own appearance, while setting it to `false` would leave the appearance generation up to the PDF viewer application. Omitting the parameter would allow iText to decide what should happen.
```ruby
- pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
+ pdf.set_field(:first_name, 'Richard', generate_appearance: true)
+ pdf.set_field('first_name', 'Richard', generate_appearance: false)
+ ```
+
+* `def set_fields(fields, generate_appearance: nil)`
+ *Sets the values of multiple fields given a set of unique field names and values, with an optional `generate_appearance` directive.*
+
+ ```ruby
+ pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'})
# result: changes the values of 'first_name' and 'last_name'
```
-* `set_image`
+ Optionally, you can choose to override iText's `generateAppearance` flag to take better control of your fields' appearance, using `generate_appearance`. Passing `true` will force the field to generate its own appearance, while setting it to `false` would leave the appearance generation up to the PDF viewer application. Omitting the parameter would allow iText to decide what should happen.
+
+ ```ruby
+ pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'}, generate_appearance: true)
+ pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'}, generate_appearance: false)
+ ```
+
+* `set_image(key, file_path)`
*Places an image file within the rectangular bounding box of the given form field.*
```ruby
pdf.set_image(:signature, 'signature.png')
+ pdf.set_image('signature', 'signature.png')
# result: the image 'signature.png' is shown in the foreground of the form field
```
-* `set_image_base64`
+* `set_image_base64(key, base64_image_data)`
*Places a base64 encoded image within the rectangular bounding box of the given form field.*
```ruby
+ pdf.set_image_base64('signature', 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==')
pdf.set_image_base64(:signature, 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==')
# result: the base64 encoded image is shown in the foreground of the form field
```
-* `rename_field`
+* `rename_field(old_key, new_key)`
*Renames a field given its unique field name and the new field name.*
```ruby
pdf.rename_field(:last_name, :surname)
+ pdf.rename_field('last_name', 'surname')
# result: renames field name 'last_name' to 'surname'
# NOTE: this action does not take effect until the document is saved
```
-* `remove_field`
+* `remove_field(key)`
*Removes a field from the document given its unique field name.*
```ruby
pdf.remove_field(:last_name)
+ pdf.remove_field('last_name')
# result: physically removes field 'last_name' from document
```
* `names`
*Returns a list of all field keys used in the document.*
@@ -229,21 +278,21 @@
```ruby
pdf.values
# output example: ["Rahl", "Richard"]
```
-* `save`
+* `save(flatten: false)`
*Overwrites the previously opened PDF document and flattens it if requested.*
```ruby
pdf.save
# result: document is saved without flattening
pdf.save_as(flatten: true)
# result: document is saved with flattening
```
-* `save_as`
+* `save_as(file_path, flatten: false)`
*Saves the filled out PDF document in a given path and flattens it if requested.*
```ruby
pdf.save_as('output.pdf')
# result: document is saved in a given path without flattening
@@ -341,12 +390,12 @@
end
puts
# setting form fields
-pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
-pdf.set_fields(football: 'Yes', baseball: 'Yes', basketball: 'Yes', nascar: 'Yes', hockey: 'Yes')
+pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'})
+pdf.set_fields({football: 'Yes', baseball: 'Yes', basketball: 'Yes', nascar: 'Yes', hockey: 'Yes', rugby: 'Yes'}, generate_appearance: false)
pdf.set_field(:date, Time.now.strftime('%B %e, %Y'))
pdf.set_field(:newsletter, 'Off') # uncheck the checkbox
pdf.set_field(:language, 'dart') # select a radio button option
pdf.set_image_base64(:photo, BASE64_PHOTO)
pdf.set_image(:signature, 'signature.png')
@@ -365,11 +414,11 @@
puts "Values: #{pdf.values}"
puts
# Checking field type
-if pdf.field_type(:football) == Field::BUTTON
+if pdf.field_type(:rugby) == Field::BUTTON
puts "Field 'football' is of type BUTTON"
else
puts "Field 'football' is not of type BUTTON"
end
@@ -380,11 +429,11 @@
puts "Renamed field 'last_name' to 'surname'"
puts
# Removing field
-pdf.remove_field :nascar
-puts "Removed field 'nascar'"
+pdf.remove_field :marketing
+puts "Removed field 'marketing'"
# 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
\ No newline at end of file