PDF Text Replacement: Pdf.TextReplace

How it works, and the font rule

A PDF stores positioned glyphs drawn with particular fonts, not editable text. TextReplace finds each placeholder or label on the assembled lines of the selected pages, encodes the new value with the font the original text uses, recomputes its width from the font's metrics, and rewrites the string operands in the content stream in place.

A replacement is possible only when the new text can be drawn with that font:

• a standard-14 font (Helvetica, Times, Courier and their bold/italic faces, not embedded) can draw any character its encoding has — the Latin-1 / WinAnsi repertoire, typically;
• an embedded font can draw any character it has a glyph for — which for a subset font means the characters the document already uses, unless the subset happens to include more;
• a non-standard font that is not embedded cannot be used: Chilkat has no way to know what it can draw;
• the whole placeholder or value must be drawn in one font at one size.

The operations: check and apply

The replacements are made in memory and are written when WriteFile or WriteBd is called. The PDF is then saved as a full rewrite, so that the old values do not survive in an earlier revision of the file (as they would in an incremental update).

Quick start: fill a template

Chilkat.Pdf pdf = new Chilkat.Pdf();
pdf.LoadFile("invoice_template.pdf");

Chilkat.JsonObject jsonIn = new Chilkat.JsonObject();
Chilkat.JsonObject jsonOut = new Chilkat.JsonObject();
jsonIn.UpdateString("placeholders.customer", "Acme Corp");
jsonIn.UpdateString("placeholders.date", "2026-10-18");
jsonIn.UpdateString("placeholders.total", "$1,234.56");
jsonIn.UpdateString("labels[0].label", "Invoice #:");
jsonIn.UpdateString("labels[0].value", "INV-2026-0412");

if (!pdf.TextReplace("apply", jsonIn, jsonOut)) {
    Console.WriteLine(jsonOut.Emit());      // the problems
    Console.WriteLine(pdf.LastErrorText);
    return;
}
pdf.WriteFile("invoice_0412.pdf");

{
  "placeholders": {
    "customer": "Acme Corp",
    "date": "2026-10-18",
    "total": "$1,234.56"
  },
  "labels": [
    { "label": "Invoice #:", "value": "INV-2026-0412" }
  ]
}

{
  "applied": true,
  "replacements": [
    { "field": "customer", "pages": "1", "count": 1 },
    { "field": "date", "pages": "1", "count": 1 },
    { "field": "total", "pages": "1", "count": 1 },
    { "label": "Invoice #:", "pages": "1", "count": 1 }
  ],
  "warnings": [],
  "problems": [],
  "notReplaced": []
}

Placeholders

Placeholder names are matched exactly (case-sensitive) after trimming the spaces inside the delimiters, so {{ customer }} and {{customer}} are the same placeholder.

Example: square-bracket placeholders, numbers and booleans as values

{
  "placeholderSyntax": "[[name]]",
  "placeholders": {
    "qty": 12,
    "unitPrice": "9.50",
    "expedited": true,
    "notes": null
  }
}

Quantity: [[qty]]           ->  Quantity: 12
Unit price: [[unitPrice]]   ->  Unit price: 9.50
Expedited: [[expedited]]    ->  Expedited: true
Notes: [[notes]]            ->  Notes: 

Labels

A label is text already on the page, such as Invoice #: or Date, that is followed by a value. TextReplace replaces the rest of the label's line with the new value; when nothing follows the label, the value is inserted after it (with a space). Matching ignores case, extra spaces and a trailing colon — the same rules as ExtractText's label.

Example: three labels, one of them every time it occurs

{
  "labels": [
    { "label": "Invoice #:", "value": "INV-2026-0412" },
    { "label": "Date", "value": "October 18, 2026" },
    { "label": "Customer ID:", "value": "C-8841", "occurrence": "all" },
    { "label": "Phone:", "value": "555 0100", "occurrence": 2 }
  ]
}

{
  "applied": false,
  "ok": true,
  "replacements": [
    { "label": "Invoice #:", "pages": "1", "count": 1 },
    { "label": "Date", "pages": "1", "count": 1 },
    { "label": "Customer ID:", "pages": "1,2", "count": 3 },
    { "label": "Phone:", "pages": "2", "count": 1 }
  ],
  "warnings": [],
  "problems": [],
  "notReplaced": []
}

Alignment

The new text rarely has the width of the old. align decides where it sits:

{
  "align": "right",
  "placeholders": { "subtotal": "$1,100.00", "tax": "$134.56", "total": "$1,234.56" }
}

Subtotal     {{subtotal}}        Subtotal      $1,100.00
Tax               {{tax}}   ->   Tax             $134.56
Total           {{total}}        Total         $1,234.56

When the new text is wider than the old and would run into neighbouring text or off the page, the replacement is still made and an overlap warning is reported, so that the application can shorten the value or choose a different template.

Unused placeholders and unmatched values

Example: a partial fill

{
  "placeholders": { "customer": "Acme Corp" },
  "unusedPlaceholders": "keep",
  "unmatchedValues": "ignore"
}

Example: the defaults catch a typo in the template

{ "placeholders": { "customer": "Acme Corp", "total": "$1,234.56" } }

{
  "applied": false,
  "ok": false,
  "replacements": [ { "field": "customer", "pages": "1", "count": 1 } ],
  "warnings": [],
  "problems": [
    { "field": "totl", "reason": "unusedPlaceholder", "page": 1 },
    { "field": "total", "reason": "notFound" }
  ],
  "notReplaced": []
}

The report (jsonOut)

Problems and warnings

Example: a check that fails the font rule

{ "placeholders": { "customer": "Müller GmbH", "total": "€1.234,56" } }

{
  "applied": false,
  "ok": false,
  "replacements": [],
  "warnings": [],
  "problems": [
    { "field": "customer", "reason": "missingGlyph", "chars": "ü",
      "font": "ABCDEF+OpenSans-Regular", "page": 1 },
    { "field": "total", "reason": "notInEncoding", "chars": "€",
      "font": "Helvetica", "page": 1 }
  ],
  "notReplaced": []
}

Placeholders outside the page content

A template may carry its placeholders in places other than the drawn text. TextReplace reports them in notReplaced and leaves them alone, so that the application can update them with the methods made for them:

"notReplaced": [
  { "field": "customer", "where": "metadata" },
  { "field": "trackingUrl", "where": "linkTarget" }
]

Saving, signatures and permissions

• apply changes the PDF in memory; call WriteFile or WriteBd to save it. The file is written as a full rewrite, so earlier revisions holding the old values are discarded.
• Signed PDFs. Rewriting the page content invalidates signatures, so apply is refused on a signed PDF while the PreserveSignatures property is true (the default). Set it to false to replace text in a signed PDF and accept that its signatures become invalid. check works on any PDF.
• Encrypted PDFs. The PDF must have been opened (UserPassword / OwnerPassword), and apply requires owner rights or the modify permission. Chilkat does not ignore owner restrictions.
• After apply, ExtractText returns the new values, and the fonts' ToUnicode maps are extended so that the new text is searchable and copyable in viewers.

Option reference

{
  "pages": "all",
  "placeholderSyntax": "{{name}}",
  "placeholders": { "name": "value", ... },
  "labels": [ { "label": "Invoice #:", "value": "INV-1", "occurrence": "first" }, ... ],
  "align": "auto",                    // auto | left | right | center
  "unusedPlaceholders": "error",      // error | blank | keep
  "unmatchedValues": "error"          // error | ignore
}

Reference documentation: Pdf.TextReplace. Related: ExtractText, Watermark, Protection, Optimize, Pdf class overview.