bookjs-eazy

bookjs-eazy is a tool for WEB printing and converting HTML to PDF. It solves the problem of controllable pagination when generating high-quality PDFs from HTML content.

Key Features:

• Automatic Pagination: Focus on building content with H5/HTML; the tool handles pagination and content truncation based on defined rules.
• WYSIWYG Preview: Supports web printing and previewing with custom page numbers, tables of contents, headers, and footers.
• Flexible Deployment: Can be used on the frontend (browser 'Print to PDF') or backend (using Chrome Headless or wkhtmltopdf).
• Docker Support: Provides a Docker image for quick deployment of a PDF generation service.

Important Limitations:

• Framework Compatibility: Does not support modern SPA routing (Vue, React, etc.) via import. You must include scripts directly via <script> tags in the HTML.
• No Dynamic Refresh: Re-rendering requires a full page refresh.
• Entry Point: Each PDF page requires its own dedicated HTML file entry point.
• Embedding: To embed within an existing web application, use an <iframe>.

To render a page for PDF generation, follow these steps:

1. Structure: Place your PDF content elements inside a container with the ID #content-box under the <body> tag.
2. Trigger Rendering: The program monitors the global variable window.bookConfig.start. Rendering only begins when this value is set to true.
   • Crucial for Dynamic Content: If your page content is loaded dynamically, set window.bookConfig.start to false by default. Once your content is fully loaded and ready, switch it to true to trigger the PDF styling and pagination logic.
3. Overflow Detection: The tool uses a container node with the class .nop-page-content to detect page overflows by monitoring height changes.

Layout Best Practices to avoid overflow detection issues:

• Avoid certain CSS properties: Elements using display: float, position: absolute, or overflow may not trigger height changes in the container, causing undetected overflows.
• Use Padding instead of Margin: Elements with margin styles cannot expand the size of .nop-page-content, which can cause position offsets and unexpected overflows. Use padding to control relative spacing instead.

To use bookjs-eazy, you must define a global configuration object named bookConfig. This object controls paper size, orientation, margins, and various plugins like page numbering, catalogs, and toolbars.

Critical: Handling Dynamic Content

If your page content is generated dynamically (e.g., via asynchronous requests or charts), you must set bookConfig.start to false initially. Only set it to true once your #content-box node is fully rendered and ready. This ensures the library doesn't attempt to paginate an empty or incomplete container.

Core Configuration Options

• start (boolean): Controls when rendering begins. Set to true to start.
• pageSize (string): Paper size (e.g., 'ISO_A4').
• orientation (string): 'portrait' or 'landscape'.
• pageSizeOption (object): Custom dimensions using width and height (e.g., { width: '15cm', height: '20cm' }).
• padding (string): Page margins (e.g., '31.8mm 25.4mm 31.8mm 25.4mm').
• pageFixedHeightOffset (number): Adjusts height to prevent blank pages caused by browser rendering differences (unit: mm, typically negative).
• printDelay (number): Milliseconds to wait before PDF generation (affects server-side printing only).

<script>
  bookConfig = {
    // Set to false if content is loaded asynchronously
    start: true,
    pageSize: 'ISO_A4',
    orientation: 'landscape',
    padding: '31.8mm 25.4mm 31.8mm 25.4mm',
    pageFixedHeightOffset: -1.0,
    forcePrintBackground: true,
    printDelay: 1000
  };
</script>

To use bookjs-eazy, you must define a global configuration object named bookConfig in a <script> tag. This object controls page dimensions, orientation, margins, and plugin behaviors.

Critical Configuration: start

If your page contains dynamic content (e.g., asynchronous requests, charts, or complex HTML rendering), set bookConfig.start to false initially. Once the content is fully rendered and ready, set it to true to trigger the bookjs-eazy rendering process.

Page Dimensions and Orientation

You can define the page size using either standard ISO/JIS/NA types or custom dimensions:

• pageSize: A string representing standard sizes (e.g., 'ISO_A4', 'NA_LETTER', 'JIS_B5'). Default is 'ISO_A4'.
• orientation: 'portrait' or 'landscape'.
• pageSizeOption: Use this for custom dimensions instead of pageSize. It requires width and height (e.g., '15cm').

Margins and Layout

• padding: A string defining margins (e.g., '31.8mm 25.4mm 31.8mm 25.4mm').
• pageFixedHeightOffset: A value in mm (often negative) used to fix issues where browsers add extra blank pages during printing.
• forcePrintBackground: Boolean to force printing of background elements. Default is true.
• printDelay: Time in milliseconds to wait before generating the PDF. Useful for pages with unpredictable asynchronous elements.

<script>
bookConfig = {
    start: true, // Set to true only when all dynamic content is ready
    pageSize: 'ISO_A4',
    orientation: 'landscape',
    padding: '31.8mm 25.4mm 31.8mm 25.4mm',
    printDelay: 1000
};
</script>