Template

Documenti ed etichette come template con versioni: codici, struttura, espressioni, draft, versioni pubblicate e rollback.

Un template descrive un documento: la pagina, i dati e il layout. Lo progetti nel Designer, lo pubblichi come versione immutabile e le tue applicazioni lo generano tramite il suo codice con l'API.

Che cos'è un template

Un template ha poche proprietà proprie e un elenco di versioni, ognuna con una definizione completa:

codicetestoobbligatorio: Come lo indicano le applicazioni: DDT_STANDARD, FATTURA. Unico nel workspace, non cambia mai.
formatoDocumento PDF · Etichetta ZPL: Si sceglie alla creazione; l'editor non lo cambia mai.
descrizionetesto: Il nome mostrato in Prynt (fino a 400 caratteri).
tipo documentoelenco: DDT, Fattura, Ordine, Conferma d'ordine, Preventivo, Packing list, Scheda prodotto, Etichetta, Report, Componente o Altro: per filtrare e organizzare.
statoAttivo · Disattivato: Un template disattivato non si può generare.
versione correnteintero: La versione pubblicata che l'API genera quando una richiesta non ne indica una.

Proprietà di un template
Campo	Tipo	Descrizione
`codice`obbligatorio	testo	Come lo indicano le applicazioni: DDT_STANDARD, FATTURA. Unico nel workspace, non cambia mai.
`formato`	Documento PDF · Etichetta ZPL	Si sceglie alla creazione; l'editor non lo cambia mai.
`descrizione`	testo	Il nome mostrato in Prynt (fino a 400 caratteri).
`tipo documento`	elenco	DDT, Fattura, Ordine, Conferma d'ordine, Preventivo, Packing list, Scheda prodotto, Etichetta, Report, Componente o Altro: per filtrare e organizzare.
`stato`	Attivo · Disattivato	Un template disattivato non si può generare.
`versione corrente`	intero	La versione pubblicata che l'API genera quando una richiesta non ne indica una.

La definizione di una versione contiene l'impostazione della pagina, i parametri, i dataset con le loro relazioni, le traduzioni e il layout (oppure, per un'etichetta, l'etichetta).

Documenti PDF ed etichette ZPL

Documento PDF: documenti a bande come DDT, fatture, ordini, certificati e report, generati in PDF su A4, A5, A3, Letter, Legal o un formato personalizzato.
Etichetta ZPL: etichette per stampanti termiche Zebra, generate come codice ZPL che la stampante esegue, a 203, 300 o 600 dpi. Hanno un editor dedicato; vedi Etichette ZPL.

Tutto il resto è comune ai due formati: parametri, dataset, espressioni, versioni, pubblicazione e API. Per trasformare un'etichetta PDF in un'etichetta ZPL crei un nuovo template.

Componenti

Un template di tipo Componente è un blocco riutilizzabile, per esempio l'intestazione aziendale, che si inserisce in altri template con l'elemento Sottoreport. Riceve per nome i parametri del template che lo include. Quando un template viene pubblicato, la versione corrente del componente viene fissata al suo interno, così le modifiche successive al componente non alterano i documenti pubblicati. Si possono annidare fino a 3 livelli di componenti.

Il codice del template

Lettere maiuscole, cifre, _, . e -, iniziando con una lettera o una cifra, al massimo 100 caratteri (gli spazi diventano _ mentre scrivi). I nomi riservati di Windows (CON, NUL, COM1…) sono rifiutati.
È unico nel workspace e non si può cambiare: è il contratto stabile con le tue applicazioni. Per avere un template con un altro codice, lo cloni.
Tienilo breve e significativo: FATTURA, DDT_STANDARD, ETICHETTA_SSCC.

Struttura di un documento

Un documento PDF è impaginato in bande, strisce orizzontali misurate in millimetri:

Intestazione paginabanda: Su ogni pagina (o solo su alcune: prima, tutte tranne la prima, ultima, tutte tranne l'ultima).
Intestazione reportbanda: Una volta, all'inizio del documento.
Corposezioni: Bande statiche, stampate una volta, e data region, che si ripetono per ogni record di un dataset.
Piede reportbanda: Una volta, alla fine (totali, firme).
Piede paginabanda: Su ogni pagina: numeri di pagina, note legali.

Bande di un documento
Campo	Tipo	Descrizione
`Intestazione pagina`	banda	Su ogni pagina (o solo su alcune: prima, tutte tranne la prima, ultima, tutte tranne l'ultima).
`Intestazione report`	banda	Una volta, all'inizio del documento.
`Corpo`	sezioni	Bande statiche, stampate una volta, e data region, che si ripetono per ogni record di un dataset.
`Piede report`	banda	Una volta, alla fine (totali, firme).
`Piede pagina`	banda	Su ogni pagina: numeri di pagina, note legali.

Una data region scorre un dataset, con filtro e ordinamento facoltativi, una propria intestazione e un proprio piede, una banda Nessun dato, gruppi (un'espressione chiave, intestazione e piede di gruppo) e region annidate collegate da una relazione.
Gli elementi stanno nelle bande: testo, campo, immagine, linea, rettangolo, tabella, barcode (Code 128, Code 39, EAN-13, EAN-8, UPC-A, ITF, Data Matrix, PDF417), QR Code, numero pagina, totale pagine e sottoreport.
Le bande possono crescere e ridursi con il contenuto, evitare di dividersi tra due pagine e forzare i salti pagina; le tabelle si spezzano tra le righe e ripetono l'intestazione.

Collegamenti, espressioni e formati

Gli elementi si collegano ai dati con un linguaggio di espressioni piccolo e sicuro (nessuna esecuzione di codice, nessun ciclo). I campi e le condizioni contengono l'espressione così com'è; i testi includono le espressioni tra doppie graffe.

CLIENTE.RAGSOCcampo: Un campo di un dataset.
Params.DOCUMENT_IDparametro: Un parametro del template.
RIGHE.QTA * RIGHE.PREZZOcalcolo: Aritmetica con decimali esatti.
sum(RIGHE.IMPORTO)aggregato: sum, count, avg, min, max, first, last, con un ambito facoltativo: report, region, group, page.
Pagina {{PageNumber}} di {{TotalPages}}testo: Un testo con espressioni incluse.
if(T.PAGATO, "Pagato", "Da pagare")funzione: Funzioni su testi, numeri, date e condizioni; t("CHIAVE") per le traduzioni.

Espressioni in un template
Campo	Tipo	Descrizione
`CLIENTE.RAGSOC`	campo	Un campo di un dataset.
`Params.DOCUMENT_ID`	parametro	Un parametro del template.
`RIGHE.QTA * RIGHE.PREZZO`	calcolo	Aritmetica con decimali esatti.
`sum(RIGHE.IMPORTO)`	aggregato	sum, count, avg, min, max, first, last, con un ambito facoltativo: report, region, group, page.
`Pagina {{PageNumber}} di {{TotalPages}}`	testo	Un testo con espressioni incluse.
`if(T.PAGATO, "Pagato", "Da pagare")`	funzione	Funzioni su testi, numeri, date e condizioni; t("CHIAVE") per le traduzioni.

Un formato su un campo usa le stringhe di formato .NET: #,##0.00, dd/MM/yyyy, d MMMM yyyy. Numeri e date seguono la lingua della generazione (IT, EN, DE, FR, ES): 1.234,50 in italiano, 1,234.50 in inglese. Visibile se nasconde un elemento o una banda in base a una condizione, e i formati condizionali cambiano colore, sfondo, grassetto o corsivo. La guida del Designer ha altri esempi.

Draft e versioni

Modifichi sempre il draft; un template ne ha al massimo uno. Il salvataggio è esplicito (Ctrl+S) e le tue applicazioni non vedono mai il draft.
Pubblica controlla il draft con il motore: gli errori bloccano la pubblicazione, gli avvisi no. Aggiungi una nota e il draft diventa una versione pubblicata con il numero successivo (1, 2, 3…) e la versione corrente. Viene inviato un webhook template.published.
Una versione pubblicata è immutabile e autosufficiente: le query condivise vengono copiate al suo interno, componenti e immagini vengono fissati al loro contenuto di quel momento. Nulla di ciò che cambia dopo altera un documento pubblicato.
Per modificare un template pubblicato crei un nuovo draft da una versione (oppure spunti Crea subito un nuovo draft dalla versione pubblicata quando pubblichi), lo modifichi e pubblichi di nuovo.

Dalla generazione successiva

L'API usa la nuova versione corrente dalla richiesta successiva: non c'è nulla da distribuire. Le richieste che indicano una versione continuano a generare quella versione finché è pubblicata.

Cronologia delle versioni e rollback

Versioni nel Designer elenca tutte le versioni con stato (Bozza, Pubblicata, Archiviata), nota e date; la stella indica la versione corrente. Per ogni versione puoi aprirla in sola lettura, creare un nuovo draft, esportarla, oppure:

Rendi corrente (rollback): l'API torna subito a generare quella versione pubblicata. Il rollback sposta solo il puntatore; nessuna versione viene modificata.
Archivia / Ripristina dall'archivio: una versione archiviata non può diventare corrente finché non viene ripristinata e l'API smette subito di generarla, anche per le richieste che la indicano; la versione corrente non si può archiviare. Una versione archiviata resta consultabile in sola lettura e in anteprima.
Confronta due versioni affiancate.

Pubblicare, fare rollback e archiviare richiedono il permesso templates.publish (developer, admin, owner); modificare i draft richiede templates.write (designer e ruoli superiori). Le versioni pubblicate non vengono mai eliminate.

Clonare, disattivare, eliminare, esportare

Clona: un nuovo template con un altro codice, a partire dal draft o da una versione pubblicata, con una copia degli asset propri del template.
Disattiva: l'API rifiuta di generare il template (409 TEMPLATE_DISABLED) finché non lo riattivi.
Elimina: toglie il template dal workspace; il suo codice torna disponibile. Un componente usato da altri template non si può eliminare.
Esporta .prynt / Importa: un pacchetto con la definizione e le sue immagini, per spostare un template in un altro workspace o in un'altra installazione, come nuovo template o come nuovo draft di uno esistente.

I template nell'API

Le applicazioni generano un template tramite il suo codice; la versione è quella corrente, salvo che la richiesta ne indichi un'altra, e l'ambiente decide solo quali database leggere:

Genera la versione correnteShell

curl -X POST https://api.prynt.it/api/v1/render \  -H "Authorization: Bearer prynt_live_..." \  -H "Content-Type: application/json" \  -d '{ "template": "DELIVERY_NOTE", "parameters": { "DOCUMENT_ID": 18425 } }' \  -o delivery-note-18425.pdf

X-Template-Version nella risposta indica quale versione è stata generata.
GET /v1/templates elenca i template pubblicati e attivi; GET /v1/templates/{code} ne restituisce uno con i suoi parametri (e il loro JSON Schema) e i dataset.
Un template senza versioni pubblicate risponde 404 TEMPLATE_NOT_PUBLISHED; un codice sconosciuto 404 TEMPLATE_NOT_FOUND; un formato che non corrisponde al template (pdf per un'etichetta) 422 FORMAT_MISMATCH.
Una richiesta che indica una versione genera solo una versione pubblicata: una versione archiviata risponde 409 VERSION_ARCHIVED; un draft o un numero inesistente 404 VERSION_NOT_FOUND.

Vedi il riferimento API.