fillable-pdf 0.9.4 → 0.9.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3295f6a5e77e53fb9ae16f59cb1456483daecf203857cd903fd84622336f9d35
-  data.tar.gz: 4bb925c8f5908f663d36f93afb701c2dc5dcd744f476a50b2bf17fc73ff97f6d
+  metadata.gz: d8b685f435c8356edc53a47ca0581ae1fa71c57cb23876b12e3ba7bef0d4aa99
+  data.tar.gz: 84f4dcd7ac4d566493dcc37a3ea3e7d776c6f8a28b1129465304ad198c2a7530
 SHA512:
-  metadata.gz: ae5c10683e12cda0c209126d256b6f223d2b4194c85b06be9af9e76c12a710c8fe5d8fe6b3ff646d0b285ff93d0f97a8a0bd0c655474b52746a7c43460fd7925
-  data.tar.gz: a793a4b88d8034f9d3194fd19c07244c4d1083477f9004307208c1b9b23764fc0dde863f6f2a54c0abb264c90f5b2d05360b850fbc074afe9f259d4f51a449cf
+  metadata.gz: 575e161cc77a304578997b4d2f967019df98382be944b0fbfd1f6e171e97545bf265a84c2b70a1a80515de520517c303fcfdf27db48ce64c0bae3a292832e6a7
+  data.tar.gz: aaaf3eee62d9886660ca753b3a06495d73ba9092d10a56e415bc5283a0056a9418d53ce9df1bda8d7030ed723e93cd1473a59107515800a6715da05eaacf7da5

data/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# GitHub recommends pinning actions to a commit SHA.
+# To get a newer version, you will need to update the SHA.
+# You can also reference a tag or branch, but the action may change without warning.
+
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: ['3.1', '3.0', '2.7', '2.6', '2.5', '2.4']
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rake test

data/.rubocop.yml

@@ -29,6 +29,7 @@ Layout/LineLength:
     - README.md
     - fillable-pdf.gemspec
   Max: 120
+  AllowedPatterns: ['^(\s*#)']
 
 Layout/SpaceInsideHashLiteralBraces:
   Enabled: false
@@ -55,5 +56,8 @@ Style/FrozenStringLiteralComment:
 Style/GuardClause:
   Enabled: false
 
+Style/HashSyntax:
+  Enabled: false
+
 Style/MutableConstant:
   Enabled: false

data/README.md

@@ -2,30 +2,61 @@
 # FillablePDF
 
 [![Gem Version](https://badge.fury.io/rb/fillable-pdf.svg)](https://rubygems.org/gems/fillable-pdf)
-[![Build Status](https://app.travis-ci.com/vkononov/fillable-pdf.svg?branch=master)](http://travis-ci.org/vkononov/fillable-pdf)
+[![Test Status](https://github.com/vkononov/fillable-pdf/actions/workflows/test.yml/badge.svg)](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.
 
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/vkononov)
 
 ## Known Issues
 
-1. This gem currently does not work with Phusion Passenger's [smart spawning](https://www.phusionpassenger.com/library/indepth/ruby/spawn_methods/#the-smart-spawning-method). Please see [Deployment with Phusion Passenger + Nginx](#deployment-with-phusion-passenger--nginx) for more information.
+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.
 
-2. If the gem hangs in `development`, removing the following gems may fix the issue:
+2. Puma workers (process forking) is not supposed due to an [issue](https://github.com/arton/rjb/issues/88) with the [rjb](https://github.com/arton/rjb) gem dependency.
+
+3. If the gem hangs in `development`, removing the following gems may fix the issue:
 
     ```ruby
     gem 'spring'
     gem 'spring-watcher-listen'
     ```
 
-3. Read-only, write-protected or encrypted PDF files are currently not supported.
+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.
+
+
+## Troubleshooting Issues
+
+### Blank Fields
+
+* **Actual Result:**
+
+  ![Blank](images/blank.png)
+
+* **Expected Result:**
+
+  ![Blank](images/checked.png)
+
+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:**
+
+  ![Blank](images/checked.png)
+
+* **Expected Result:**
 
+  ![Blank](images/distinct.png)
+
+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).**
+- Ensure that your `JAVA_HOME` variable is set before installing this gem (see examples below).
 
   * OSX: `/Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home`
   * Ubuntu/CentOS: `/usr/lib/jvm/java-1.8.0-openjdk`
@@ -126,19 +157,21 @@ An instance of `FillablePDF` has the following methods at its disposal:
     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`
-    *Retrieves the numeric type of a field given its unique field name.*
+* `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
@@ -148,6 +181,13 @@ An instance of `FillablePDF` has the following methods at its disposal:
     Field::TEXT ('/Tx')
     ```
 
+    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.*
 
@@ -156,52 +196,71 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # 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
     ```
 
@@ -221,7 +280,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # output example: ["Rahl", "Richard"]
     ```
 
-* `save`
+* `save(flatten: false)`
     *Overwrites the previously opened PDF document and flattens it if requested.*
 
     ```ruby
@@ -231,7 +290,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # 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
@@ -333,8 +392,8 @@ 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
@@ -357,7 +416,7 @@ 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"
@@ -372,8 +431,8 @@ 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')

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 class FillablePDF
-  VERSION = '0.9.4'
+  VERSION = '0.9.5.1'
 end

data/lib/fillable-pdf.rb

@@ -10,7 +10,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   #   @param [String|Symbol] file_path the name of the PDF file or file path
   #
-  def initialize(file_path) # rubocop:disable Metrics/MethodLength
+  def initialize(file_path)
     raise IOError, "File <#{file_path}> is not found" unless File.exist?(file_path)
     @file_path = file_path
     begin
@@ -20,7 +20,6 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
       @pdf_doc = ITEXT::PdfDocument.new @pdf_reader, @pdf_writer
       @pdf_form = ITEXT::PdfAcroForm.getAcroForm(@pdf_doc, true)
       @form_fields = @pdf_form.getFormFields
-      @pdf_form.setGenerateAppearance false
     rescue StandardError => e
       raise "#{e.message} (Input file may be corrupt, incompatible, read-only, write-protected, encrypted, or may not have any form fields)" # rubocop:disable Layout/LineLength
     end
@@ -58,7 +57,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   end
 
   ##
-  # Retrieves the numeric type of a field given its unique field name.
+  # Retrieves the string type of a field given its unique field name.
   #
   #   @param [String|Symbol] key the field name
   #
@@ -88,9 +87,14 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   #   @param [String|Symbol] key the field name
   #   @param [String|Symbol] value the field value
+  #   @param [NilClass|TrueClass|FalseClass] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance, nil (default) to let iText decide what's appropriate
   #
-  def set_field(key, value)
-    pdf_field(key).setValue(value.to_s)
+  def set_field(key, value, generate_appearance: nil)
+    if generate_appearance.nil?
+      pdf_field(key).setValue(value.to_s)
+    else
+      pdf_field(key).setValue(value.to_s, generate_appearance)
+    end
   end
 
   ##
@@ -155,9 +159,10 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   # Sets the values of multiple fields given a set of unique field names and values.
   #
   #   @param [Hash] fields the set of field names and values
+  #   @param [NilClass|TrueClass|FalseClass] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance,  nil (default) to let iText decide what's appropriate
   #
-  def set_fields(fields)
-    fields.each { |key, value| set_field key, value }
+  def set_fields(fields, generate_appearance: nil)
+    fields.each { |key, value| set_field key, value, generate_appearance: generate_appearance }
   end
 
   ##
@@ -218,7 +223,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   # Saves the filled out PDF document in a given path and flattens it if requested.
   #
   #   @param [String] file_path the name of the PDF file or file path
-  #   @param [Hash] flatten: true if PDF should be flattened, false otherwise
+  #   @param [TrueClass|FalseClass] flatten true if PDF should be flattened, false otherwise
   #
   def save_as(file_path, flatten: false)
     if @file_path == file_path
@@ -243,7 +248,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   ##
   # Writes the contents of the modified fields to the previously opened PDF file.
   #
-  #   @param [Hash] flatten: true if PDF should be flattened, false otherwise
+  #   @param [TrueClass|FalseClass] flatten: true if PDF should be flattened, false otherwise
   #
   def finalize(flatten: false)
     @pdf_form.flattenFields if flatten

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.5.1
 platform: ruby
 authors:
 - Vadim Kononov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-14 00:00:00.000000000 Z
+date: 2022-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -145,24 +145,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".rubocop.yml"
-- ".travis.yml"
 - Gemfile
 - LICENSE.md
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
-- ext/commons-7.2.3.jar
-- ext/font-asian-7.2.3.jar
-- ext/forms-7.2.3.jar
-- ext/io-7.2.3.jar
-- ext/kernel-7.2.3.jar
-- ext/layout-7.2.3.jar
-- ext/slf4j-api-1.7.32.jar
-- ext/slf4j-simple-1.7.32.jar
+- ext/commons-7.2.4.jar
+- ext/font-asian-7.2.4.jar
+- ext/forms-7.2.4.jar
+- ext/io-7.2.4.jar
+- ext/kernel-7.2.4.jar
+- ext/layout-7.2.4.jar
+- ext/slf4j-api-2.0.4.jar
+- ext/slf4j-simple-2.0.4.jar
 - fillable-pdf.gemspec
+- images/blank.png
+- images/checked.png
+- images/distinct.png
 - lib/field.rb
 - lib/fillable-pdf.rb
 - lib/fillable-pdf/itext.rb

data/.travis.yml

@@ -1,10 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 3.0.3
-jdk:
-  - openjdk8
-before_install:
-  - gem install bundler