Boldsign.FormField (Boldsign v0.10.0)

Copy Markdown View Source

Typed builders for BoldSign signer form fields placed by coordinate.

These build the entries you put in a signer's formFields list on Boldsign.Document.send/2 (and friends), anchoring each field at explicit page coordinates.

The type gotcha

BoldSign's form-field object keys the field type as type, not fieldType. If you send fieldType, BoldSign silently ignores it and every field defaults to a signature field — so a date field renders as a second signature, a checkbox becomes a signature, etc., with no error. These builders always emit the correct type key so you cannot hit that trap.

Coordinates

bounds are in 96-DPI pixels from the top-left of the page. If you derive positions from a PDF text layer (pdftotext -bbox reports points at 72 DPI), multiply by 4/3.

Example

Boldsign.Document.send(client, %{
  title: "Agreement",
  files: [Boldsign.File.from_binary(pdf, "agreement.pdf", "application/pdf")],
  signers: [
    %{
      name: "Ada",
      emailAddress: "ada@example.com",
      signerType: "Signer",
      signerOrder: 1,
      formFields: [
        Boldsign.FormField.signature(%{x: 72, y: 803, width: 150, height: 40}, id: "sig1"),
        Boldsign.FormField.date_signed(%{x: 72, y: 889, width: 120, height: 24}, id: "date1")
      ]
    }
  ]
})

Prefer this coordinate path over Boldsign.TextTag: definition-based text tags on document/send did not reliably persist a document in live testing (the API returns 201 with a documentId, but the document is never created). See Boldsign.TextTag for details.

Summary

Types

bounds()

%{x:, y:, width:, height:} (any key style) or a {x, y, width, height} tuple, in 96-DPI px from the top-left.

opts()

Options: :page (1-based, default 1), :required (default true), :id, :name.

Functions

build(type, bounds, opts \\ [])

Builds a field for any BoldSign type string. Use the typed helpers above for the common cases; this is the escape hatch for others.

checkbox(bounds, opts \\ [])

A checkbox field.

date_signed(bounds, opts \\ [])

A date-signed field (BoldSign auto-fills it with the signing date).

initial(bounds, opts \\ [])

An initials field.

signature(bounds, opts \\ [])

A signature field.

text_box(bounds, opts \\ [])

A free-text field the signer fills in.

Types

bounds()

@type bounds() :: map() | {number(), number(), number(), number()}

%{x:, y:, width:, height:} (any key style) or a {x, y, width, height} tuple, in 96-DPI px from the top-left.

opts()

@type opts() :: [
  page: pos_integer(),
  required: boolean(),
  id: String.t(),
  name: String.t()
]

Options: :page (1-based, default 1), :required (default true), :id, :name.

Functions

build(type, bounds, opts \\ [])

@spec build(String.t(), bounds(), opts()) :: map()

Builds a field for any BoldSign type string. Use the typed helpers above for the common cases; this is the escape hatch for others.

checkbox(bounds, opts \\ [])

@spec checkbox(bounds(), opts()) :: map()

A checkbox field.

date_signed(bounds, opts \\ [])

@spec date_signed(bounds(), opts()) :: map()

A date-signed field (BoldSign auto-fills it with the signing date).

initial(bounds, opts \\ [])

@spec initial(bounds(), opts()) :: map()

An initials field.

signature(bounds, opts \\ [])

@spec signature(bounds(), opts()) :: map()

A signature field.

text_box(bounds, opts \\ [])

@spec text_box(bounds(), opts()) :: map()

A free-text field the signer fills in.