Generatore PDF da modelli JSON

Con questo modulo è possibile generare dei file PDF partendo da file di testo contenenti una valida sintassi JSON, che possono essere localizzati sia nella cartella della singola azienda (quindi caricati dal pannello PARAMETRI dell’area partner come file generico) oppure nell’area comune dei pattern.

La generazione deve avere uno o più oggetti di partenza, ad esempio può essere un modello basato su un cliente, o su un articolo, una lista di scadenze dell’estratto conto, un ordine.

La definizione JSON è un array di oggetti JSON che devono avere obbligatoriamente l’attributo type che può identificare:

• t = testo semplice non interpretato, nel cui attributo text potrei trovare ad esempio “Denominazione”
• p = testo pattern interpretato sul tipo di oggetto di partenza, nel cui attributo text potrei trovare ad esempio “Codice: [code]”
• c = testo in cella con allineamento e bordi
• d = dettaglio, permette di inserire un riquadro al cui interno vengono rappresentati degli oggetti figlio, ad esempio più scadenze dell’estratto conto cliente, o righe di un documento
• f = firma grafica, che viene richiesta all’utente nel momento in cui si genera il documento
• i = immagine, in cui potrei trovare un attributo url per prelevare online da un indirizzo web o un attributo file in cui potrei trovare ad esempio “logo.png” oppure “[imm1]”
• l = linea
• q = riquadro
• r = rettangolo pieno
• s = impostazioni pagina del documento
• u = testo che viene richiesto all’utente in fase di generazione
• x = definizione di coordinate parametriche [top_0]…[top_9] e [left_0]…[left_9] richiamabili dagli altri elementi, questo tipo di oggetto non ha attributo “z” e viene interpretato sempre per primo

Tutti o quasi gli oggetti hanno degli attributi universali che quindi non saranno riportati su ognuno dei tipi, e sono:

• page = numero di pagina su cui l’elemento deve apparire, valore default 1, oppure “all” se deve apparire su tutte, “last” se deve apparire solo sull’ultima pagina oppure “notlast” se deve apparire su tutte le pagine tranne l’ultima, in assenza di questo parametro l’elemento viene rappresentato solo nella prima pagina elaborata;
  il numero di pagine effettivo del file può dipendere sia dal massimo attributo “page” assegnato agli elementi, sia dalle pagine autogenerate quando un elemento di tipo “d” dettaglio crea nuove pagine per esaurimento dello spazio verticale
• x = distanza dal bordo sinistro in millimetri, quindi generalmente nel range 5-205, può essere un numero, o una stringa che può combinare variabili [left_0]…[left_9] e pattern interpretati, ad esempio “[p_PDF_LEFT_CLIENTE]-[left_5]”, può anche contenere valori decimali
• y = distanza dal bordo superiore in millimetri, quindi generalmente nel range 5-292, anch’esso può essere un numero o combinare [top_0]…[top_9], pattern e operazioni aritmetiche anche con decimali
• z = ordinamento di profondità, con range 1-100, per cui un valore più piccolo viene aggiunto nel documento prima e quindi va sullo sfondo, il valore default è 0 quindi in assenza di parametro esplicito gli elementi vengono inseriti per primi
• include = se specificato, è un pattern che viene valutato sull’oggetto corrente, se restituisce stringa non vuota allora l’elemento viene stampato, altrimenti viene ignorato
  esempio di testo incluso solo se il documento è stato generato in modalità cliente:
  { “type”: “p”, “include”: “[moda;regexs=^C$;regexr=C;regexm=1;regexend]”, “x”: 10, “y”: 20, “text”: “Grazie per aver usato la nostra app!” }
• exclude = opposto di include, se il pattern interpretato sull’oggetto restituisce una stringa non vuota, allora l’elemento viene ignorato
  esempio di testo escluso se il cliente ha già un codice assegnato nel gestionale
  { “type”: “p”, “exclude”: “[codc]”, “x”: 10, “y”: 20, “text”: “L’approvazione del nuovo cliente è a discrezione della ditta” }

Tipo “d” (dettaglio oggetti secondari)

Blocco di dettaglio con le proprie coordinate x, y, w, h per definire i contorni del blocco. Contiene un array “elements” contenente gli elementi da valutare per ognuno degli oggetti figlio, le coordinate di ogni definizione vengono traslate rispetto al punto alto a sinistra del blocco, e in verticale viene aggiunto un ulteriore spostamento verso il basso pari al valore della proprietà “h2” per ognuno degli oggetti figlio (ad esempio una scadenza di estratto conto, una riga di documento).

• x = distanza del blocco di dettaglio dal margine sinistro
• y = distanza del blocco di dettaglio dal margine superiore
• w = larghezza del blocco di dettaglio
• h = altezza del blocco di dettaglio
• h2 = spostamento fra una riga e la successiva all’interno del blocco di dettaglio
• cols = opzionale, default 1, numero di colonne per le quali dividere lo spazio “w” mettendo gli elementi in riga e andando a capo ogni “cols” elementi aggiunti, quindi lo spazio di ogni elemento sarà di (w/cols)*h2
• index = opzionale, serve se al generatore arrivano diversi array di elementi figli che hanno indici da 0 a seguire, non viene usato quando si usano relazioni univoche fra l’oggetto principale e gli oggetti figli (es. le righe di un documento, oppure le rate sospese di un cliente)
• top_out = opzionale, se valorizzato con un numero da 0 a 9, scrive o rimpiazza la variabile (es. [top_5]) corrispondente con l’altezza massima raggiunta dall’ultimo elemento processato, permette di usare la variabile calcolata per rappresentare altri elementi appena finisce l’ultimo elemento, senza lasciare lo spazio vuoto fino a (y+h)
• elements = array di definizioni interpretate su ognuno degli oggetti del blocco di dettaglio, le coordinate di ognuno degli elementi (x, y, x2, y2) vengono traslate in base alla riga e colonna effettiva dello specifico elemento, e non all’angolo superiore sinistro della pagina
  • ognuno degli oggetti contenuti in “elements” può avere un attributo even opzionale che, se valorizzato a 0 fa apparire l’elemento grafico solo sulle righe di dettaglio dispari, mentre se valorizzato a 1 lo fa apparire solo sulle righe di dettaglio pari, può essere ad esempio usato per aggiungere un riquadro a colori alterni dietro le righe di dettaglio; il conteggio è a base 1 e tiene conto anche dell’eventuale attributo “cols” per cui tutti gli elementi figli fino ad esaurimento delle colonne disponibili condividono il comportamento “even”;
  • gli elementi figli possono avere attributi include, exclude autonomi, e tutti i propri tag vengono interpretati rispetto all’oggetto figlio

Il blocco di dettaglio inizia nella pagina corrente o comunque nella pagina indicata dal suo attributo “page” e si estende automaticamente alle pagine successive se il numero di elementi è maggiore di (cols)*floor(h/h2).

Tipo “f” (firma dell’utente)

Casella in cui viene inserita una firma autografa che viene richiesta al momento della generazione del documento.

Non deve essere usato invece per disegnare una firma apposta in precedenza a un documento app già salvato, per la quale invece occorre usare un oggetto di tipo “i” (immagine) con l’attributo “base64” valorizzato a “[firm]”, meglio ancora se con l’attributo “include”:”[firp]” per ignorare totalmente il blocco se il documento non ha firma.

• x, y = coordinate dell’angolo alto a sinistra della casella in cui viene inserita la firma
• w = larghezza del riquadro firma
• h = altezza del riquadro firma

Tipo “i” (immagine)

Blocco immagine che può essere presa da un URL internet specificando l’attributo url oppure può cercare un file locale scaricato nella cartella interna delle foto specificando l’attributo file, che non deve contenere obbligatoriamente il nome ma può anche essere un pattern che viene interpretato sulla base dell’oggetto di origine, ad es. “[imm1]” che preleva l’URL della foto principale di un articolo, “[imm2]” la prima delle foto aggiuntive ecc…

In aggiunta alle proprietà x e y, l’oggetto ha anche:

• w = larghezza dell’immagine
• h = altezza dell’immagine
• base64 = dati Base64 contenente i byte di immagine JPG o PNG, prioritario rispetto all’attributo “file” o “url”
• file = nome del file che viene cercato nella cartella immagini locale, viene anche interpretato come pattern se il nome grezzo non esiste, ad esempio può contenere “[imm1]” perché venga interpretato con il nome della prima immagine di un articolo
• url = url da cui recuperare l’immagine, una volta scaricata viene mantenuta in locale e non è possibile forzare il download di un file con lo stesso nome
• ratio = se valorizzato a 1 mantiene le proporzioni dell’immagine adattandola nel contenitore specificato da w e h, lasciando eventuale spazio non riempito
• dpi = se valorizzato insieme a ratio=1, con valore ad esempio 150, forza il ridimensionamento dell’immmagine per occupare meno spazio nel formato PDF

Gli errori di caricamento immagine non bloccano la generazione ma vengono accumulati in una lista messaggi consultabile a fine generazione.

Tipo “l” (linea)

Linea disegnata a partire dal punto di coordinate x,y fino al punto di coordinate x2, y2. In alcune delle implementazioni, ad esempio esportando in PNG o JPG, la linea sarà disegnata solo se retta, quindi con x=x2 oppure y=y2.

Altri attributi:

• color = colore della linea in valore esadecimale, default nero 0x000000
• w = spessore della linea, default 0.1

Tipo “p” (testo interpretato)

Testo interpretato sull’oggetto di partenza, ad esempio se sto generando il PDF partendo da un articolo posso usare i tag [code], [desc], [imm1], [pric], [note] per ottenere rispettivamente gli attributi codice, descrizione, url dell’immagine principale, prezzo, dettagli. Gli attributi sono gli stessi del tipo “t” quindi text e size ma anche w e wrap se devo andare a capo.

Se l’interpretazione di text produce una stringa vuota vengono tentati gli attributi “text2”, “text3” e così via, fino a che non si ottiene un testo interpretato non vuoto, oppure fino a che l’attributo “textN” cercato non esiste o è vuoto.

Tipo “t” (testo semplice)

Testo semplice non interpretato con gli attributi:

• text = stringa da scrivere senza interpretarla con GestoreDescrizioni
• size = grandezza del carattere, opzionale, default 10, può anche essere un pattern tipo [p_PDF_FONT_DITTA;default=14]
• w = larghezza della cella nel caso sia abbinato all’opzione wrap per andare a capo automaticamente, può essere un numero, o una stringa che combina ad esempio “[left_4]+15” o un parametro interpretato tipo “[p_PDF_LEFT_CLIENTE]-5”, vengono prima risolte le variabili e poi effettuate le operazioni aritmetiche
• wrap = se valorizzato a 1 porta il testo a capo se supera la larghezza massima impostata, con interlinea default (anche con versioni 26.06.xx), se valorizzato invece con valori da 2 o superiore, usa il valore specificato come interlinea (solo da versione app 26.06.08)

Tipo “u” (testo immesso da utente)

Testo liberamente immesso dall’utente al momento della compilazione, è necessario il parametro “text” contenente la richiesta che sarà presentata all’utente e il resto dei parametri sono in comune con il tipo “t” o “p”. Il testo immesso viene interpretato come pattern prima di essere aggiunto al documento quindi se l’utente immette il testo [oggi] questo tag viene sostituito con la data odierna.

Se il modulo chiamante non fornisce una callback per richiedere all’utente il testo, questo elemento viene ignorato.

Tipo “x” (coordinate parametriche)

Un oggetto con “type”:”x”, “left”:”0″,”value”:”10″ crea una variabile [left_0] che si può usare dentro ogni attributo x di altri elementi anche sommandolo a valori o altre variabili.

Un oggetto con “type”:”x”, “top”:”1″,”value”:”40″ crea ad esempio la variabile [top_1] e così via, potendo creare da top_0 a top_9 e da left_0 a left_9.

Una volta definite le variabili si può quindi definire un oggetto di tipo “c” (cella) con attributo “x”:”[left_0]+10″, “w”:”[left_1]-[left_0]” e intervenire solo sulle definizioni di left_0 e left_1 per modificare le coordinate di tutti gli elementi che le referenziano.