Form scripts
editMany 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.JavaScriptRead the scripts
var total = form.FindField("Total")!;
var calculate = total.Actions.Calculate?.Script;
var order = form.CalculationOrder;
var documentScripts = document.JavaScripts;- Actions gives the keystroke, format, validation and calculation scripts of a field.
- CalculationOrder lists the calculated fields in the order a viewer calculates them.
- JavaScripts gives the document-level scripts, which usually declare the functions the fields call.
- PdfTextField.SetValue sets a value and the text its appearance shows, as a format script does: the value keeps
1234.5while the field shows$1,234.50.
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:
- The keystroke script of the field, then its validation script: when one sets
event.rc = false, the value is rejected (IsAccepted isfalse) and nothing changes. - The calculation scripts of the form, in the calculation order.
- 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 onthisis 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
eventobject, the fields (this.getField, withvalue,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.scandandapp.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.willCommitistrue): there is no typing. - The appearance properties a script sets on a field (
textColor,display...) are ignored.