Moduł IText służy do tworzenia dokumentów w formacie PDF.
Konfiguracja
Moduł nie jest automatycznie dołączany do każdej instancji. Aby skorzystać z modułu IText należy w pliku konfiguracyjnym instancji umieścić wpis
<module name="itext"/>
Moduł IText wymaga ponadto umieszczenia na serwerze jPALIO plików z czcionkami w formacie TTF
Tworzenie dokumentu PDF
Szkielet każdego dokumentu PDF generuje następujący kod jPALIO
$itext.createDocument("A4", true)
$itext.setMetaData("Autor", "Tytuł")
$// ...
$itext.openDocument()
$itext.addParagraph("")
$// ...
$=(PDF, $itext.closeDocument())
Funkcja createDocument(String, Boolean) tworzy nowy dokument i ma 2 argumenty: pierwszym jest format dokumentu (A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, B1, B2, B3, B4, B5, LETTER, HALFLETTER, ARCH_A, ARCH_B, ARCH_C, ARCH_D, ARCH_E, _11x17, LEGAL, NOTE, LEDGER, FLSA, FLSE), drugim orientacja strony (true - pionowa, false - pozioma). Istnieją jeszcze inne warianty tej funkcji. Są to: createDocument(String, Boolean, Object), której trzecim argumentem po formacie dokumentu i orientacji strony jest kolor tła - nazwa lub tablica trzech wartości z zakresu od 0 do 255, createDocument(Long, Long), której pierwszym argumentem jest szerokość a drugim wysokość dokumentu oraz createDocument(Long, Long, Object), której trzecim argumentem po szerokości i wysokości dokumentu jest kolor tła - nazwa lub tablica trzech wartości z zakresu od 0 do 255.
Funkcja setMetaData(String, String) ustawia metadane dokumentu i przyjmuje dwa argumenty: pierwszym jest autor, drugim tytuł dokumentu.
Funkcja openDocument() otwiera dokument. Od momentu wywołania tej funkcji możliwe jest wprowadzanie treści do dokumentu.
Funkcja closeDocument() zamyka dokument i zwraca jego treść w postaci tablicy bajtów, którą następnie można wypisać na stronie binarnej lub zapisać do bazy danych w zależności od potrzeb.
Dodatkowo pomiędzy wywołaniami funkcji createDocument i openDocument można ustawić wielkości marginesów, wykorzystując do tego celu funkcję setMargins(Long, Long, Long, Long, Boolean), której pierwsze 4 argumenty to szerokości marginesów: lewego, prawego, górnego i dolnego wyrażone w punktach, a piąty argument określa czy dokument ma być przystosowany do wydruku dwustronnego (zamiana marginesu lewego z prawym na nieparzystych stronach).
UWAGA Wywołanie $itext.addParagraph("") umieszczone w ciele dokumentu tworzy pusty paragraf. Pusty paragraf nie zajmuje miejsca w dokumencie, ale zapewnia, że jeśli ciało dokumentu będzie puste to zostanie wygenerowany prawidłowy pusty dokument PDF.
Umieszczenie tekstu w dokumencie
Do umieszczania tekstu w dokumencie służą metody setFont, addText, addTextAligned i addParagraph.
Metoda setFont ustawia czcionkę tekstu w danym kontekście dokumentu - wskazuje plik czcionki oraz pozwala określić jej rozmiar, styl, kolor i kodowanie znaków. Przed umieszczeniem jakiejkolwiek treści w dokumencie konieczne jest ustawienie czcionki za pomcą metody setFont.
Metody addText i addTextAligned umieszczają tekst w danym kontekście dokumentu. Istnieje możliwość bezwzględnego pozycjonowania tekstu z określeniem sposobu wyrównania włącznie. Dokumenty PDF mają rozdzielczość 72 dpi - jeżeli dokument ma format A4 (210 × 297 mm) to rozmiar strony w pikselach wynosi 595 × 842 px. Pozycja (0, 0) to lewy dolny róg strony dokumentu.
Metoda addParagraph tworzy nowy akapit tekstu określając wyrównanie tekstu, wcięcia i odstępy. Treścią akapitu może być ciąg znaków lub wynik wykonania kodu jPALIO.
Dodatkowo do sterowania rozmieszczeniem tekstem można wykorzystać bezargumentową metodę newPage realizującą przejście do nowej strony dokumentu PDF.
Tworzenie tabel
Do tworzenia tabel służy metoda addTable. Określa ona liczbę komórek w wierszu tabeli, wyrównanie tabeli, jej szerokość, wielkości odstępów czy powtarzanie nagłówka.
W kodzie jPALIO generującym ciało tabeli wykorzystuje się metodę addTableCell, która tworzy komórkę tabeli. Kolejne wiersze tabeli są tworzone automatycznie - kiedy liczba komórek utworzonych kodzie jPALIO generującym ciało tabeli przekroczy zadeklarowaną liczbę komórek w wierszu, wówczas zostanie utworzony kolejny wiersz, w którym będą umieszczane kolejne komórki.
Do ustalenia szerokości kolumn tabeli można posłużyć się metodą setColumnWidths, której argumentem jest tablica szerokości komórek (wartości względne).
Tworzenie wypunktowań
Do tworzenia wypunktowań używana jest funkcja addList, która określa sposób wypunktowania (NUMBERS - liczby, LETTERS - litery, SYMBOL - symbole), szerokość miejsca na symbole (w punktach), początkowy symbol oraz wielkości wcięć.
Elementy wypunktowania tworzy się za pomocą metody addListItem, która określa wyrównanie elementu oraz odstępy i wcięcia.
Umieszczanie grafiki w dokumencie
Do umieszczania grafiki w dokumencie PDF służy funkcja addImage(byte[], Object[]), której pierwszym parametrem jest tablica bajtów reprezentująca zawartość pliku graficznego (np. odczytaną z bazy danych), a drugim tablica następujących parametrów: wyrównanie obrazka (LEFT lub 0, MIDDLE lub 1, RIGHT lub 2, UNDERLYING lub 8, TEXTWRAP lub 4), bezwzględne położenie obrazka na stronie w punktach (tablica dwóch wartości: odległość od lewej i odległość od dołu), tryb skalowania (ABSOLUTE, PROPORTIONAL, PERCENT), wielkość obrazka w punktach lub procentach, zależnie od trybu skalowania (tablica dwóch wartości: szerokość i wysokość), obrót obrazka w stopniach (jeśli ma zostać użyta wartość domyślna danego parametru w tablicy, należy w miejscu tego parametru wstawić wartość null; tablica nie musi zawierać wszystkich parametrów - może być krótsza).
Nagłówek i stopka
Do umieszczania w dokumencie nagłówka i stopki, które będą się powtarzać na każdej stronie dokumentu służą metody setHeader i setFooter odpowiednio. Wywołania powyższych funkcji w kodzie muszą być umieszczone przed wywołaniem metody openDocument. Nagłówek i stopka są traktowane jako tabele, dlatego pierwszym argumentem każdej z tych metod jest ilość komórek takiej tabeli, a drugim kod jPALIO generujący kolejne komórki. W kodzie jPALIO należy korzystać z funkcji addTableCell.
Tworzenie dokumentu przy wykorzystaniu szablonu
Moduł IText pozwala również na tworzenie dokumentu przy wykorzystaniu istniejącego szablonu (pliku PDF). Tworzenie dokumentu w tym przypadku polega na pobraniu stron szablonu, osadzeniu ich w generowanym dokumencie i pozycjonowaniu tekstu na osadzonym szablonie.
Aby w tworzonym dokumencie wykorzystać stronę z istniejącego szablonu należy odczytać treść szablonowego dokumentu korzystając zmetody readDocument, której argumentem jest binarna zawartość istniejącego dokumentu PDF (szablonu). Metoda zwraca tablicę obiektów, z których każdy reprezentuje pojedynczą stronę szablonu. Następnie aby umieścić stronę szablonu w tworzonym dokumencie należy użyć metody addTemplate, której pierwsze dwa argumenty określają położenie strony szablonu na stronie tworzonego dokumentu (w poziomie i w pionie), a trzeci reprezentuje obiekt pojedynczej strony szablonu (element tablicy zwróconej przez readDocument). Ostatnią czynnością jest pozycjonowanie tekstu na szablonie. Do tego celu służy omówione wcześniej metody addText i addTextAligned.
Szczególnym przykładem szablonu może być kod kreskowy stworzony za pomocą metody createBarcode.
Przykładowy dokument PDF (kod źródłowy do umieszczenia na stronie binarnej)
$itext.createDocument("A4", true)
$itext.setMetaData("jPALIO S.A.", "Zaświadczenie")
$itext.setMargins(30, 30, 30, 30, false)
$itext.setHeader(1, {
$itext.setFont("/opt/jpalio/fonts/times.ttf", 8)
$itext.addTableCell([0, 0, 1, 1], "____________________________________________________________________________________________________________________________________")
})
$itext.setFooter(1, {
$itext.setFont("/opt/jpalio/fonts/times.ttf", 8)
$itext.addTableCell([0, 0, 1, 1], "____________________________________________________________________________________________________________________________________")
})
$itext.openDocument()
$itext.addTable(2, 0, 100, {
$itext.setFont("/opt/jpalio/fonts/times.ttf", 12)
$itext.addTableCell(0, "jPALIO S.A.\nul. Joteyki 20\n02-317 Warszawa")
$itext.setFont("/opt/jpalio/fonts/times.ttf", 12)
$itext.addTableCell([0, 0, 1, 2], "Warszawa, 1 stycznia 2010")
$itext.setFont("/opt/jpalio/fonts/timesbd.ttf", 14)
$itext.addTableCell([0, 0, 1, 0, 6, 24], "Nr Z676/2008")
$itext.addTableCell(0, "")
})
$=(IMAGE, $sql.readLine("select content from p_media where code = 'media.images.emblem.jpg'"))
$itext.addImage((byte[])$IMAGE[0], [null, [247, 675], "ABSOLUTE", [100, 100]])
$itext.setFont("/opt/jpalio/fonts/timesbd.ttf", 20)
$itext.addParagraph(1, [32, null, 48, 48], "Zaświadczenie")
$itext.addParagraph(3, [20, 20], {
$itext.setFont("/opt/jpalio/fonts/times.ttf", 16)
$itext.addText("Tekst tekst tekst tekst tekst tekst tekst ")
$itext.setFont("/opt/jpalio/fonts/timesbd.ttf", 16)
$itext.addText("tekst tekst ")
$itext.setFont("/opt/jpalio/fonts/times.ttf", 16)
$itext.addText("tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst tekst.")
})
$itext.addList("NUMBERS", 20, [], {
$itext.setFont("/opt/jpalio/fonts/times.ttf", 16)
$=(@counter, 1)
$for(7, {
$itext.addListItem(0, $+(["Punkt ", $@counter]))
$++(@counter)
})
})
$itext.setFont("/opt/jpalio/fonts/times.ttf", 8)
$itext.addTable(2, 0, [100, null, 100], {
$itext.addTableCell(0, "")
$itext.addTableCell([0, 0, 1, 1, 4], "...........................................................................\npieczęć i podpis")
})
$writeBinary($itext.closeDocument())
Używanie szablonów na przykładzie kodów kreskowych EAN13 (kod źrółowy do umieszczenia na stronie binarnej)
$itext.createDocument("A4", true)
$itext.setMetaData("jPALIO S.A.", "Kod kreskowy")
$itext.openDocument()
$=(@barCode, "1234567890123")
$=(@barCodeTemplate, $itext.createBarcode($@barCode, "EAN13"))
$itext.addTemplate(100, 740, $@barCodeTemplate)
$itext.setFont("/opt/jpalio/fonts/times.ttf", 10)
$itext.addText(105, 730, $@barCode)
$writeBinary($itext.closeDocument())