PDFarm 3.1 Tutorial

Indice

Cos'è PDFarm

Torna all'indice
PDFarm è un tool che permette di generare PDF partendo da un documento XML a cui si farà riferimento nella guida con il termine PHTML.
La struttura PHTML è molto simile al ben noto HTML sia per facilitare e velocizzare l'apprendimento dello sviluppatore nella definizione del layout grafico che per adattarsi all'esigenze tipiche di un documento cartaceo.
Il tool è stato realizzato in Java ed è rivolto agli sviluppatori e web designer che necessitano di aggiungere la funzionalità di generazione di documenti PDF nella propria applicazione.
La semplicità del tool rende PDFarm uno strumento rapido per la costruzione di layout grafici complessi ma flessibili.

Come installare PDFarm

Torna all'indice
Il tool PDFarm "Web service" non necessita di alcuna installazione ma richiede di disporre di un servizio hosting che supporti almeno un linguaggio di programmazione con cui sia possibile effettuare una chiamata remota al server PDFarm (es. PHP, .NET, JAVA, C++, Perl, Phyton, etc...). Ricevuta la chiave di utilizzo è sufficiente effettuare una chiamata HTTP POST al server PDFarm specificando i parametri chiave PDFarm e codice PHTML, ottenendo così il relativo PDF.

Il tool PDFarm "Server edition" invece necessita di una breve installazione.
Come prima cosa è bene verificare di avere installata una Java Virtual Machine 1.5.0 o superiore (consigliata 1.6.0 o sucessiva). E' possibile verificare tale requisito eseguendo il comando:

> java -version

Per maggiori informazioni o per scaricare Java clicca qui: http://java.sun.com/javase/downloads/

Per installare PDFarm Server Edition è sufficiente scaricare il file zip dal pannello utente dello shop online, estrarlo in una cartella a piacere ed eseguire la procedura guidata per l'attivazione della licenza tramite il comando:

> java -classpath "path/to/PDFarm.3.1_XXX_server.jar" it.kiwiage.pdfarm.License

La procedura guidata di attivazione della licenza va effettuata tramite un computer connesso a internet (la procedura di attivazione è eseguibile anche su un computer diverso dal server finale di destinazione di PDFarm) ed è necessario munirsi di:
- chiave di attivazione (reperibile nella mail di conferma dell'acquisto)
- MAC address di una interfaccia di rete installata sul server di destinazione di PDFarm (se diverso dal computer da cui viene lanciato il comando)
Al termine della procedura viene generato il file license.dat (nella directory da cui si è eseguita la procedura di attivazione) che permette di utilizzare PDFarm Server Edition.

nota: la generazione del file license.dat può avvenire UNA SOLA VOLTA e deve essere associato ad un singolo MAC address.

Per verificare la corretta attivazione della licenza di PDFarm Server Edition eseguire il comando:

> java -jar path/to/PDFarm.3.1.jar --check-license

Per visualizzare tutte le opzioni eseguire il comando

> java -jar path/to/PDFarm.3.1.jar --help

Struttura del documento PHTML

Torna all'indice
Ogni documento PHTML deve iniziare con il tag:

<?xml version="1.0" encoding="UTF-8"?>

Nel valore dell'attributo encoding deve essere indicato il tipo di codifica del documento PHTML (i.e. 'ISO-8859-1', 'UTF-8', etc).
Per utilizzare le entità HTML (i.e. '&amp' , '&copy;' ecc.) all'interno del documento PHTML è necessario aggiungere come seconda riga:

<!DOCTYPE phtml SYSTEM "PDFarm.dtd">

Dopo l'intestazione deve seguire il tag <phtml></phtml> al cui interno verranno definite le quattro sezioni head, header, body e footer:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE phtml SYSTEM "PDFarm.dtd">
<phtml>
	<head>
	...
	</head>
	<header>
	...
	</header>
	<body>
	...
	</body>
	<footer>
	...
	</footer>
</phtml>
Nel tag <phtml> è possibile configurare le proprietà subject, title e author, questi valori compariranno all'interno delle proprietà del documento generato.
Inoltre sono configurabili i margini della pagina, il formato (A0,A1,...,B0,B1,..., letter, legal) e l'orientamento (portrait, landscape). In fase di sviluppo, può essere utile porre a true l'attributo guidelines per tracciare le linee guida della struttura del documento PDF.
La sezione head può solo contenere le configurazioni iniziali attraverso l'uso del tag <set>.
Le sezioni header e footer sono utilizzate per definire le parti di layout che compariranno rispettivamente come testata e piè di pagina. I contenuti inseriti in queste due sezioni saranno ripetuti in ogni pagina del documento. Specificando l'attributo showFromPage è possibile indicare quale deve essere la prima pagina a contenere l'header o il footer (utile in caso di documenti con copertina).
Il contenuto vero e proprio del documento deve essere inserito all'interno della sezione body.
Esempi:

Testo e font

Torna all'indice
Il testo può essere inserito liberamente all'interno delle sezioni header, footer e body.
E' possibile utilizzare il tag <p> per creare dei paragrafi, ma non sono per ora previsti attributi per la configurazione di tale oggetto.
Il font utilizzato di default è il Times-roman dimensione 12. Tramite il tag <set> è possibile modificare le proprietà di default del testo come il font, la dimensione, il colore e lo stile, es:

<head>
...
...
<set key="fontsize" value="10"/>
<set key="font" value="Helvetica"/>
</head>

NOTA: Utilizzando questo tag all'interno della sezione head, avrà effetto su tutte le sezioni body, header e footer.
Se il tag <set> viene utilizzato internamente alle sezione body, header e footer, avrà effetto solo sulla sezione coinvolta.
La libreria PDFarm include quattro font interni: Time-roman, Helvetica, Courier, Symbol.
E' possibile inoltre specificare la codifica dei font con il comando: <set key="fontencoding" value="Cp1252">.

N.B.: E' possibile utilizzare altri font, purchè presenti sul server che esegue PDFarm Server Edition precaricandoli con il tag:
<set key="fontdir" value="c:/windows/fonts" />
Con questa operazione PDFarm analizzerà nella cartella specificata tutti i file di tipo True Type Font e li renderà disponibili all'utilizzo nel documento PDF.
Per allegare un particolare font nel documento è possibile utilizzare il tag:
<set key="fontembedded" value="Verdana">
Le chiavi "fontdir", "fontembedded" e "fontencoding" possono essere utilizzate solo nella sezione <head>. La chiave"fontencoding" deve precedere tutte le altre chiavi, mentre "fontembedded" deve seguire "fontdir", come nell'esempio seguente: 
<head>
	<set key="fontencoding" value="Cp1252"> <!-- "Cp1252" è il valore di default, questo comando è supefluo -->
	<set key="fontdir" value="c:/windows/fonts/" />
	<set key="fontembedded" value="Verdana" />
</head>
Se occorre applicare delle proprietà solo ad una piccola parte del testo, si consiglia l'utilizzo dei tag <font>, <b>(grassetto), <i>(corsivo), <u>(sottolineato),<sub>(pedice), <sup>(apice).
Per inserire testi ruotati di un qualsiasi angolo utilizzare il tag <rotatetext>.
Esempi:

Immagini

Torna all'indice
I formati inseribili sono JPEG, PNG o GIF. È supportato il canale 'alpha' (trasparenza) nel formato GIF, anche parziale nel formato PNG.
Per inserire un'immagine utilizzare il tag <img>. Come risorsa è possibile indicare nell'attributo src un percorso locale (e.s.:"c:/images/logo.jpg", utilizzabile in PDFarm Server Edition) oppure un percorso remoto (e.s.:"http://sito.it/images/logo.jpg"). Inoltre possono essere specificati i bordi (border, borderright, borderstyle, bordercolor, ecc ), l'angolo di rotazione (angle), il fattore di scala (scale) o, in alternativa l'attributo autoresize che adatta automaticamente le dimensioni dell'immagine alla dimensione dell'area disponibile.
Alcuni tags come <body>, <header>, <footer> e <td> supportano l'attributo img per aggiungere un'immagine di sfondo al relativo oggetto. Tramite l'attributo repeat si può ripetere l'immagine di sfondo all'interno del contenitore in senso orizzontale (repeat-x), verticale (repeat-y) o in entrambi i sensi (repeat). Il valore di default è no-repeat.
Esempi:

Tabelle

Torna all'indice
Le tabelle sono probabilmente gli oggetti più utili nel PHTML in quanto, oltre alla creazione di classiche griglie, sono adatte per impostare il layout dei componenti.
In maniera analoga all'HTML, la tabelle PHTML usano la struttura <table>-<tr>-<td>: 
<table>
	<tr>
	<td>r1c1</td>
	<td>r1c2</td>
	<td>r1c3</td>
	</tr>
	<tr>
	<td>r2c1</td>
	<td>r2c2</td>
	<td>r2c3</td>
	</tr>
</table>
All'interno delle celle è possibile inserire qualsiasi componente, comprese tabelle annidate.
Nel tag <table> tutti gli altri attributi configurano i valori di default delle celle, eccetto l'attributo width che indica la larghezza in percentuale della tabella rispetto allo spazio disponibile (default 100%) e l'attributo headerRows che specifica il numero di righe dell'header della tabella (ovvero le righe che verranno automaticamente replicate quando la tabella viene rappresentata su più pagine). Per esempio indicando <table align="center">, i contenuti delle celle all'interno della tabella saranno di default allineati centralmente.
Esempi:

Links & Liste

Torna all'indice
I links sono creati tramite il tag <a> il quale può contenere testo oppure un' immagine.
Nel link è possibile specificare, attraverso l'attributo href , un riferimento interno al documento (ancora) o un URL.
Per creare un' ancora nel documento si deve specificare l'attributo name.
Per creare una lista si utilizzano i tag <ul> (undordered list), <ol> (ordered list) e <li> (list item): 
<a href="http://www.pdfarm.net">Homepage sito PDFarm</a>
<a href="dopoLista">Salta la lista</a>

<ul>
	<li>item1</li>
	<li>item2</li>
	<li>item3</li>
</ul>
<ol>
	<li>item1</li>
	<li>item2</li>
	<li>item3</li>
</ol>

<a name="dopoLista">Fine lista di esempio</a>
Esempi:

Componenti speciali

Torna all'indice

Campi editabili

Il tag <input>permette di creare, all'interno del documento, un componente compilabile dall'utente. È possibile creare aree di testo ( specificando type="text") o caselle di controllo ( type="checkbox") definendone il layout grafico (bordi, sfondo, rappresentazione grafica, valore di default, dimensioni, stato iniziale, ecc).
Esempio:

Campi pagina

Esempio:

Esempi completi

Torna all'indice