Scrivere un modello

Un modello è il tuo documento di sempre, con dei segnaposto dove vanno i dati. Lo scrivi con il programma che usi già - Word per un DOCX, un qualsiasi editor per un file HTML, Excel per un XLSX - e lo carichi; ogni generazione lo compila con il JSON di quella chiamata. Una regola da ricordare:

Campi e oggetti

{
  "number": "2026-000147",
  "customer": {
    "name": "Acme Srl",
    "city": "Milan"
  }
}

Fattura n. {{ number }}

Cliente: {{ customer.name }}
Città:   {{ customer.city }}

Un campo alla radice del JSON si scrive con il suo nome; un campo dentro un oggetto si raggiunge con un punto, annidato quanto serve ({{ customer.address.city }}). Lo stesso segnaposto può comparire più volte in un documento.

Scriverne uno, dall'inizio alla fine

1. Parti dal documento che mandi già - una fattura, un contratto, una lettera - impaginato esattamente come deve apparire.
2. Sostituisci ogni parte variabile con un segnaposto che porta il nome del suo campo nel JSON. In Word scrivi ogni segnaposto tutto di seguito: modificarlo a metà lo divide senza che si veda (Errori comuni).
3. Ripeti una riga per ogni elemento di una lista con un ciclo (Liste e righe ripetute), e mostra una parte solo quando serve con una condizione (Parti condizionali).
4. Spunta caselle, metti immagini e grafici dai dati: le caselle di spunta qui sotto, immagini e grafici in Far stare un valore nello spazio.
5. Segna dove firma ciascun firmatario se il documento sarà firmato: i tag di firma qui sotto.
6. Caricalo, poi Valida e Anteprima nella console: Valida confronta un JSON di esempio con ciò che il file chiede, e Anteprima mostra il PDF finito, con la filigrana. Nessuno dei due costa credito.

In Word, in HTML, in Excel

Quale formato per quale documento, e che cosa sa fare ciascuno: Che cosa sa fare ogni formato.

Grassetto, font e impaginazione vengono dal modello

Un valore arriva come testo semplice e prende l'aspetto del punto in cui finisce. Tutta la formattazione si scrive nel modello stesso:

• Word: formatta il segnaposto. Metti {{ customer.name }} in grassetto, o dagli un font, una dimensione o un colore, e il valore esce così. Formatta allo stesso modo l'intero segnaposto, graffe comprese.
• HTML: il tuo markup e il tuo CSS, per esempio <strong>{{ customer.name }}</strong>. Un valore è sempre stampato come testo: se i dati contengono <b>, il documento mostra quei caratteri, non diventa grassetto.
• Excel: il formato della cella (font, riempimento, formato numerico).

Nel JSON non c'è nulla da scrivere per mettere un valore in grassetto, e non c'è un codice di formattazione per farlo. **parole** in un valore si stampa così com'è, asterischi compresi: i doppi asterischi sono capiti solo nel messaggio di un'email di richiesta di firma (Scrivere il messaggio), mai in un documento. Numeri e date si stampano come arrivano: mandali già formattati (Far stare un valore nello spazio che gli hai lasciato).

Dove firma un firmatario

Un documento che sarà firmato dice dove, con un tag scritto allo stesso modo: {{ signature.A }} posiziona la firma del firmatario la cui chiave è A nei signers della richiesta; {{ signature.A.name }} e {{ signature.A.date }} posizionano il suo nome e la data. Il tag non stampa nulla ed è tolto dal PDF finito. Dimensioni, le regole e l'alternativa con le coordinate: Dove va la firma sulla pagina.

Spuntare una casella (Word)

Una casella di spunta in un modello Word si imposta con un true o false con lo stesso nome nei dati:

"data": { "consenso": true, "newsletter": false }

• Dai un nome alla casella: una casella di modulo tradizionale (Sviluppo → Strumenti legacy) con il suo segnalibro, nelle sue proprietà; un controllo contenuto casella di controllo (Sviluppo → Casella di controllo) con il suo Tag, oppure il suo Titolo. Maiuscole e minuscole non contano.
• true la spunta, false la toglie.
• Nessuna chiave, oppure null: la casella resta esattamente com'è nel modello.
• Qualsiasi altra cosa ("yes", 1) non viene interpretata: la casella resta com'è, e gli avvisi della risposta dicono che il valore di una casella non era true o false.

La pagina del modello nella console elenca le caselle che ha trovato accanto ai suoi campi, così vedi quali nomi possono impostare i dati; un tag di firma ({{ signature.A }}) non è elencato fra i dati da inviare, perché indica dove firma un firmatario, non un valore.

Si leggono solo i nomi alla radice dei dati. In un modello HTML la casella la scrivi tu, per esempio {{ '☒' if consenso else '☐' }}.

Gestire i modelli da uno script: Gestire i modelli da uno script. Righe ripetute: Liste e righe ripetute. Se/altrimenti: Parti condizionali. Adattare un valore allo spazio che gli hai lasciato: Far stare un valore nello spazio che gli hai lasciato. Risoluzione dei problemi a partire dal sintomo: Errori comuni. Il PDF si fa con font liberi: quali font mantengono l'impaginazione di Word.