```
The v42 settings are `"media"` (the CSS media type to lay out for, `"screen"` by default), `"dark"` (`"true"` matches `@media (prefers-color-scheme: dark)`), `"externalResources"` (`"false"` loads no images or style sheets), `"webFonts"` (`"false"` loads no `@font-face` fonts), `"rejectUnitlessLengths"` (`"true"` drops lengths without a unit, such as `width: 600`, outside quirks mode, as browsers do) and `"bevelColorScheme"` (`"chrome"` draws inset/outset/groove/ridge borders in Chrome's colours). Unknown keys are ignored.
### 6.5 The DOM API: reading and changing the document
_From PD4ML v4.2.0, with the v42 layout engine. DMS and UA editions._ Between `readHTML(...)` and the output, [`getDocument()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#getDocument()) returns the parsed HTML document, to read, query with CSS selectors and change; the output is laid out as if the HTML had been written that way. [`layout()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#layout()) lays the document out into pages without writing it and tells where each element ended up:
```java
import com.pd4ml.dom.Document;
import com.pd4ml.dom.Element;
import com.pd4ml.dom.Layout;
pd4ml.useHtmlRenderer(Constants.LayoutEngine.v42);
pd4ml.readHTML(new URL("https://example.com/invoice.html"));
Document doc = pd4ml.getDocument();
doc.getElementById("total").setTextContent("1 250,00 EUR");
for (Element img : doc.querySelectorAll("img:not([alt])")) {
img.setAttribute("alt", "");
}
Layout layout = pd4ml.layout();
if (layout.getPages(doc.getElementById("totals")).size() > 1) { // split over two pages?
doc.getElementById("totals").setAttribute("style", "page-break-before: always");
}
pd4ml.writePDF(out);
```
The classes, in the package [`com.pd4ml.dom`](https://pd4ml.com/javadoc/com/pd4ml/dom/package-summary.html):
| Class | What it gives |
|---|---|
| `Node` | the tree: `getParentNode()`, `getChildNodes()`, siblings, `appendChild()`, `insertBefore()`, `replaceChild()`, `removeChild()`, `remove()`, `cloneNode()`, `getTextContent()`/`setTextContent()`, `toHtml()` |
| `Document` | `getElementById()`, `querySelector()`/`querySelectorAll()`, `getElementsByTagName()`/`getElementsByClassName()`, `getHead()`, `getBody()`, `getTitle()`, `createElement()`, `createTextNode()`, `createComment()` |
| `Element` | attributes (`getAttribute()`, `setAttribute()`, `removeAttribute()`, `getAttributes()`), classes (`addClass()`, `removeClass()`, `toggleClass()`, `hasClass()`), `getInnerHTML()`/`setInnerHTML()`, `getOuterHTML()`/`setOuterHTML()`, `matches()`, `closest()`, child and sibling elements |
| `Text`, `Comment`, `DocumentType` | text (`getData()`, `setData()`, `isWhitespace()`), comments and the doctype |
| `Layout` | from `layout()`: `getPageCount()`, page sizes and numbers, `getBoxes(element)`, `getPages(element)`, `elementAt(page, x, y)`, `getComputedStyle(element, property)` |
| `LayoutBox` | one box of an element: its page, `getX()`, `getY()`, `getWidth()`, `getHeight()` in points from the top left of the page |
Make the changes before the first output: writing a document moves footnotes and endnotes into place in the tree. `layout()` is a snapshot -- after changing the document, call it again. With the v40 engine, or before `readHTML(...)`, both methods throw an `IllegalStateException`.
The full guide, with more examples: [DOM API: Modifying the HTML Document Before Conversion](https://pd4ml.com/docs/features/modifying-the-html-document-before-conversion.html). Runnable examples: [A009ModifyDocumentWithDom.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/advanced/A009ModifyDocumentWithDom.java), [A010ReadLayout.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/advanced/A010ReadLayout.java).
## 7. Page layout: size, margins, and scaling
Three settings govern how source content maps onto printed pages:
| Setting | Meaning | Default |
| ------------- | ---------------------------------------------------------- | --------------- |
| `pageSize` | Target paper format | A4, portrait |
| `pageMargins` | Blank border reserved on every page | 10 mm all sides |
| `htmlWidth` | Virtual viewport width (px) the source is laid out against | 727 px |
```java
import com.pd4ml.PageSize;
import com.pd4ml.PageMargins;
import com.pd4ml.Dimensions.Units;
pd4ml.setPageSize(PageSize.LETTER);
pd4ml.setPageMargins(new PageMargins(15, 20, 15, 20, Units.MM));
pd4ml.setHtmlWidth(1000);
```
Content is scaled uniformly to fit the printable area:
```
scale = (pageWidth - marginLeft - marginRight) / htmlWidth
```
A narrower `htmlWidth` means a larger scale factor -- text and images appear bigger on the page, at the cost of how much content fits horizontally before wrapping. [`pd4ml.adjustHtmlWidth(true)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#adjustHtmlWidth(boolean)) (or the CLI's `-adjustwidth`) instead measures the document's own natural width and uses that, useful for source HTML that isn't already responsive-width-aware.
The scale applies to every size, including those given in physical units: with an `htmlWidth` of 1600 px on A4, `font-size: 12pt` prints at about 5.5pt. [`protectPhysicalUnitDimensions(true)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#protectPhysicalUnitDimensions(boolean)) keeps sizes in `mm`, `cm`, `in`, `pt` and `pc` at their true size while pixel-sized content still scales (v40 engine; the v42 engine always converts physical units at 96 dpi, as browsers do). From PD4ML v4.2.0 it works for DOCX and RTF output too - before, it made physical sizes there about four times too small.
[`setPageSize(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageSize(com.pd4ml.PageSize))/[`setPageMargins(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageMargins(com.pd4ml.PageMargins)) also accept an optional **scope** string (`"1"`, `"2+"`, `"3-7,odd"`, ...) to vary page size or margins across the document -- the same scope grammar used by headers/footers (§8) and by `Pd4Cmd -pagerange`.
[`fitPageVertically(Constants.CENTER_ALIGN)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#fitPageVertically(int)) downscales the entire layout to guarantee it fits one single page, rather than paginating -- handy for "print this as a single-page summary" use cases; it's mutually exclusive with multi-column mode (§10.1).
Runnable example: [E002SetPageFormat.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E002SetPageFormat.java)
## 8. Headers, footers, watermarks, and backgrounds
Repeating page decorations are themselves HTML/CSS fragments, not a separate mini-format to learn:
```java
pd4ml.setPageHeader("$[title]", 30, "1"); // first page only
pd4ml.setPageHeader("$[title] — $[page]/$[total]", 30, "2+"); // every page after
pd4ml.setPageFooter(
"Page $[page] of $[total]
",
24, "1+");
```
Three placeholders are always available: `$[page]` (current page number), `$[total]` (total page count), and `$[title]` (document title). Arbitrary additional placeholders come from [`setDynamicData(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setDynamicData(java.util.Map)):
```java
Map data = new HashMap<>();
data.put("customer", "Acme Corp.");
data.put("invoiceNo", "INV-2026-0031");
pd4ml.setDynamicData(data);
pd4ml.setPageFooter("Invoice $[invoiceNo] — $[customer]
", 24, "1+");
```
A watermark, and a full-bleed page background rendered underneath every page's content, follow the same HTML-fragment-plus-scope model -- the watermark content is itself HTML (an `![]()
`, styled text, or anything else CSS can lay out), not a bare image URL:
```java
pd4ml.setWatermark("
",
50, 50, // left, top
0.15f, // opacity
30, // rotation angle, degrees
1.0f, // scale
true, true, // visible on screen and in print
"1+");
pd4ml.setPageBackground("", "1+");
```
Watermarks also appear in RTF and DOCX output (from v4.2.0): with the v40 engine as a Word text watermark, with v42 as a picture of the watermark - see [RTF and DOCX Output: Watermarks](https://pd4ml.com/docs/features/rtf-and-docx-output.md#watermarks).
Runnable examples: [E003SetPageHeaderFooter.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E003SetPageHeaderFooter.java), [E004SetPageHeaderFooterInline.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E004SetPageHeaderFooterInline.java) (headers/footers), [E005SetPageBackground.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E005SetPageBackground.java), [E006SetPageBackgroundInline.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E006SetPageBackgroundInline.java) (backgrounds), [E007SetPageWatermark.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E007SetPageWatermark.java), [E008SetPageWatermarkInline.java](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/basics/E008SetPageWatermarkInline.java) (watermarks) -- each via the API and inline tags respectively.
**CSS gradient backgrounds.** _From PD4ML v4.2.0, both layout engines._ `linear-gradient()`, `radial-gradient()`, `conic-gradient()` and their `repeating-` forms work as backgrounds, in PDF and image output:
```css
.banner { background: linear-gradient(to right, #f80, #08f); border-radius: 12px; }
.badge { background: radial-gradient(circle at 30% 30%, #fff, #fc0 40%, #c60); }
.chart { background: conic-gradient(#36c 0 40%, #f80 0 75%, #ccc 0); border-radius: 50%; }
.stripes { background: repeating-linear-gradient(45deg, #eee 0 10px, #fff 10px 20px); }
.fade { background: linear-gradient(transparent, rgba(0,0,0,.6)), url(photo.jpg); }
```
- **The full CSS syntax:** angles and `to ` / `to `; radial shapes, sizes (`closest-side`, `farthest-corner`, ...) and `at `; conic `from ` and `at `; color stops anywhere along the gradient, hard stops and double-position stops. Transparent stops fade without turning grey.
- **Sized and tiled like images:** `background-size`, `background-position` and `background-repeat` apply, so `linear-gradient(...) 0 0 / 20px 20px` tiles a pattern.
- **Boxes:** gradients follow rounded corners, and show through the gaps of dashed and dotted borders. On a box that breaks across pages, the gradient continues from one page to the next.
- **In PDF, gradients are vector shadings, not images:** sharp at any zoom, and small. Transparent stops become a soft mask. PDF/A-1 does not allow transparency, so there the colors are blended over white instead.
The v40 layout engine draws one background layer per box (the first gradient or image), reads `background-size` only from the property itself (not from the `/ size` part of the `background` shorthand), and draws a `border-radius: 50%` box as a pill rather than an ellipse.
A background image or gradient on `` -- or on ``, when `` has no background -- fills every page of the v42 layout engine's output, as in v40.
## 9. Fonts, bookmarks, and hyperlinks
```java
pd4ml.useTTF("/opt/fonts"); // TrueType/OpenType directory to embed glyphs from
pd4ml.embedTTFs(true, false); // embed only the glyphs actually used, not the full font
pd4ml.applyKerning(true); // honor the font's own kerning pairs
pd4ml.enableLigatures(true); // build compound glyphs (fi, fl, ...) where the font defines them
pd4ml.generateBookmarksFromHeadings(true); // one bookmark per