Form scripts

edit

Many forms calculate fields from others (a total from quantities and prices) and format values (currencies, dates) with JavaScript. Meziantou.Framework.Pdf reads these scripts; Meziantou.Framework.Pdf.JavaScript runs them.

dotnet add package Meziantou.Framework.Pdf.JavaScript

Read the scripts

var total = form.FindField("Total")!;
var calculate = total.Actions.Calculate?.Script;
var order = form.CalculationOrder;
var documentScripts = document.JavaScripts;

Run the scripts

CreateScriptSession creates a sandbox that runs the scripts when values are set through it:

using var scripts = document.Form.CreateScriptSession(new PdfFormScriptOptions
{
    Timeout = TimeSpan.FromSeconds(1),
    MaxStatements = 1_000_000,
    MemoryLimit = 64 * 1024 * 1024,
});

scripts.SetValue("Price", "12.5");
var result = scripts.SetValue("Quantity", "3");

SetValue runs the scripts as a viewer does when a user commits a value:

  1. The keystroke script of the field, then its validation script: when one sets event.rc = false, the value is rejected (IsAccepted is false) and nothing changes.
  2. The calculation scripts of the form, in the calculation order.
  3. The format scripts of the fields that changed: their appearances show the text the script gives.

Changes lists each field that changed, with its old value, new value and displayed text. SetValues sets several values and calculates once at the end; Recalculate runs the calculations alone. Save the document to keep the values.

What the scripts can do

  • The scripts never run by themselves: opening a document or setting Value runs none. The document-level scripts run once, when the session is created; the open action never runs. The document-level scripts and the field scripts share the document object (this): what a document-level script declares or sets on this is seen by the field scripts.
  • Setting a field to the value it already has changes nothing: its appearance, written by its format script, is kept.
  • They see the event object, the fields (this.getField, with value, valueAsString, type, readonly...), the AF functions of the viewers (AFSimple_Calculate, AFNumber_Format, AFNumber_Keystroke, AFPercent_*, AFDate_*, AFTime_*, AFSpecial_*, AFRange_Validate, AFMergeChange), util.printf, util.printd, util.scand and app.alert, which calls Alert.
  • The calls that reach outside of the form (submitting, mailing, printing, opening a URL or a document, menu items) do nothing, and are reported in the diagnostics.
  • Each script is limited in time, statements and memory (PdfFormScriptOptions). An error or a limit exceeded is a diagnostic, and the other scripts run, as in the viewers; set ThrowOnScriptError to throw instead.
  • The numbers and the dates are formatted with fixed rules, not with the culture of the machine: the results are the same everywhere. A script may set a read-only field, as calculations do; SetValue refuses it.
  • Only the commit of a value runs the keystroke script (event.willCommit is true): there is no typing.
  • The appearance properties a script sets on a field (textColor, display...) are ignored.