Adding form fields to composer

[sled]

Hello there,

I'm trying to compose a PDF with AcroForm fields inside, because placing the fields by absolute coordinates is quite tedious and because they're not part of the layout, layouting becomes tricky.

So I had the idea to add the fields as simple "placeholder" boxes to the layout, it's not working perfectly yet, i.e. I'd like check boxes to be able to float to the left of the labels, infer the size of the box by the field's generated appearance etc.

Before I go further with this approach I'd like to hear your (@gettalong) opinion / suggestions whether this is feasible or if there's a better way to achieve this.

Here's an example:

class TextField < HexaPDF::Layout::Box
  def initialize(field:, **kwargs, &block)
    @field = field
    super(**kwargs, &block)
  end


  def draw(canvas, x, y)
    @field.create_widget(canvas.context, Rect: [x, y, x + width, y + height])
    super
  end
end

class CheckBoxField < HexaPDF::Layout::Box
  def initialize(field:, **kwargs, &block)
    @field = field
    super(**kwargs, &block)
  end

  def draw(canvas, x, y)
    @field.create_widget(canvas.context, Rect: [x, y, x + width, y + height])
    super
  end
end

HexaPDF::Composer.create('test.pdf') do |pdf|
  pdf.document.config['layout.boxes.map'][:text_field] = 'TextField'
  pdf.document.config['layout.boxes.map'][:check_box_field] = 'CheckBoxField'

  form = pdf.document.acro_form(create: true)

  pdf.column(columns: [15, -1], gaps: [5], equal_height: true) do |column|
    membership = form.create_check_box('membership')

    [
      column.check_box_field(field: membership, height: 10, width: 10),
      column.text('Ich bin bereits Teilnehmer.') # label for the checkbox
    ]
  end

  pdf.text('Kontaktinformationen')

  pdf.column(columns: 3, gaps: 30, equal_height: true) do |column|
    salutation = form.create_text_field('salutation', font_size: 10)
    firstname = form.create_text_field('firstname', font_size: 10)
    lastname = form.create_text_field('lastname', font_size: 10)

    [
      column.text_field(field: salutation, height: 20, style: { border: {width: 1, color: [[255, 0, 0]]}}),
      column.text_field(field: firstname, height: 20, style: { border: {width: 1, color: [[255, 0, 0]]}}),
      column.text_field(field: lastname, height: 20, style: { border: {width: 1, color: [[255, 0, 0]]}})
    ]
  end
end

[gettalong]

First, I like to mention that adding support for placing form fields via the layouting mechanism/composer is on my todo list. However, I don't have a clear vision on the implementation, yet.

• I think your approach makes the most sense. However, I would delegate the creation of the actual fields to the boxes, maybe using a block to allow complete configuration of the field and the future widget.

• As for check boxes: How about making a combined box? I.e. one that includes the check box and the label? Then you have complete control over where the check box should be in reference to the label. If you need some pointers on this, let me know.

• In your TextField#draw method you should use canvas.graphics_state.ctm.evaluate(x, y) to ensure you get the untransformed coordinates needed for the widget annotations (I generally try to use real coordinates in the box implementations to ensure fewer PDF content stream instructions but that is not guaranteed).

• You can use color: "red" instead of color: [[255, 0, 0]] as all CSS color names are supported.

• If you use this in production, I would change the configuration globally and not per instance since adding the box implementations is a non-invasive change.

[sled]

with floatable I mean something like in this example here: https://hexapdf.gettalong.org/examples/frame_text_flow.html so it would be possible to create something like:

My name is _______, and I live in _______

[TextBox] [Input Box] [TextBox] [InputBox]

[gettalong]

Ah, okay. You can have boxes floating left or right using the position=:float style property. However, layouting is done at the box/frame level and not at the paragraph level. So there would be a problem with wrapping lines.

What you really want is an inline box (see https://hexapdf.gettalong.org/documentation/api/HexaPDF/Document/Layout/index.html#method-i-inline_box and https://hexapdf.gettalong.org/documentation/api/HexaPDF/Document/Layout/index.html#method-i-formatted_text_box), like in this example (but it is easier with the higher-level layouting and composer interface). The only requirement is that the inline box has a fixed size.

[sled]

Can we use the AppearanceGenerator to calculate the size of the form field? Because often times the form inputs need to be styled in a particular way, so the default appearance generator is replaced by a custom one. Also if no width or height information is provided, the appearance generator falls back to default values

hexapdf/lib/hexapdf/type/acro_form/appearance_generator.rb

Line 210 in ca5a90d

rect.width = @document.config['acro_form.text_field.default_width'] if rect.width == 0

hexapdf/lib/hexapdf/type/acro_form/appearance_generator.rb

Line 213 in ca5a90d

(font_size == 0 ? @document.config['acro_form.default_font_size'] : font_size)

Instead of replicating this logic, which doesn't take into account user modifications to the appearance generator, it would be much easier if the AppearanceGenerator could give us sizing information. The layout implementation would then be trivial.

[gettalong]

A form field should ideally have its width and height set, the fallback calculations are just based on assumptions and/or configuration options. However, once you have created the widget with a width and/or height set to 0, you could call field.create_appearances which creates the appearances and then use widget[:Rect].width and widget[:Rect].height to get the final dimensions.

[gettalong]

Here is some sample code (it's a full script, so you can execute it) producing the following output:

require 'hexapdf'

# The check box field from your example.
class CheckBoxField < HexaPDF::Layout::Box
  def initialize(field: nil, **kwargs, &block)
    @field = field
    super(**kwargs, &block)
  end

  def draw(canvas, x, y)
    rect = [*canvas.graphics_state.ctm.evaluate(x, y),
            *canvas.graphics_state.ctm.evaluate(x + width, y + height)]
    @field.create_widget(canvas.context, Rect: rect)
    super
  end
end

# This class is an example for customizing an existing box class. Since the keyword arguments can't
# be defined via the Style class yet, they would need to be specified on each usage of the ListBox.
# So defining a custom class is a work-around for that.
class CustomList < HexaPDF::Layout::ListBox
  def initialize(**kwargs)
    super
    @content_indentation = 2 * style.font_size
    @item_spacing = style.font_size
    @item_type = lambda do |document, box, _index|
      HexaPDF::Layout::Box.new(height: box.style.font_size, width: box.style.font_size) do |canvas, ibox|
        canvas.fill_color("red").circle(ibox.width / 2.0, ibox.height / 2.0, ibox.width / 2.0).fill
      end
    end
  end
end

# This is a box implementation for a component, in this case for a checkbox with label.
#
# It encapsulates everything to easily render a check box at the current position, regardless of
# whether that is inside a column, a list box or anywhere else.
class CheckBoxWithLabel < HexaPDF::Layout::Box

  # The document argument is needed for creating and adding the sub-boxes. A Box would normally not
  # have a reference to a HexaPDF::Document instance since most of the layout classes are designed
  # to be rather independent of the other parts of HexaPDF.
  #
  # The other arguments are just the information needed for rendering the box.
  def initialize(document:, field:, label:, **kwargs)
    super(**kwargs)
    @document = document
    @field = if field.kind_of?(String)
               document.acro_form(create: true).create_check_box(field)
             else
               field
             end
    @label = label
  end

  # Fits the content into the rectangular area. See comments in the method for details.
  def fit(available_width, available_height, frame)
    # The box consists of two parts. One way to fit those parts would be to manually fit them into
    # rectangular area specified by available_width and available_height. However, it is much easier
    # to do what HexaPDF itself does: Use the Frame and BoxFitter classes. First we need the frame
    # instance for the available area, taking into account the reserved spaces for border, padding,
    # etc.
    content_frame = HexaPDF::Layout::Frame.new(frame.x + reserved_width_left,
                                               frame.y - available_height + reserved_height_bottom,
                                               available_width - reserved_width,
                                               available_height - reserved_height)
    # Then we just need to create the BoxFitter instance with the list of frames that it should
    # use; in our case just the one.
    @fitter = HexaPDF::Layout::BoxFitter.new([content_frame])

    # Now that we have everything, we create the boxes for the individual content parts and fit them
    # using the box fitter.

    # Check Box
    check_box = @document.layout.check_box_field(field: @field,
                                                 width: style.font_size, height: style.font_size,
                                                 style: {margin: [0, 10, 0, 0],
                                                         position: :float, position_hint: :left})
    @fitter.fit(check_box)

    # Label
    label_box = @document.layout.text_box(@label, style: style, position: :float)
    @fitter.fit(label_box)

    # Once all boxes are placed we need to set the @width and @height. Otherwise the layout engine
    # would think that the box couldn't be correctly fit.
    #
    # Ordinarily, we would take a set width and height into account at the start of the method. In
    # this case those are ignored and it is assumed the box has dynamic width and height.
    #
    # The width is calculated by summing the consumed space from both boxes. For the height we ask
    # the box fitter for the content height.
    @width = @fitter.fit_results.sum {|fr| fr.mask.bbox.width }
    @height = @fitter.content_heights[0]

    # Finally we need to set @fit_successful to whether fitting was succesful. Again, the box fitter
    # has the necessary information.
    @fit_successful = @fitter.fit_successful?
  end

  # No splitting is allowed.
  def split(_available_width, _available_height, _frame)
    @fitter.fit_successful? ? [self, nil] : [nil, self]
  end

  # Drawing is easy by just using the results stored in the box fitter instance. Note that we do not
  # utilize the x and y coordinates here because the frame we built in #fit contains coordinates
  # relative to the outer frame and not coordinates relative to its origin at (0,0).
  def draw_content(canvas, _x, _y)
    @fitter.fit_results.each {|result| result.draw(canvas) }
  end
end

# By registering the custom box classes we can easily access them in the composer or in doc.layout.
HexaPDF::DefaultDocumentConfiguration['layout.boxes.map'][:check_box_field] = CheckBoxField
HexaPDF::DefaultDocumentConfiguration['layout.boxes.map'][:custom_list] = CustomList
HexaPDF::DefaultDocumentConfiguration['layout.boxes.map'][:check_box_with_label] = CheckBoxWithLabel


HexaPDF::Composer.new do |comp|
  comp.document.config['debug'] = true
  form = comp.document.acro_form(create: true)
  comp.text("Here comes a standalone check box in size 20x20")
  comp.check_box_field(field: form.create_check_box('test'), width: 20, height: 20)
  comp.text("Here is a labeled one")
  comp.check_box_with_label(document: comp.document, field: 'labeled', label: 'This is the label')
  comp.custom_list do |list|
    list.check_box_with_label(document: comp.document, field: 'list1', label: 'Inside the list 1')
    list.check_box_with_label(document: comp.document, field: 'list2', label: 'Inside the list 2')
  end
  comp.column do |column|
    column.check_box_with_label(document: comp.document, field: 'col1', label: 'Inside the column 1')
    column.check_box_with_label(document: comp.document, field: 'col2', label: 'Inside the column 2')
  end
  comp.write('form.pdf')
end