PrintForm.js

English | 简体中文

PrintForm.js is a lightweight (zero-dependency Vanilla JS) browser-side pagination script.

Its core function is: automatically splitting a long HTML container (.printform) into multiple pages that fit the print paper size. It handles headers, footers, repeated table headers, page number updates, and dummy row filling automatically.

📚 Documentation Navigator

🚀 Getting Started

I want to...	Read this
Understand the project	Project Overview - Architecture, concepts, tech stack
Start using in 5 minutes	Quick Start Guide - Step-by-step tutorial
Use it correctly (full guide)	Usage Guide - Structure, API, PTAC/PADDT, pitfalls
See all configuration options	Configuration Reference - All data-* attributes

🎨 PrintForm Studio

Studio v2 is a Production Pilot for ERP engineers. It builds inspectable, self-contained print-form HTML; it is not a no-code freeform canvas.

I want to...	Read this
Design a general print form without coding	Studio v3: general business forms, browser AI and optional isolated Node/JSON source profile; Pilot evidence/limits. ERPNext is optional; full production qualification remains open
Build a Pilot single-HTML form	Open studio-v2/index.html — protocol-based, offline, WebMCP-ready
Understand v2 status and roadmap	Studio v2 documentation index (authoritative Chinese)
Review architecture and task status	GOAL.md · DESIGN.md · SPEC.md · EPIC.md · ROADMAP.md · TASK.md · PROGRESS.md ·

Studio v2 is the intended production path and remains Production Pilot. It exports a self-contained HTML with declarative bindings, embedded runtimes and validation records. Versions: runtime 1.0.0 / Studio 0.11.0 / Protocol 2.0.0 / Agent Contract 4.0.0. E14's four-layer panel, change cards, mode controls, history and resizable rail exist; the current worktree includes shared scope/apply/data-policy enforcement and closed Agent projections, while composed release acceptance remains incomplete. See the production plan for current evidence, pending requirements and proposed layout. Production Ready has not been declared. Studio v1 remains frozen and independent.

💻 Development

I want to...	Read this
Understand the code structure	Code Structure - File organization, data flow
Develop and extend	Developer Handbook · Node24 CI · Dependency advisory remediation
Learn about auto-docs	Auto Documentation Guide - How docs are generated

🔧 Reference

Document	Description
CONFIGURATION.md	Auto-generated config reference (Markdown)
configuration.html	Auto-generated config reference (HTML, view in browser)
config-reference.json	Auto-generated config reference (JSON, for tools)
CHANGELOG.md	Notable changes, most recent first
Compatibility matrix	The four independent version lines and how they combine (Chinese)
LICENSE	MIT

---

Logic Diagram

To help understand how printform.js works, please refer to the flowchart below: See: docs/LOGIC_DIAGRAM.md. Link: Link to the flowchart image

---

Quick Start (Short)

1. Start Server

You need a static server to preview the effect (to avoid browser local file restrictions).

# Option A: Python (Recommended)
python3 -m http.server 8000

# Option B: Node/Vite
npm install
npm run dev

2. Preview

Open in browser:

• http://localhost:8000/index.html (Full demo)
• http://localhost:8000/index001.html (Basic structure)

---

How to Use (Essentials)

PrintForm does not require complex build tools, just follow a specific HTML structure convention.

Mobile (iOS/Android) Rendering Notes

Some mobile browsers can auto-adjust font sizes and/or allow user scaling which may change layout measurements and break the expected print-like pagination. For consistent rendering, set these on your HTML page:

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">
<style>
  html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
</style>

If you need to keep pinch-zoom for accessibility, remove maximum-scale=1, user-scalable=no and keep text-size-adjust.

1. Basic Structure

Create a div with class="printform" and configure the paper size.

<!-- Explicit logical CSS-pixel budget, not physical A4; use data-paper-size for a preset. -->
<div class="printform"
     data-papersize-width="750"
     data-papersize-height="1050">

    <!-- 1. Header (Repeated at top of every page) -->
    <div class="pheader">...</div>

    <!-- 2. Doc Info (Repeats by default; configurable) -->
    <div class="pdocinfo">...</div>

    <!-- 3. Table Header (Column titles, repeated on new pages) -->
    <div class="prowheader">...</div>

    <!-- 4. Data Rows (Core content, split automatically) -->
    <div class="prowitem">Row 1</div>
    <div class="prowitem">Row 2</div>
    <div class="prowitem">Row 3...</div>

    <!-- 5. Footer (Defaults to last page; configurable) -->
    <div class="pfooter">...</div>

</div>

<!-- Include script -->
<script src="./dist/printform.js"></script>

2. Key Classes

Note: Do not rely on data-* attributes for styling. During formatting, the engine replaces section class names (e.g. .pheader → .pheader_processed). If you style by class, mirror rules for both original and _processed class names.

Class	Description	Default Behavior
.printform	Root Container	The script only processes content inside this container.
.pheader	Header	Repeats on every page.
.pdocinfo	Doc Info	Document metadata (e.g. invoice details), repeats on every page (configurable).
.prowheader	Table Header	Table column headers, repeats on every page.
.prowitem	Business Row	Measured DOM Range continuations retain one semantic identity across multi-cell/multirow fragments; indivisible content must fit. See continuation limits.
.pfooter	Footer	Defaults to last page only (can be configured to repeat).
.ptac	Terms/Text	Measured rich-text and table-cell continuations; preserves graphemes and authored inline content.
.paddt	Audit/Addendum	PADDT rows rendered after main pages.

---

Configuration (Short)

You can use data-* attributes directly on the .printform element to control behavior. For the full list, see docs/CONFIGURATION.md.

Common Configs

Attribute	Example	Description
data-papersize-width	750	Paper width (px).
data-papersize-height	1050	Paper height budget (px); page container height is intentionally not forced so debug can show actual content height (final fill spacer may be sub-pixel).
data-paper-size	A4	Preset paper size (A4/A5/LETTER/LEGAL). Used when width/height not set.
data-dpi	96	DPI used to convert data-paper-size to pixels.
data-orientation	portrait / landscape	Paper orientation.
data-repeat-header	y / n	Repeat header on every page (Default y).
data-repeat-footer	y / n	Repeat footer on every page (Default n).
data-show-logical-page-number	y / n	Show page numbers (e.g. "Page 1 of 3").
data-show-physical-page-number	y / n	Show physical page numbers (for N-up).
data-n-up	Positive integer	N-Up Printing: Validated logical pages uniformly scaled into physical sheet cells; see geometry and limits.

Row / Footer Controls

Attribute	Example	Description
data-height-of-dummy-row-item	26	Height for each dummy row item used to fill remaining space.
data-repeat-docinfo	y / n	Repeat .pdocinfo on every page.
data-repeat-docinfo002	y / n	Repeat .pdocinfo002 on every page.
data-repeat-docinfo003	y / n	Repeat .pdocinfo003 on every page.
data-repeat-docinfo004	y / n	Repeat .pdocinfo004 on every page.
data-repeat-docinfo005	y / n	Repeat .pdocinfo005 on every page.
data-repeat-rowheader	y / n	Repeat .prowheader on every page.
data-repeat-ptac-rowheader	y / n	Repeat .prowheader on PTAC-only pages.
data-repeat-footer	y / n	Repeat .pfooter on every page (final page always includes all footers).
data-repeat-footer002	y / n	Repeat .pfooter002 on every page.
data-repeat-footer003	/

PADDT Controls

Attribute	Example	Description
data-repeat-paddt	y / n	Reserved toggle for PADDT repeat behavior (currently unused).
data-repeat-paddt-rowheader	y / n	Repeat .prowheader on PADDT pages.
data-insert-paddt-dummy-row-items	y / n	Insert dummy row items on PADDT pages.
data-paddt-max-words-per-segment	180	Max words per PADDT segment when splitting paragraphs.
data-paddt-debug	y / n	Enable PADDT debug logs.
data-repeat-paddt-docinfo	y / n	Repeat .pdocinfo on PADDT pages only.
data-repeat-paddt-docinfo002	y / n	Repeat .pdocinfo002 on PADDT pages only.
data-repeat-paddt-docinfo003	y / n	Repeat .pdocinfo003 on PADDT pages only.
data-repeat-paddt-docinfo004	y / n	Repeat .pdocinfo004 on PADDT pages only.
data-repeat-paddt-docinfo005	y / n	Repeat .pdocinfo005 on PADDT pages only.

Example

<div class="printform"
     data-papersize-width="800"
     data-papersize-height="1100"
     data-repeat-footer="y"
     data-show-logical-page-number="y">
     ...
</div>

---

Advanced Features

1. Dummy Rows (Filling Empty Space)

If a page is not full, PrintForm automatically inserts empty rows to push the footer to the bottom.

• You can customize the dummy row style:

<template class="custom-dummy-row-item-content">
  <tr style="height:20px;"><td style="border:0;">...</td></tr>
</template>

• You can customize the page-height spacer (single root element; height is auto-filled):

<template class="custom-dummy-spacer-content">
  <table style="width:100%; table-layout:fixed;" cellpadding="0" cellspacing="0">
    <tr><td style="border-top:1px solid #000;"></td></tr>
  </table>
</template>

2. Force Page Break

Add tb_page_break_before to the row to start a new page before it.

<div class="prowitem tb_page_break_before">...</div>

3. Hide Row Header On A Specific Page

If you need a page to start without the repeating .prowheader, add without_prowheader (or tb_without_rowheader) on the row that starts that page.

<table class="prowitem tb_page_break_before without_prowheader">...</table>

4. JS API

The script runs automatically on load. If you generate content dynamically (e.g. AJAX), trigger formatting manually:

// Format all .printform elements
await PrintForm.formatAll({ force: true });

// Or format a specific node
const myForm = document.querySelector('#invoice-1');
PrintForm.format(myForm);

formatAll() processes current source forms, including later additions; concurrent calls share completion. It returns {formattedCount, failedCount} and rejects with AggregateError plus error.report if any form fails. Successful formatting removes the source .printform; failed formatting preserves it. See the ERP support contract for layout, business-data and actual-print limits.

5. Build for Production

If you modify the source (src/ directory), rebuild:

npm run build

Output is in dist/printform.js (and root *.html + README.md/README.zh-CN.md are copied to dist/ for npm run preview).

FAQ

Q: Why is my content cut off? A: Check the configured height after headers/footers. Text and supported table cells can continue; oversized atomic assets, money, nested tables or chrome fail instead of silently clipping. See measured continuation limits.

Q: How to hide the header on the first page? A: The logic prefers consistency. For special cases, hide the header via CSS using a wrapper selector or split the DOM before formatting.

Q: Margins are wrong when printing? A: Physical margins are controlled by the browser and printer driver. In the print dialog, enable "Background graphics" and set margins to "None" or "Minimum" (PDF viewers at non-100% zoom may show 1px jitter; pin footers via @media print absolute positioning if you need visual lock).

Directory Structure

• src/printform.js - Entry point
• src/printform/formatter/ - Core Logic (Pagination calculation)
• src/printform/config.js - Configuration definitions
• src/printform/dom.js - DOM helpers
• index.html - Full test case