-

hierachy. Not compatible with page.bookmarks.destinations=true page.format=A4 – specified target page format (e.g. A6 , LETTER ) page.hyperlinks=true – enables a conversion of HTML hyperlinks to active PDF hyperlinks page.orientation=false – by true rotates given target page format to 90 degrees (e.g. portrait to landscape) pdf.forms.enable=false – enabled a conversion of HTML forms to submittable native PDF forms. pdf.pdfa=false – enables PDF/A output pdf.protect.pud=false – forces PD4ML to keep HTML object sizes given in physical units (mm, pt, in etc) in resulting PDF, independently on HTML-to-PDF scale factor proxy.host= – proxy host address (if needed) proxy.port=0 – proxy port (if needed) style.add= – CSS style string to be applied to loaded documents ttf.fonts.default.monospace= – default monospaced font. Not recommended, use CSS style for that instead ttf.fonts.default.sansserif= – default Sans Serif font. Not recommended, use CSS style for that instead ttf.fonts.default.serif= – default Serif font. Not recommended, use CSS style for that instead ttf.fonts.dir= – location of TTF fonts dir directory with pd4fonts.properties index file userSpace.adjustToContent=false – if true , forces PD4ML to set htmlWidth value to the measured width of the HTML content. Suggest edit Last updated on October 28, 2018 4. PD4ML Java API # API Documentation Each release of PD4ML comes with actual JavaDocs. When you use Maven for dependency management, your IDE will automatically download the JavaDocs JARs and when you hover on a PD4ML class or method, show you the corresponding documentation. For reference we also publish the API documentation online so you can link to it from emails or websites: https://pd4ml.tech/javadoc/com/pd4ml/PD4ML.html Pre-Requisites The following are the pre-requisites needed to use the PD4ML Java API library: * JDK installed on your PC * Apache Maven build automation tool * Eclipse installed on your PC (While Eclipse is not compulsory it is highly recommended) * PD4ML Java API can be downloaded from our website directly (or let Maven do that automatically) * PD4ML evaluation license Developing your first application Creating blank Maven Java project As a good starting point we recommend to create a blank Java project as described in the tutorial: https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html After you’ve got the example application to run, let’s add to it PD4ML. First add PD4ML library dependency to project’s pom.xml . See lines 17-22 below: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 4.0.0 com.mycompany.app test-pd4ml jar 1.0-SNAPSHOT test-pd4ml http://maven.apache.org junit junit 3.8.1 test com.pd4ml pd4ml [1.0.0,) org.apache.maven.plugins maven-compiler-plugin 3.1 1.7 1.7 pd4ml https://pd4ml.tech/maven2/ true In order to resolve the dependency, add a location of PD4ML repository. The right location for the repository address is $HOME/.m2/settings.xml (See Maven documentation). We’ll keep the example configuration simpler and add the repository info to pom.xml , despite it is not a recommended practice. See lines 37-45 in the example above. If you own PD4ML license with product source code access, use https://pd4ml.tech/maven2-src/ as the repository URL. You would also need to configure the repository access credentials (login/password pair) obtained from the license email. Also for runtime environment simplicity we’ll add the example PD4ML API calls to the application test suite. A typical test case class looks like the example: 1. 2. 3. 4. public class AppTest extends TestCase { public AppTest(String testName) { super(testName); } 5. public static Test suite() { return new TestSuite(AppTest.class); } 6. 7. 8. 9. public void testApp() { } 10. 11. 12. } We are going to extend testApp() method with PD4ML usage example code. Creating a PD4ML object When writing an application with PD4ML API, the very first thing to do is to create the PD4ML object: 1. 2. 3. 4. 5. try { PD4ML pd4ml = new PD4ML(); } catch (Exception e) { e.printStackTrace(); } The constructor in the example has no parameters and it expects to find license pd4ml.lic file in the working dir of the application or in the root folder of the classpath or of pd4ml*.jar . Alternatively you may pass to PD4ML constructor a string with a serial number (obtained from the license email) or a string with an URL of an alternative pd4ml.lic location. Where to obtain pd4ml.lic ? Download it from your license page or save the serial number from the license email to a text file and name the file pd4ml.lic Reading HTML After you’ve got an instance of PD4ML you can read and parse a source HTML document with one of a variety of readHTML() methods. In the example it reads from a prepared input stream. But it can also read from an arbitrary URL. 1. 2. 3. String html = "Hello, World!"; ByteArrayInputStream bais = new ByteArrayInputStream(html.getBytes()); 4. 5. 6. // read and parse HTML pd4ml.readHTML(bais); If you want to point the converter to a font directory or to apply an additional style, headers, footers, watermarks etc – the corresponding API calls need to be performed before readHTML() Writing target format A parsed source document can be rendered as a sequence of images, PDF or RTF documents. Here it writes a PDF: 1. 2. File pdf = File.createTempFile("result", ".pdf"); FileOutputStream fos = new FileOutputStream(pdf); 3. 4. 5. // render and write the result as PDF pd4ml.writePDF(fos); Launching default document viewer (optional) It is rarely needed in real-life applications, but very handy in our case: lookup for a default viewer and launch it for just generated PDF. 1. 2. // open the just-generated PDF with a default PDF viewer Desktop.getDesktop().open(pdf); It looks for a viewer, associated with given file extension. For PDF it launches Adobe Reader (or similar). If we write to a file with .rtf extension it likely launches MS Word or WordPad First PD4ML application complete The application, in its entirety, is as follows: 1. package com.mycompany.app; 2. 3. 4. 5. 6. import import import import java.awt.Desktop; java.io.ByteArrayInputStream; java.io.File; java.io.FileOutputStream; 7. 8. import com.pd4ml.PD4ML; 9. 10. 11. 12. import junit.framework.Test; import junit.framework.TestCase; import junit.framework.TestSuite; 13. 14. 15. 16. 17. public class AppTest extends TestCase { public AppTest(String testName) { super(testName); } 18. 19. 20. 21. public static Test suite() { return new TestSuite(AppTest.class); } 22. 23. 24. 25. public void testApp() { try { PD4ML pd4ml = new PD4ML(); 26. 27. 28. 29. String html = "Hello, World!"; ByteArrayInputStream bais = new ByteArrayInputStream(html.getBytes()); 30. 31. 32. // read and parse HTML pd4ml.readHTML(bais); 33. 34. File pdf = File.createTempFile("result", ".pdf"); FileOutputStream fos = new FileOutputStream(pdf); 35. 36. // render and write the result as PDF pd4ml.writePDF(fos); 37. 38. 39. // alternatively or additionally: // pd4ml.writeRTF(rtfos, false); // BufferedImage[] images = pd4ml.renderAsImages(); 40. 41. 42. 43. // open the just-generated PDF with a default PDF viewer Desktop.getDesktop().open(pdf); 44. 45. 46. } catch (Exception e) { e.printStackTrace(); } 47. 48. 49. } 50. 51. } Running the application Now we are ready to run the demo application. Go to the Maven project root (where pom.xml is) and execute the command line: 1. mvn test The test target builds the projects and runs its test suite. As our example code is implemented as a test case, it will be executed. If you did everything correct you’ll see a PDF viewer window with a generated PDF file in it: The document is minimalistic and built using PD4ML defaults: A4 page format, 10mm margins, 727px htmlWidth, no TTF fonts. 727px are calculated from (A4.width - margins.left - margins.right) * PIXELS_PER_POINT , which is (595pt - (10mm + 10mm) * 2.835pt/mm) * 1.35px/pt Customizing the conversion PDF page format and content scaling There are 3 important PD4ML properties, impact resulting PDF page format and layout: pageSize , pageMargins , htmlWidth . pageSize defines output paper format: A4 , ISOB4 , LETTER , LEGAL etc. Corresponding constants are defined in java.pd4ml.Constants class, but you may define any non-standard page dimension with, for instance, new com.pd4ml.PageSize(400,400) (by default the dimensions are in typographic points) and pass it to pd4ml.setPageSize() method. Default page format is A4 , orientation portrait . PDF file format does not explicitly specifies on meta level if a particular page is landscape landscape– or portrait portrait-oriented. If a page has its width greater than height – it is landscape, otherwise it is portrait. com.pd4ml.PageSize implements a page rotation by a simple swapping of page height and width. pageMargins define blank page area width around the page content. The default value for it new PageMargins(10, 10, 10, 10, Units.MM) The page margins can be additionally increased by HTML document margins (e.g. ). The HTML document margins have some specifics, when converted to PDF: the top margin is applied to the top of the document (in other words, on the first page only), the bottom margin on the last page only. Document with no margins: htmlWidth value defines "virtual web browser" frame width (in screen pixels), and by default for A4 it is 727px (to keep 1:1 scale factor by 72dpi). PD4ML renders source HTML page using htmlWidth parameter and maps the resulting layout to the efficient PDF page width (which is pageFormat.width - pageMargins.left - pageMargins.right ). That makes HTML-to-PDF scale factor computed like that: scale = (pageFormat.width - pageInsets.left - pageInsets.right) / htmlWidth From the above it is obvious, that an increasing of htmlWidth makes the resulting document content appears smaller. Examples: htmlWidth = 920 htmlWidth = 1320 Defining page header and footer setPageHeader() and setPageFooter() methods are used to define page headers/footers using HTML as a layout definition. Optional scope parameter allows to apply particular header or footer to a specified range of pages. The HTML code may include the placeholders: $[page] – to be substituted with current page number; $[total] – total number of pages; $[title] – document title as defined in

Hello, World!

Hello, New Page!

Comments: Line 1. Make sure there is no whitespaces before the directive start (before <%@ ). The taglib is intended to return a PDF (binary) file. Any content or whitespace (incl. new line characters) before implicitly switches HTTP output to text mode and prefixes the PDF bytes with unexpected characters. As the last resort PD4ML taglib tries to reset such undesired content (if any), but it is not possible in all environments and java.lang.IllegalStateException: getOutputStream() has already been called for this response is thrown. Other symptoms of the undesired content are either corrupted PDF, or PDF, which is always being reindexed when opened by a PDF Viewer. Line 2 and 3 No characters or whitespaces between tags or directives allowed (See %><% and %> <%@page contentType="text/html; charset=ISO8859_1"%> Hello, World! Defining PDF document footer (or header) with JSP custom tag. Since PD4ML v4.0.0 a dedicated header/footer JSP custom tags are not supported anymore. Instead of it use PD4ML proprietary and tags (they take effect not only in JSP context, but also in regular HTML). Identically you may define a watermark with tag. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. <%@ taglib uri="http://pd4ml.com/tlds/4.0" prefix="pd4tl"%><%@page contentType="text/html; charset=ISO8859_1"%> $[title] Visible only on the first page Page $[page] of $[total] Page 1 Page 2 Comments: Line 13 Page header definition, whose scope is limited only by the first page. $[title] placeholder is to be substituted with a title value taken from HTML’s