fillable-pdf 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3105d6a8fe53b1a6e31ba6c13742fcf1084e9a37e54e6163545962e0afad39c9
-  data.tar.gz: be445e7766b56bf10b87a08683909932039e3bdd6ed99d2f743635f24f650867
+  metadata.gz: 2cdd748940498c34c3e4f19f91f83cfc47fcf34dda1d10eb07e05f7aef9c7d57
+  data.tar.gz: a98954a86876c759716a8919a24f54c175ec97eb0eddd19bc2b9aaa844bdd6cb
 SHA512:
-  metadata.gz: 7bc9900f789332db17d1b754a911139fd99e14b2410bcaab167311b0d29404fffe0131ea450963fee265c9db0daaa50852371b5ca63f2eadc39c636c3ce62126
-  data.tar.gz: 412662633f9de92c60cecceaea7bee5afda28c7b55edb5f76d8a424ab9b096a4f598bca4e7ef99adcbe41da090e84a9b1247c99301e25746dd0b5140ad024d51
+  metadata.gz: bb4104898a7feb6a16338aae323b3d1285f8fb5dd2458e48d5e936ca17ed27fc407289c68db0a466105bbe06fc1100cfd5a8cfa92873f6f6b731692ee385bfaf
+  data.tar.gz: 07430fe63ccbbec3e4c7c5191d6831b767320b87ed6ea0bd0542c11d41e10fe8c7883ce7d396fe7cc31f029d425fb87e055e3af01bd44358cf8d3b99010e17ca

data/README.md

@@ -1,14 +1,16 @@
 
 # FillablePDF
 
-[![Gem Version](https://img.shields.io/gem/v/fillable-pdf.svg)](https://rubygems.org/gems/fillable-pdf)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Lint Status](https://github.com/vkononov/fillable-pdf/actions/workflows/lint.yml/badge.svg)](https://github.com/vkononov/fillable-pdf/actions/workflows/lint.yml)
-[![Test Status](https://github.com/vkononov/fillable-pdf/actions/workflows/test.yml/badge.svg)](https://github.com/vkononov/fillable-pdf/actions/workflows/test.yml)
+[![Gem Version](https://img.shields.io/gem/v/fillable-pdf.svg?label=Gem&logo=rubygems&logoColor=white)](https://rubygems.org/gems/fillable-pdf)
+[![Ruby](https://img.shields.io/badge/Ruby-2.4%20to%204.0-CC342D?logo=ruby&logoColor=white)](https://github.com/vkononov/fillable-pdf/blob/main/.github/workflows/test.yml)
+[![JDK](https://img.shields.io/badge/JDK-8%20to%2026-007396?logo=openjdk&logoColor=white)](https://github.com/vkononov/fillable-pdf/blob/main/.github/workflows/test.yml)
+[![Test Matrix](https://img.shields.io/github/actions/workflow/status/vkononov/fillable-pdf/test.yml?branch=main&label=Test%20Matrix&logo=github)](https://github.com/vkononov/fillable-pdf/actions/workflows/test.yml)
+[![Lint](https://img.shields.io/github/actions/workflow/status/vkononov/fillable-pdf/lint.yml?branch=main&label=Lint&logo=github)](https://github.com/vkononov/fillable-pdf/actions/workflows/lint.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/MIT)
 
 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.
 
-Supports `Ruby >= 2.4.0` with `JDK >= 8`
+Supports **Ruby 2.4 → latest** and **JDK 8 → latest**, with the full Ruby/Java matrix tested daily in CI.
 
 [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/vkononov)
 
@@ -16,7 +18,7 @@ Supports `Ruby >= 2.4.0` with `JDK >= 8`
 
 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. 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.
+2. Puma workers (process forking) is not supported 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:
 
@@ -229,7 +231,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     pdf.set_field('first_name', 'Richard', generate_appearance: false)
     ```
 
-* `def set_fields(fields, generate_appearance: nil)`
+* `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
@@ -317,7 +319,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # result: document is saved in a given path with flattening
     ```
 
-    **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.
+    **NOTE:** Saving the file automatically closes the input file, so you would need to reinitialize the `FillablePDF` class before making any more changes or saving another copy.
 
 * `save_as!(file_path, flatten: false)`
     *Saves the filled out PDF document in a given path and flattens it if requested. Raises an error if the path matches the current file (use save() instead).*
@@ -452,15 +454,18 @@ Naturally, there are many downsides (in terms of efficiency, scalability, securi
 
 ## Example
 
-The following [example.rb](example/run.rb) with [input.pdf](example/input.pdf) is located in the [example](example) 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).
+The following [run.rb](example/run.rb) with [input.pdf](example/input.pdf) is located in the [example](example) directory. It uses most 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_relative '../lib/fillable-pdf'
 
+# Get the directory where this script is located
+EXAMPLE_DIR = __dir__
+
 BASE64_PHOTO = 'iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==' # rubocop:disable Layout/LineLength
 
 # opening a fillable PDF
-pdf = FillablePDF.new('input.pdf')
+pdf = FillablePDF.new(File.join(EXAMPLE_DIR, 'input.pdf'))
 
 # total number of fields
 if pdf.any_fields?
@@ -473,12 +478,15 @@ 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', rugby: 'Yes'}, generate_appearance: false)
+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')
+pdf.set_image(:signature, File.join(EXAMPLE_DIR, 'signature.png'))
 
 # list of fields
 puts "Fields hash: #{pdf.fields}"
@@ -515,11 +523,11 @@ pdf.remove_field :marketing
 puts "Removed field 'marketing'"
 
 # saving the filled out PDF in another file
-pdf.save_as('output.pdf')
+pdf.save_as(File.join(EXAMPLE_DIR, '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
+pdf = FillablePDF.new(File.join(EXAMPLE_DIR, 'output.pdf'))
+pdf.save_as File.join(EXAMPLE_DIR, 'output.flat.pdf'), flatten: true
 
 # closing the document
 pdf.close
@@ -528,19 +536,19 @@ pdf.close
 The example above produces the following output and also generates the output file [output.pdf](example/output.pdf).
 
 ```text
-The form has a total of 16 fields.
+The form has a total of 14 fields.
 
-Fields hash: {:last_name=>"Rahl", :first_name=>"Richard", :football=>"Yes", :baseball=>"Yes", :basketball=>"Yes", :hockey=>"Yes", :date=>"November 16, 2021", :newsletter=>"Off", :nascar=>"Yes", :language=>"dart", :"language.1"=>"dart", :"language.2"=>"dart", :"language.3"=>"dart", :"language.4"=>"dart", :signature=>"", :photo=>""}
+Fields hash: {last_name: "Rahl", first_name: "Richard", football: "Yes", baseball: "Yes", basketball: "Yes", date: "August 12, 2026", newsletter: "Off", nascar: "Yes", language: "dart", signature: "", photo: "", rugby: "Yes", hockey: "Yes", marketing: ""}
 
-Keys: [:last_name, :first_name, :football, :baseball, :basketball, :hockey, :date, :newsletter, :nascar, :language, :"language.1", :"language.2", :"language.3", :"language.4", :signature, :photo]
+Keys: [:last_name, :first_name, :football, :baseball, :basketball, :date, :newsletter, :nascar, :language, :signature, :photo, :rugby, :hockey, :marketing]
 
-Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "Yes", "November 16, 2021", "Off", "Yes", "dart", "dart", "dart", "dart", "dart", "", ""]
+Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "August 12, 2026", "Off", "Yes", "dart", "", "", "Yes", "Yes", ""]
 
 Field 'football' is of type BUTTON
 
 Renamed field 'last_name' to 'surname'
 
-Removed field 'nascar'
+Removed field 'marketing'
 ```
 
 ## Contributing
@@ -554,6 +562,6 @@ Removed field 'nascar'
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/license/MIT).
 
-However, you must also adhere to the [iText License](https://github.com/itext/itext7) when using this gem in your project.
+However, you must also adhere to the [iText License](https://github.com/itext/itext-java) when using this gem in your project.

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 class FillablePDF
-  VERSION = '1.1.1'
+  VERSION = '1.1.3'
 end

data/lib/fillable-pdf.rb

@@ -128,7 +128,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #   @param [String|Symbol] key the field name
   #   @param [String|Symbol] file_path the name of the image file or image path
   #   @return [self] returns self for method chaining
-  #   @raise [FileOperationError] if the image file is not found
+  #   @raise [FileOperationError] if the image file is not found or the field has no visible area
   #   @raise [FieldNotFoundError] if the field does not exist
   #
   def set_image(key, file_path) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
@@ -136,13 +136,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
     raise FileOperationError, "File <#{file_path}> is not found" unless File.exist?(file_path)
 
     begin
-      field = pdf_field(key)
-      widgets = field.getWidgets
-      widget_dict = suppress_warnings { widgets.isEmpty ? field.getPdfObject : widgets.get(0).getPdfObject }
-      orig_rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
-
-      border_style = field.getWidgets.get(0).getBorderStyle
-      border_width = border_style.nil? ? 0 : border_style.getWidth
+      widget_dict, orig_rect, border_width = image_placement(key)
 
       bounding_rectangle = ITEXT::Rectangle.new(
         orig_rect.getWidth - (border_width * 2),
@@ -165,6 +159,8 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
       widget_dict.put(ITEXT::PdfName.AP, pdf_dict)
       pdf_dict.put(ITEXT::PdfName.N, pdf_form_x_object.getPdfObject)
       widget_dict.setModified
+    rescue FileOperationError
+      raise
     rescue StandardError => e
       raise FileOperationError, "Failed to set image for field '#{key}': #{e.message}"
     end
@@ -393,6 +389,20 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
     field
   end
 
+  # Dictionary, rectangle and border width of the field's first widget, falling
+  # back to the field itself when it has no widget annotations.
+  def image_placement(key)
+    field = pdf_field(key)
+    widgets = field.getWidgets
+    widget = widgets.isEmpty ? nil : widgets.get(0)
+    widget_dict = suppress_warnings { (widget || field).getPdfObject }
+    rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
+    raise FileOperationError, "Field '#{key}' has no visible area to place an image in" if rect.nil?
+
+    border_style = widget&.getBorderStyle
+    [widget_dict, rect, border_style.nil? ? 0 : border_style.getWidth]
+  end
+
   def validate_input(key, value)
     validate_field_name(key)
     raise InvalidArgumentError, 'Field value cannot be nil' if value.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Vadim Kononov
@@ -51,9 +51,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
-description: 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.
+description: Ruby wrapper for iText to work with AcroForm PDFs. Fill and read text
+  fields, checkboxes and radio buttons, add images to fields, rename or remove fields,
+  and flatten forms.
 email:
 - vadim@konoson.com
 executables: []
@@ -62,12 +62,12 @@ extra_rdoc_files: []
 files:
 - LICENSE.md
 - README.md
-- ext/commons-9.7.0.jar
-- ext/font-asian-9.7.0.jar
-- ext/forms-9.7.0.jar
-- ext/io-9.7.0.jar
-- ext/kernel-9.7.0.jar
-- ext/layout-9.7.0.jar
+- ext/commons-9.7.1.jar
+- ext/font-asian-9.7.1.jar
+- ext/forms-9.7.1.jar
+- ext/io-9.7.1.jar
+- ext/kernel-9.7.1.jar
+- ext/layout-9.7.1.jar
 - ext/slf4j-api-2.0.18.jar
 - ext/slf4j-simple-2.0.18.jar
 - lib/fillable-pdf.rb
@@ -98,5 +98,5 @@ requirements:
 - JDK >= 8
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Fill out or extract field values from simple fillable PDF forms using iText.
+summary: Fill, read, flatten and edit PDF form fields in Ruby with the iText engine
 test_files: []