Formatting text fields

Text fields accept any text by default, and the signed PDF prints it at 11 points. When a field needs something more specific, such as a phone number, a dollar amount, or an account number in a fixed shape, you describe that in the field's config. Signers see a hint in the empty field and a short message when what they entered doesn't match, and they can't finish until it does.

Setting a field's config

config is part of a template field, so you set it when you create or update the field. Envelopes sent from the template copy it along with the rest of the field, and fields you add to an envelope directly (as in Send an envelope without a template) take the same config.

import {updateField} from '@verdocs/js-sdk';

await updateField(endpoint, templateId, 'amount', {
  config: {
    type: 'textbox',
    number: {style: 'currency', currency: 'USD', decimals: 2, min: 0},
    fit: {max_font_size: 11, min_font_size: 8, overflow: 'ellipsize'},
  },
});

config.type always matches the field's type, so you can leave it out and we fill it in. An update replaces the whole config, so include every option you want to keep, or send null to clear it. The template builder sets the same options from its Inspector panel.

Built-in formats

The field's validator checks for a common format:

A validator we don't recognize is treated as plain text.

Numbers, currency, and percentages

config.number makes a field a number field. Signers enter the number the way their locale writes it, and when they leave the field it's rewritten in the field's style. We store the plain number, like 12450.5, so your integration never has to parse $12,450.50, and the signed PDF prints it formatted.

A number field uses its number settings in place of validator. To prefill one, send the plain number as a string, like "12450.5".

Input masks

config.input_mask gives the value a fixed shape. Each _ is a slot for one character the signer types, and every other character is filled in for them. The mask also shows in the empty field, and the stored value includes the filled-in characters.

{"type": "textbox", "input_mask": "(___) ___-____"}

A signer who types 5550123456 gets (555) 012-3456, and the field isn't complete until every slot is filled. A slot accepts any character, so pair the mask with a pattern when slots must be digits:

{
  "type": "textbox",
  "input_mask": "(___) ___-____",
  "validation": {"pattern": "\\(\\d{3}\\) \\d{3}-\\d{4}"}
}

Patterns

config.validation.pattern is a regular expression the whole value has to match, and validation.message is what signers see when it doesn't:

{
  "type": "textbox",
  "validation": {"pattern": "AC-\\d{6}", "message": "Enter your account number, like AC-123456."}
}

We match the pattern against the entire value, so you don't need ^ and $. Patterns can be up to 500 characters, and we refuse ones that could take too long to match on some values, such as nested repeats like (a+)+.

Text case and length

config.text_case is upper or lower. Signing converts what the signer types, and we apply it again when a value is saved and when it's stamped, so values your application fills in follow it too. config.max_length caps the value at 1 to 10,000 characters.

Fitting text on the signed PDF

config.fit decides how the value fits the field's width on the signed PDF. Stamping starts at max_font_size and steps down toward min_font_size until the text fits. Text that's still too wide at the smallest size follows overflow.

In a multi-line field, every line shares the size that fits the widest one. Fit only changes the signed PDF; signers see their full value while they type.

When several checks apply

Signers see one message at a time, for the first check the value fails: the format or number range, then the mask, then the pattern, then the length. Empty values pass every check, since required decides whether a field can be left empty. Read-only fields skip the checks entirely.

Filling fields from your application

When your application fills fields itself, for example in a proxied signing flow, we apply text_case but store the value without the other checks. js-sdk exports the helpers signing uses, so you can check a value before you send it:

import {getFieldFormatProblem, parseFieldNumber} from '@verdocs/js-sdk';

if (field.config?.type === 'textbox' && field.config.number) {
  const amount = parseFieldNumber(field.config.number, '$12,450.50'); // 12450.5
  const problem = getFieldFormatProblem(field, String(amount)); // null when it passes
}

A failed check returns format, range, mask, pattern, or length. formatFieldNumber goes the other way, turning a stored number into the text the field shows.