PD4ML v3 to v4 Migration Guide

Software activation is new in PD4ML v4. The activation code enables or disables certain product features, depending on the license you purchased.

To activate the software, you need to either place pd4ml.lic (a text file with an activation code) in your application’s working directory, or in the root of its classpath.

For example, in the context of a web application, this could be /WEB-INF/classes (not WEB-INF/lib). You can also package pd4ml.lic into your application’s JAR, but you’ll have to experiment with this: the hierarchy of EARs, WARs, JARs, etc. can confuse the PD4ML classloader.

Another approach is to pass the activation code itself or the path to the pd4ml.lic file (or even the URL) directly to the com.pd4ml.PD4ML(String) constructor or applyLicense() method.

You can get the activation code or download pd4ml.lic from https://pd4ml.com/view-my-licenses/

The activation code contains information about the available features, as well as the end date of the maintenance period. The code only activates software versions released before the date. If you apply the code to a version of the software released later, it will watermark the generated documents with a “DEMO MODE” banner, just as if you hadn’t applied any activation at all.

Other reasons for the “DEMO MODE” banner is a corrupted activation code or if PD4ML cannot find/read pd4ml.lic for some reason. A verbose diagnostics output triggered by pd4ml.setLogLevel(255) can help to determine what is wrong with the activation.

While PD4ML v3 processes document with a single call pd4ml.render(in, out), PD4ML v4 separates the document conversion process into two phases: input document parsing and output document rendering. It allows to collect input document metadata before the output rendering. Or to reuse parsed input document to produce multiple formats: PDF, RTF, raster images.

The example demonstrates a reading of a source document from an HTML string and a writing of a conversion result to a temp file with PD4ML v4 and v3 API.

PD4ML v4 example relies on default settings of PD4ML: output format is A4, 10mm margins etc. PD4ML v3 has different default margins (T,L,B,R): 25pt, 50pt, 25pt, 25pt

PD4ML pd4ml = new PD4ML();

String html = "TEST<pd4ml:page.break><b>Hello, World!</b>";
ByteArrayInputStream bais =
new ByteArrayInputStream(html.getBytes());

// read and parse HTML
pd4ml.readHTML(bais);

File pdf = File.createTempFile("result", ".pdf");
FileOutputStream fos = new FileOutputStream(pdf);

// render and write the result as PDF
pd4ml.writePDF(fos);

// alternatively or additionally:
// pd4ml.writeRTF(rtfos, false);
// BufferedImage[] images = pd4ml.renderAsImages();

// open the just-generated PDF with a default PDF viewer
Desktop.getDesktop().open(pdf);

PD4ML pd4ml = new PD4ML();

String html = "TEST<b>Hello, World!</b>";
StringReader bais = new StringReader(html);

File pdf = File.createTempFile("result", ".pdf");
FileOutputStream fos = new FileOutputStream(pdf);
// render and write the result as PDF
pd4ml.render(bais, fos);

// open the just-generated PDF with a default PDF viewer
Desktop.getDesktop().open(pdf);

PD4ML v3 specifies the PDF, PDFA, or RTF output document type using the outputFormat() method. PD4ML v4 has special writing methods for certain types: writePDF(OutputStream os, String pdfFormat), writeRTF(OutputStream os), renderAsImages().

There are 3 important PD4ML properties, impact resulting PDF page format and layout: pageSize, pageMargins, htmlWidth.

1. pageSize defines output paper format: A4, ISOB4, LETTER, LEGAL etc.

For both PD4ML v3 and v4 the default page format is A4 and orientation portrait.

2. pageMargins define blank page area width around the page content. The default value for it in PD4ML v4 is new PageMargins(10, 10, 10, 10, Units.MM), while in PD4ML v3 it is new Insets(25, 50, 25, 25); (T,L,B,R in typographical points). So if you’d like to keep the margins as it was in v3, explicitly call pd4ml.setPageMargins(new PageMargins(50, 25, 25, 25, Units.PT)); (L,T,R,B)

3. htmlWidth default value in PD4ML v3 and in v4 is 640px.

With htmlWidth=727px you can achieve 1:1 pixel/point correspondence of 72 DPI resolution. It is calculated from (A4.width - margins.left - margins.right) * PIXELS_PER_POINT, which is (595pt - (10mm + 10mm) * 2.835pt/mm) * 1.35px/pt

4. Default <body> margin in PD4ML v3 is 8px. Can be applied in PD4ML v4 with pd4ml.addStyle("BODY {margin: 8px}", true);

5. PD4ML v3 default PDF view mode can be set in PD4ML v4 with pd4ml.setParam(Constants.PD4ML_DOCUMENT_VIEW_MODE, "OneColumn");

PD4ML pd4ml = new PD4ML();
pd4ml.setParam(Constants.PD4ML_DOCUMENT_VIEW_MODE, "OneColumn");
pd4ml.setHtmlWidth(640);
pd4ml.addStyle("BODY { margin: 8px }", true);
pd4ml.setPageSize(PageSize.A4);
pd4ml.setPageMargins(new PageMargins(50, 25, 25, 25, Units.PT));

The chart shows the correspondence between PD4ML API calls in v3 and v4. The method names are hyperlinked with matching Javadoc entries.

PD4ML v3 supports two types of headers/footers: basic text-only ones (with three output regions: left/center/right) and headers/footers defined with arbitrary HTML. PD4ML v4 does not implement rather redundant text-only headers/footers as they can be easily emulated with HTML code.

More fundamental difference between v3 and v4 is that v3 uses a special class PD4PageMark to define page headers/footers. In v4 the main PD4ML class has the dedicated methods to define page headers/footers with HTML:

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 <title> HTML tag or overridden with setDocumentTitle() API call.

// define page header for the first page 30px high
pd4ml.setPageHeader("$[title]", 30, "1");

// define page footer for the first page
pd4ml.setPageFooter("Total pages: $[total]", 30, "1");

// define page header for the second page
pd4ml.setPageHeader("<b>$[title]</b> $[page]/$[total]", 30, "2+");

// define page footer for the second page
pd4ml.setPageFooter("<div style='width: 100%; text-align: right'>Page: $[page]</div>", 30, "2+");

PD4PageMark header = new PD4PageMark() {
    public String getHtmlTemplate(int pageNumber) {  
        if ( pageNumber == 1 ) {  
            return "<html><body>$[title]";  
        } else {  
            return "<html><body><b>$[title]</b> $[page]/$[total]";  
        }  
    }  
};

PD4PageMark footer = new PD4PageMark() {
    public String getHtmlTemplate(int pageNumber) {  
        if ( pageNumber == 1 ) {  
            return "<html><body>Total pages: $[total]";  
        } else {  
            return "<html><body><div style='width: 100%; text-align: right'>Page: $[page]</div>";  
        }  
    }  
};

header.setAreaHeight(30);
footer.setAreaHeight(30);

// assign page header  
pd4ml.setPageHeader(header);
// assign page footer  
pd4ml.setPageFooter(footer);

Instead of setPageHeader() and setPageFooter() API calls, you may define header/footer code in your source HTML document inline with proprietary <pd4ml:page.header> and <pd4ml:page.footer> tags.

Optional scope attribute allows to apply particular header or footer to a specified range of pages. <pd4ml:page.header> and <pd4ml:page.footer> tags may appear in any location of document body (preferable as a direct child of <body> element) and impact current and subsequent pages until it is overridden again.

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 <title> HTML tag or overridden with setDocumentTitle() API call.

<html>
<head>
<title>Header/Footer example</title>
<style>BODY {font-family: Arial}</style>
</head>
<body>

<!-- inline definition of the header/footer for the current and all following pages -->
<pd4ml:page.header height=30>$[title]</pd4ml:page.header>
<pd4ml:page.footer height=30>Total pages: $[total]</pd4ml:page.footer>

First Page

<pd4ml:page.break>

<!-- here it overrides the header/footer set above starting from the current page -->
<pd4ml:page.header height=30>
<b>$[title]</b> $[page]/$[total]
</pd4ml:page.header>
<pd4ml:page.footer height=30>
<div style='width: 100%; text-align: right'>Page: $[page]</div>
</pd4ml:page.footer>

Second Page
</body>
</html>

Both PD4ML v3 and v4 distributions among other features also include JSP custom tag library. PD4ML JSP custom tags provide a simple mechanism for a converting of HTML or JSP page output into PDF in Web scenarios. In PD4ML v4 the taglib is an integral part of the main library. In PD4ML v3 it comes as a separate pd4ml_tl.jar.

For backward compatibility with JSP documents created for PD4ML v3, you can use pd4ml_tl.jar taken from PD4ML v3 distribution together with PD4ML v4.

But if you want to use the latest taglib, you should consider the following.

In PD4ML v4 we changed the taglib structure and removed some redundant wrapper classes. Now we recommend to use pd4tl: tag prefix instead of previous pd4ml: in order to distinguish the custom JSP tags from PD4ML proprietary tags (e.g. <pd4ml:page.break>).

<%@ taglib uri="http://pd4ml.com/tlds/4.0" 
  prefix="pd4tl"%><%@page 
  contentType="text/html; charset=ISO8859_1"%><pd4tl:transform
  screenWidth="400"
  pageFormat="A5"
  pageOrientation="landscape"
  pageInsets="100,100,100,100,points">
<html>
<head>
<title>pd4ml test</title>
<style type="text/css">
body {
	color: red;
	font-family: Tahoma, "Sans-Serif";
	font-size: 10pt;
}
</style>
</head>
<body>
	<p>
		Hello, World!
	</p>
	<pd4ml:page.break />
	<table style="border: 1px solid gray; border-radius: 5px; background-color: #f8f8f8; color: #000000">
		<tr>
			<td>Hello, New Page!</td>
		</tr>
	</table>
</body>
</html>
</pd4tl:transform>

See https://pd4ml.com/support-topics/pd4ml-v4-programmers-manual/#pd4ml-jsp-taglib-and-web-applications for more PD4ML JSP taglib usage hints.