Da modulo compilabile a record congelato: compilazione e flatten di AcroForm

Spec: ISO 32000-2, §12.7

In sintesi

Un modulo PDF ha due vite. Prima è compilabile: un insieme di campi tipizzati in cui una persona digita, spunta o sceglie. Poi, quando l’accordo è fatto, diventa un record congelato: i valori sono stampati nella pagina stessa così che ogni lettore, su ogni dispositivo, veda esattamente ciò che è stato concordato. NextPDF costruisce la prima e produce il secondo, con una garanzia deliberata — non getterà via in silenzio i valori lungo il tragitto.

Perché è importante

Il divario tra «ciò che ho compilato» e «ciò che vedi» è dove i moduli vanno storti.

Un campo compilabile è, tecnicamente, un piccolo widget interattivo disegnato sopra la pagina. Lettori diversi possono renderizzarlo in modo diverso. Alcuni onorano un valore salvato, altri rigenerano l’aspetto da un font che non si possiede, altri permettono a un lettore di modificarlo di nuovo. Per una bozza che si vuole far continuare a modificare ai collaboratori, quello è il punto. Per la copia firmata di ciò che è stato concordato, è una responsabilità: il record non dovrebbe dipendere da quale applicazione lo apre, e non dovrebbe essere modificabile a posteriori.

Il flatten chiude il divario. Prende il valore attuale di ciascun campo e lo dipinge nella pagina come grafica ordinaria e immutabile — lo stesso tipo di contenuto di un’intestazione o di un logo. Dopodiché, non c’è alcun campo da modificare e alcun aspetto da rigenerare. Il documento mostra una sola cosa, la stessa cosa, ovunque.

In breve

Un AcroForm è il modulo interattivo del documento: un albero di campi tipizzati dichiarati nel catalog (Spec: ISO 32000-2, §12.7).
Ciascun campo è reso visibile da una widget annotation — il rettangolo sulla pagina su cui si clicca o si digita (Spec: ISO 32000-2, §12.5).
NextPDF fornisce builder tipizzati per ogni controllo di modulo non-firma supportato — text, checkbox, radio, list box e combo box (choice), e push button — più un field manager che li scrive come oggetti PDF appropriati.
Il flatten renderizza il valore di ciascun campo nel content stream della pagina e rimuove il modulo interattivo ormai ridondante, lasciando un record congelato.
Se si chiede di appiattire un documento che non ha pagine, NextPDF non distrugge silenziosamente i valori dei campi. Conserva il modulo, avvisa, e permette di aggiungere una pagina e appiattire correttamente.

Come NextPDF lo affronta

Il modello mentale è di due strati. Il campo è il dato: un nome, un tipo, un valore e un insieme di flag. Il widget è l’immagine: un rettangolo su una pagina specifica che permette a un lettore di interagire con il campo (Spec: ISO 32000-2, §12.5). Un campo può persino emergere attraverso più widget — è esattamente così che funziona un gruppo radio, diverse scelte sulla pagina collegate a un unico valore sottostante.

NextPDF dà a ciascun tipo di campo il proprio builder tipizzato, così che non si assembli mai a mano un dizionario grezzo. Il tipo porta per l’utente i dettagli PDF-corretti. Una checkbox, un radio button e un push button condividono tutti lo stesso tipo di modulo sottostante nella specifica e si distinguono dai loro flag; il motore imposta quei flag dal tipo scelto, anziché chiedere di ricordare quale bit significa «radio». Un list box e un combo box sono entrambi campi choice; di nuovo, il builder sceglie la codifica corretta. Si dichiara il tipo di campo una volta, a parole, e i byte seguono.

Il flatten è la seconda metà. L’appiattitore raggruppa le widget annotation per la pagina che le possiede, usando il rettangolo di ciascun widget per il posizionamento su quella pagina, poi renderizza ciascun valore come una piccola sequenza di operatori di content stream — imposta un colore, imposta una posizione del testo, disegna i glifi — accodata al contenuto esistente di quella pagina (Spec: ISO 32000-2, §8.4). Il valore smette di essere un campo vivo e diventa inchiostro dipinto. Poiché il modulo non porta più alcun campo interattivo, il motore rimuove quindi la voce AcroForm: non resta più nulla su cui essere interattivi.

Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

From a fillable form to a frozen record: declare typed fields, draw their on-page widgets, fill in values, then flatten those values into immutable page graphics and drop the now-empty interactive form.

Esempio pratico

Un modulo piccolo e rappresentativo: si costruiscono alcuni campi tipizzati, poi lo si appiattisce in un record congelato.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

Prima di flattenForms(), questo è un modulo compilabile. Dopo, gli stessi valori sono dipinti nella pagina e non resta alcun campo da cambiare. Si sceglie il tipo di campo scegliendo il suo metodo builder — textField, checkBox, comboBox — così che un tipo sbagliato non possa essere codificato come una stringa generica: un refuso è una chiamata a un metodo che non esiste, colta prima che qualsiasi campo sia scritto, non un campo silenziosamente sbagliato. È la stessa postura rifiuta-di-indovinare che adotta il resto del motore; si veda un’API che si rifiuta di indovinare.

Equivoco comune

La trappola è credere che compilare un campo lo congeli. Non lo fa. Un campo compilato porta ancora un valore vivo che un lettore capace può modificare, e un aspetto che alcuni lettori rigenereranno. «Ho impostato il valore» e «il documento è ora un record fisso» sono due stati diversi. Solo il flatten passa dall’uno all’altro, perché solo il flatten trasforma il valore in grafica di pagina che non si comporta più come un campo.

L’errore speculare è appiattire una bozza su cui si ha ancora bisogno di raccogliere input. Una volta appiattiti, i campi sono spariti — è tutto il punto — quindi si appiattisca la copia che si intende rendere definitiva, non quella che si sta ancora facendo circolare.

C’è una sfumatura di operabilità che vale la pena conoscere. Se si chiede al motore di appiattire un documento che non ha pagine, esso non cestina silenziosamente i valori dei campi. Non c’è alcuna superficie di pagina su cui dipingerli, quindi invece di spogliare il modulo interattivo e azzerarne i valori — una perdita di dati totale e invisibile — NextPDF conserva il modulo, mantiene ogni valore intatto e ancora interattivo, e fa emergere un avviso che dice cosa è successo. Si aggiunge una pagina e si appiattisce di nuovo. Questo è un progetto deliberato senza perdita di dati: il motore preferisce restituire un documento ancora compilabile e un avviso chiaro piuttosto che uno svuotato in silenzio. I valori che ti sono stati affidati sono l’unica cosa che un flatten non deve mai gettare via.

Limiti e confini

Il supporto ai moduli di NextPDF è pieno core: builder tipizzati per i comuni controlli di campo interattivi, un appiattitore di moduli e un field manager che scrive i campi come oggetti PDF appropriati. Questa pagina descrive quella superficie core.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	Builder tipizzati per campi text, checkbox, radio, choice (list box e combo box) e push-button; posizionamento dei widget; un field manager; e un appiattitore di moduli che incorpora i valori nella grafica di pagina. Disponibile in ogni edizione.
Pro	Not in this edition
Enterprise	Not in this edition

Il flatten è a senso unico per progetto. Rimuove il modulo interattivo così che il record sia fisso; non è un interruttore «blocca temporaneamente», e non esiste un un-flatten che ri-deriva campi modificabili dalla grafica dipinta. Se serve una copia che le persone possano continuare a modificare, si conservi il modulo non appiattito e si appiattisca un duplicato.

Il flatten inoltre non è una firma. Rende un documento non modificabile nel senso del lettore ordinario, ma non prova crittograficamente chi lo ha prodotto né che non sia cambiato da allora. Quando il record deve essere dimostrabilmente quello concordato, si appiattisca e poi si firmi; si veda come le firme stanno in un PDF.

Infine, un modulo taggato e accessibile è una preoccupazione separata da uno appiattito. Se la versione compilabile deve essere usabile con tecnologia assistiva, i campi necessitano di nomi e struttura accessibili mentre sono ancora interattivi; si veda cosa rende un PDF accessibile.

Documenti correlati

Cosa rende un PDF accessibile — campi di modulo taggati e nomi accessibili, per la fase compilabile.
Un’API che si rifiuta di indovinare — perché il tipo di campo è un enum tipizzato, non una stringa che il motore deve interpretare.
L’anatomia di un file PDF — dove vivono davvero il catalog, le pagine e le annotation da cui è costruito un modulo.
Come le firme stanno in un PDF — come rendere un record congelato dimostrabilmente quello concordato.

Glossario

AcroForm — il modulo interattivo di un PDF: l’albero di campi tipizzati dichiarati nel document catalog che rende il file compilabile (Spec: ISO 32000-2, §12.7).
Campo — il lato dato di un controllo di modulo: un nome, un tipo, un valore e flag. Indipendente da come appare sulla pagina.
Widget annotation — il rettangolo visibile e cliccabile su una pagina attraverso cui un lettore interagisce con un campo (Spec: ISO 32000-2, §12.5). Un campo può averne diversi.
Campo choice — un campo che offre un insieme di opzioni: un list box le mostra aperte, un combo box mostra un menu a tendina. Entrambi sono lo stesso tipo di campo PDF.
Flatten — renderizzare il valore attuale di ciascun campo nella pagina come grafica immutabile e rimuovere il modulo interattivo, producendo un record congelato.
Record congelato — un documento appiattito: mostra una sola cosa fissa in ogni lettore e non ha più campi da modificare.