palapala_pdf 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9359afef10584362d61be46353495ae97d4ee17a380912fac9ede823fc9d41b
-  data.tar.gz: 3c8fce8d86a1fa1e1a9394c7e46eb9fe487669f5d621eabf56cd0ae2c29dd33b
+  metadata.gz: 230cc525cd5e4bbc4d2ce9ddb0a418486bc27ad6163cef9834a67d7e23442b41
+  data.tar.gz: b283d90551ef07efe3384148b061ec0a6a18cb3bdbc9485c1e8717e6bc4979f3
 SHA512:
-  metadata.gz: e026b00c0e48fc24a412314a51f612813c2ac6441bee5b48139999dc58ceeec0b9c2807edf0cd0c00cdffb99fbcd0bb6848b2fc53599ed8d51fe286ee3a77155
-  data.tar.gz: c759088c15ea39529b7cf9ccdb95dee9af3c7b8bb02c8bc3ab6aef73e59de4e93378cd12f85e7affd3c2c2a7c2c8a476449087d529ce98dfd1aa2806f9119adc
+  metadata.gz: cfcf738f7171f679d419349cce4ce0441bb3be54fc355fa9592222b04c63654d6646c6103310f8ddf56e7112a3ccc95b30ddb92db86e0ff48a12b221f8be039c
+  data.tar.gz: efa8277743d960b0d3e869ab970c8248a2f901b572d4451bf0c479c311eabbd2a810e678efad489913ced8ab2ada14e8ce7d4b4fbb7d3ccad61ce98f419ee1b2

data/README.md

@@ -4,7 +4,9 @@
 
 This project is a Ruby gem that provides functionality for generating PDF files from HTML using the Chrome browser. It allows you to easily convert HTML content into PDF documents, making it convenient for tasks such as generating reports, invoices, or any other printable documents. The gem provides a simple and intuitive API for converting HTML to PDF, and it leverages the power and flexibility of the Chrome browser's rendering engine to ensure accurate and high-quality PDF output. With this gem, you can easily integrate PDF generation capabilities into your Ruby applications.
 
-At the core, this project leverages the same rendering engine as [Grover](https://github.com/Studiosity/grover), but with significantly reduced overhead and dependencies. Instead of relying on the full Grover/Puppeteer/NodeJS stack, this project uses a raw web socket to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficieny while providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.
+At the core, this project leverages the Chrome rendering engine, but with significantly reduced overhead and dependencies. Instead of relying on the full Grover/Puppeteer/NodeJS stack, this project uses a raw web socket to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficieny while providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.
+
+It leverages work from [Puppeteer](https://pptr.dev/browsers-api/) (@puppeteer/browsers) to install a local Chrome-Headless-Shell if no Chrome is running, but that requires node (npx) to be available.
 
 This is how easy PDF generation can be in Ruby:
 
@@ -16,88 +18,28 @@ And this while having the most modern HTML/CSS/JS availlable to you: flex, grid,
 
 A core goal of this project is performance, and it is designed to be exceptionally fast. By leveraging **direct communication** with a headless Chrome or Chromium browser via a **raw web socket**, the gem minimizes overhead and dependencies, enabling PDF generation at speeds that significantly outperform other solutions. Whether generating simple or complex documents, this gem ensures that your Ruby applications can handle PDF tasks efficiently and at scale.
 
-## Installation
-
-To install the gem and add it to your application's Gemfile, execute the following command:
-
-```
-$ bundle add palapala_pdf
-```
-
-If you are not using bundler to manage dependencies, you can install the gem by running:
-
-```
-$ gem install palapala_pdf
-```
-
-Palapala PDF connects to Chrome over a web socket connection.
-An external Chrome/Chromium is expected. Start it with the following
-command (9222 is the default port):
-
-```sh
-/path/to/chrome --headless --disable-gpu --remote-debugging-port=9222
-```
-
-### Installing Chrome / Headless Chrome
-
-Seems the august 2024 release 128.0.6613.85 is seriously performance impacted. So to avoid regression issues, it's suggested to install a specific version of Chrome, test it and stick with it.  This is easiest using npx and some tooling provided by Puppeteer. Unfortunately it depends on node/npm, but it's worth it. E.g. install a specific version like this:
-
-```
-npx @puppeteer/browsers install chrome@127.0.6533.88
-````
-
-This installs chrome in a `chrome` folder in the current working dir and it outputs the path where it's installed when it's finished.
-
-If you installed it using puppeteer from above
-
-```sh
-./chrome/mac_arm-127.0.6533.88/chrome-mac-arm64/Google\ Chrome\ for\ Testing.app/Contents/MacOS/Google\ Chrome\ for\ Testing --headless --disable-gpu --remote-debugging-port=9222
-```
+## Sponsor This Project
 
-Currently i'd advise for the `chrome-headless-shell`variant that is a light version meant just for this use case. The chrome-headless-shell is a minimal, headless version of the Chrome browser designed specifically for environments where you need to run Chrome without a graphical user interface (GUI). This is particularly useful in scenarios like server-side rendering, automated testing, web scraping, or any situation where you need the power of the Chrome browser engine without the overhead of displaying a UI. Headless by design, reduced size and overhead but still the same engine.
+If you find this project useful and would like to support its development, consider sponsoring or buying a coffee to help keep it going:
 
-```
-npx @puppeteer/browsers install chrome-headless-shell@stable
-```
+- **GitHub Sponsors:** [Sponsor on GitHub](https://github.com/sponsors/koenhandekyn)
+- **Buy Me a Coffee:** [Buy a Coffee](https://buymeacoffee.com/koenhandekyn)
 
-It installs to a path like this `./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell`. As it's headless by design, it only needs one parameter
+Your support is greatly appreciated and helps maintain the project!
 
-```
-./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell --remote-debugging-port=9222
-```
+## Installation
 
-Alternatively, Palapala PDF will try to launch Chrome as a child process.
-It guesses the path to Chrome, or you configure it like this:
+To install the gem and add it to your application's Gemfile, execute the following command:
 
-```ruby
-Palapala.setup do |config|
-  config.headless_chrome_path = '/usr/bin/google-chrome-stable' # path to Chrome executable
-end
 ```
-
-### Installing Node/NPX
-
-Using Brew
-
-````
-brew install node
+$ bundle add palapala_pdf
 ```
 
-Using NVM (Node Version Manager)
-
-````
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
-source ~/.nvm/nvm.sh
-nvm --version
-nvm install node
-````
-
-
 ## Usage Instructions
 
 To create a PDF from HTML content using the `Palapala` library, follow these steps:
 
-1. **Configuration**:
+**Configuration from inside Ruby**
 
 Configure the `Palapala` library with the necessary options, such as the URL for the browser and default settings like scale and format.
 
@@ -105,76 +47,82 @@ In a Rails context, this could be inside an initializer.
 
 ```ruby
 Palapala.setup do |config|
-    # run against an external chrome/chromium or leave this out to run against a chrome that is started as a child process
+    # debug mode
     config.debug = true
-    config.headless_chrome_url = 'http://localhost:9222' # run against a remote Chrome instance
-    # config.headless_chrome_path = '/usr/bin/google-chrome-stable' # path to Chrome executable
-    config.defaults = { scale: 1, format: :A4 }
+    # Chrome headless shell version to use (stable, beta, dev, canary, etc.) when launching a new Chrome instance
+    config.chrome_headless_shell_version = :stable
+    # run against an external chrome/chromium or leave this out to run against a chrome that is started as a child process
+    config.headless_chrome_url = 'http://localhost:9222'
+    # path to Chrome executable
+    config.headless_chrome_path = '/usr/bin/google-chrome-stable'
+    # default options for PDF generation
+    config.defaults = { scale: 1 }
+    # extra params to pass to Chrome when launched as a child process
+    config.chrome_params = []
 end
 ```
-1. **Create a PDF from HTML**:
 
-Create a PDF file from HTML in `irb`
+**Using environemnt variables**
+
+```sh
+CHROME_HEADLESS_SHELL_VERSION=canary ruby examples/performance_benchmark.rb
+````
+
+```sh
+HEADLESS_CHROME_URL=http://192.168.1.1:9222 ruby examples/performance_benchmark.rb
+```
 
 ```sh
-gem install palapala_pdf
+CHROME_HEADLESS_PATH=/var/to/chrome ruby examples/performance_benchmark.rb
 ```
 
-in IRB, load palapala and create a PDF from an HTML snippet:
+**Create a PDF from HTML**
+
+Load palapala and create a PDF file from an HTML snippet:
 
 ```ruby
 require "palapala"
 Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
 ```
 
-Instantiate a new Palapala::Pdf object with your HTML content and generate the PDF binary data.
+Instantiate a new Palapala::Pdf object with your HTML content and generate the PDF binary data:
 
 ```ruby
 require "palapala"
 binary_data = Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
 ```
 
-## Paged CSS
-
-Paged CSS is a subset of CSS designed for styling printed documents. It extends standard CSS to handle pagination, page sizes, headers, footers, and other aspects of printed content. Paged CSS is commonly used in scenarios where web content needs to be converted to PDFs or other paginated formats.
-
-### Headers and Footers
+## Advanced Examples
 
-When using Chromium-based rendering engines, headers and footers are not controlled by the Paged CSS standard but are instead managed through specific settings in the rendering engine.
+- headers and footers
+- paged css for paper sizes, paper margins, pages breaks, etc
+- js based rendering
 
-With palapala PDF headers and footers are defined using `header_html` and `footer_html` options. These allow you to insert HTML content directly into the header or footer areas.
+## Connecting to Chrome
 
-```ruby
-Palapala::Pdf.new(
-  "<p>Hello world</>",
-  header_html: '<div style="text-align: center;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
-  footer_html: '<div style="text-align: center;">Generated with Palapala PDF</div>',
-  margin: { top: "2cm", bottom: "2cm"}
-).save("test.pdf")
-```
+Palapa PDF will go through this process
 
-### Page size, orientation and margins
+- check if a Chrome is running and exposing port 9222 (and if so, use it)
+- if `Palapala.headless_chrome_path` is defined, launch Chrome as a child process using that path
+- if **NPX** is avalaillable, install a **Chrome-Headless-Shell** variant locally and launch it as a child process. It will install the 'stable' version or the version identified by `Palapala.chrome_headless_shell_version` setting (or from ENV `CHROME_HEADLESS_SHELL_VERSION`).
+- as a last fallback it will guess a chrome path from the detected OS and try to launch a Chrome with that
 
-#### With CSS
+In our expreience a Chrome-Headless-Shell version gives the best performance and resource useage.
 
-todo example
+### Installing Chrome / Headless Chrome manually
 
-#### As params
+This is easiest using npx and tooling provided by Puppeteer (depends on node/npm, but it's worth it). This installs chrome in a `chrome` folder in the current working dir and it outputs the path where it's installed when it's finished. Currently we'd advise for the `chrome-headless-shell` variant that is a light version meant just for this use case. The chrome-headless-shell is a minimal, headless version of the Chrome browser designed specifically for environments where you need to run Chrome without a graphical user interface (GUI). This is particularly useful in scenarios like server-side rendering, automated testing, web scraping, or any situation where you need the power of the Chrome browser engine without the overhead of displaying a UI. Headless by design, reduced size and overhead but still the same engine.
 
-todo example
+```sh
+npx @puppeteer/browsers install chrome-headless-shell@stable
+```
 
-## JS based rendering
+It installs to a path like this `./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell`. As it's headless by design, it only needs one parameter:
 
-```html
-  <html>
-    <script type="text/javascript">
-      document.addEventListener("DOMContentLoaded", () => {
-        document.body.innerHTML += "<p>Current time from JS: " + new Date().toLocaleString() + "</p>";
-      });
-    </script>
-    <body><p>Default body text.</p></body>
-  </html>
+```sh
+./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell --remote-debugging-port=9222
 ```
+*Note: Seems the august 2024 release Chrome releases 128.0.6613.85 onward is seriously performance impacted for PDF generation. Chrome Headless Shell releases don't seem to suffer from this issue.
 
 ## Raw parameters (Page.printToPDF)
 
@@ -196,15 +144,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/palapa
 - [Eugen Neagoe](https://github.com/eneagoe) - Thank you for your valuable input, feedback and opinions.
 - [Radu Bogoevici](https://github.com/codenighter) - Thanks for test driving, and all help big and small.
 
-## Sponsor This Project
-
-If you find this project useful and would like to support its development, consider sponsoring or buying a coffee to help keep it going:
-
-- **GitHub Sponsors:** [Sponsor on GitHub](https://github.com/sponsors/koenhandekyn)
-- **Buy Me a Coffee:** [Buy a Coffee](https://buymeacoffee.com/koenhandekyn)
-
-Your support is greatly appreciated and helps maintain the project!
-
 ## Findings
 
 - For Chrome, mode headless=new seems to be slower for pdf rendering cases.
@@ -212,24 +151,14 @@ Your support is greatly appreciated and helps maintain the project!
 
 ## Primitive benchmark
 
-On a macbook m3, the throughput for 'hello world' PDF generation can reach around 300 docs/second when allowing for some concurrency. As Chrome is actually also very efficient, it scales really well for complex documents also. If you run this in Rails, the concurrency is being taken care of either by the front end thread pool or by the workers and you shouldn't have to think about this. (Using an external Chrome)
+On a macbook m3, the throughput for 'hello world' PDF generation can reach around 500 to 800 docs/second when allowing for some concurrency (4 threads). As Chrome is actually also very efficient, it scales really well for complex documents also. If you run this in Rails, the concurrency is being taken care of either by the front end thread pool or by the workers and you shouldn't have to think about this. (Using an external Chrome)
 
 Note: it renders `"Hello #{i}, world #{j}! #{Time.now}."` where i is the thread and j is the iteration counter within the thread and persists it to an SSD (which is very fast these days).
 
-### benchmarking 20 docs: 1x20, 2x10, 4x5
-
-```sh
-c:1, n:20 : Throughput = 159.41 docs/sec, Total time = 0.1255 seconds
-c:2, n:10 : Throughput = 124.91 docs/sec, Total time = 0.1601 seconds
-c:4, n:5  : Throughput = 196.40 docs/sec, Total time = 0.1018 seconds
-```
-
-### benchmarking 320 docs: 1x320, 4x80, 8x40
-
 ```sh
-c:1, n:320 : Throughput = 184.99 docs/sec, Total time = 1.7299 seconds
-c:4, n:80  : Throughput = 302.50 docs/sec, Total time = 1.0578 seconds
-c:8, n:40  : Throughput = 254.29 docs/sec, Total time = 1.2584 seconds
+c:1, n:10 : Throughput = 16.76 docs/sec, Total time = 0.5968 seconds
+c:2, n:10 : Throughput = 170.41 docs/sec, Total time = 0.1174 seconds
+c:4, n:80 : Throughput = 579.03 docs/sec, Total time = 0.5526 seconds```
 ```
 
 This is about a factor 100x faster then what you typically get with Grover and still 10x faster then with many alternatives. It's effectively that fast that you can run this for a lot of uses cases straight from e.g. your Ruby On Rails web worker in the controller on a single machine and still scale to lot's of users.
@@ -256,25 +185,22 @@ In this example, `pdf_data` is the binary data of the PDF file. The `filename` o
 
 ## Docker
 
-In docker as root you must pass the no-sandbox browser option:
+TODO
 
-```ruby
-Palapala.setup do |config|
-  config.opts = { 'no-sandbox': nil }
-end
-```
-It has also been reported that the Chrome process repeatedly crashes when running inside a Docker container on an M1 Mac. Chrome should work as expected when deployed to a Docker container on a non-M1 Mac.
+*It has also been reported that the Chrome process repeatedly crashes when running inside a Docker container on an M1 Mac. Chrome should work as expected when deployed to a Docker container on a non-M1 Mac.*
 
 ## Thread-safety
 
-Behind the scenes, a websocket is openend and stored on Thread.current for subsequent requests. Hence, the code is
-thread safe in the sense that every web socket get's a new tab in the underlying chromium and get an isolated context.
-
 For performance reasons, the code uses a low level websocket connection that does all it's work on the curent thread
 so we can avoid synchronisation penalties.
 
+Behind the scenes, a websocket is openend and stored on Thread.current for subsequent requests. Hence, the code is
+thread safe in the sense that every web socket get's a new tab in the underlying chromium and get an isolated context.
+
 ## Heroku
 
+TODO
+
 possible buildpacks
 
 https://github.com/heroku/heroku-buildpack-chrome-for-testing

data/doc/installing_node.md

@@ -0,0 +1,16 @@
+### Installing Node (npx)
+
+Using Brew
+
+```sh
+brew install node
+```
+
+Using NVM (Node Version Manager)
+
+```sh
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
+source ~/.nvm/nvm.sh
+nvm --version
+nvm install node
+```

data/doc/paged_css.md

@@ -0,0 +1,167 @@
+## Paged CSS
+
+Paged CSS is a subset of CSS designed for styling printed documents. It extends standard CSS to handle pagination, page sizes, headers, footers, and other aspects of printed content. Paged CSS is commonly used in scenarios where web content needs to be converted to PDFs or other paginated formats.
+
+Setting page size
+
+```css
+@page {
+  /* set a standard page size */
+  size: A4 landscape;
+  /* Custom */
+  size: 8.5in 11in; /* Width x Height */
+}
+```
+
+Setting page margins
+
+```css
+@page {
+  margin: 1in; /* 1 inch on all sides */
+  margin: 1in 0.5in 1in 0.5in; /* Top, Right, Bottom, Left */
+}
+```
+
+Forcing a Page Break before or after an Element
+
+```css
+/* This ensures that every `h1` starts on a new page. */
+h1 {
+  page-break-before: always;
+}
+/* This ensures that every `p` element ends with a page break, starting the next content on a new page. */
+p {
+  page-break-after: always;
+}
+/* This prevents a table from being split across two pages. */
+table {
+  page-break-inside: avoid;
+}
+```
+
+### Headers and Footers
+
+When using Chromium-based rendering engines, headers and footers are not controlled by the Paged CSS standard but are instead managed through specific settings in the rendering engine.
+
+With palapala PDF headers and footers are defined using `header_template` and `footer_template` options. These allow you to insert HTML content directly into the header or footer areas.
+
+Critical is that you specify a font-size because by default Chrome uses a very tiny font.
+
+```ruby
+Palapala::Pdf.new(
+  "<p>Hello world</>",
+  header_template: '<div style="text-align: center; font-size: 12pt;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
+  footer_template: '<div style="text-align: center; font-size: 12pt;">Generated with Palapala PDF</div>',
+).save("test.pdf")
+```
+
+### Examples
+
+#### Headers and Footers
+
+TODO explain about headers and footers, font sizes, styles being independent, and how to insert current page, total pages, etc.
+
+#### Page sizes and margins
+
+Paged CSS, also known as @page CSS, is used to control the layout and appearance of printed documents. It allows you to define page-specific styles, such as sizes and margins, which are crucial for generating well-formatted PDFs.
+
+You can specify the size of the page using predefined sizes or custom dimensions. Common predefined sizes include A4, A3, letter, etc. Margins can be set for the top, right, bottom, and left sides of the page. You can specify all four margins at once or individually. You can also define named pages for different sections of your document.
+
+##### Example: Different First Page
+
+TODO Validate
+
+```css
+@page first {
+  size: A4;
+  margin: 2in; /* Larger margin for the first page */
+}
+
+@page {
+  size: A4;
+  margin: 1in;
+}
+
+body {
+  counter-reset: page;
+}
+
+body:first {
+  page: first;
+}
+```
+
+#### Page breaks
+
+Paged CSS allows you to control how content is divided across pages when printing or generating PDFs. Page breaks are an essential part of this, as they determine where a new page starts. You can control page breaks using the `page-break-before`, `page-break-after`, and `page-break-inside` properties.
+
+##### Page Break Properties
+
+1. **`page-break-before`**: Forces a page break before the element.
+2. **`page-break-after`**: Forces a page break after the element.
+3. **`page-break-inside`**: Prevents or allows a page break inside the element.
+
+##### Values
+
+- `auto`: Default. Neither forces nor prevents a page break.
+- `always` Always forces a page break.
+- `avoid`: Avoids a page break inside the element.
+- `left`: Forces a page break so that the next page is a left page.
+- `right`: Forces a page break so that the next page is a right page.
+
+##### Examples
+
+```css
+/* This ensures that every `h1` starts on a new page. */
+h1 {
+  page-break-before: always;
+}
+/* This ensures that every `p` element ends with a page break, starting the next content on a new page. */
+p {
+  page-break-after: always;
+}
+/* This prevents a table from being split across two pages. */
+table {
+  page-break-inside: avoid;
+}
+```
+
+##### Practical Use Cases
+
+- **Chapter Titles**: Use `page-break-before: always;` for chapter titles to ensure each chapter starts on a new page.
+- **Sections**: Use `page-break-after: always;` for sections that should end with a page break.
+- **Tables and Figures**: Use `page-break-inside: avoid;` to keep tables and figures from being split across pages.
+
+#### Tables accross Pages
+
+TODO explain `display` property with the values `table-header-group` and `table-footer-group`
+
+##### Example
+
+```html
+<table>
+  <thead>
+    <tr>
+      <th>Header 1</th>
+      <th>Header 2</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Data 1</td>
+      <td>Data 2</td>
+    </tr>
+    <!-- More rows -->
+  </tbody>
+  <tfoot>
+    <tr>
+      <td>Footer 1</td>
+      <td>Footer 2</td>
+    </tr>
+  </tfoot>
+</table>
+```
+
+In this example:
+- The `<thead>` section will be repeated at the top of each page.
+- The `<tfoot>` section will be repeated at the bottom of each page.

data/examples/all.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'palapala'
+
+$debug = ARGV[0] == 'debug'
+Palapala.debug = $debug
+
+require_relative "headers_and_footers"
+require_relative "paged_css"
+require_relative "js_based_rendering"

data/examples/chrome_base_header_footer_template.html

@@ -0,0 +1,169 @@
+<!--
+  OPTIONS AS PASSED IN THE C++ code
+  =================================
+  options.Set(kSettingHeaderFooterDate,
+              base::Time::Now().InMillisecondsFSinceUnixEpoch());
+  options.Set("width", static_cast<double>(page_size.width()));
+  options.Set("height", static_cast<double>(page_size.height()));
+  options.Set("topMargin", page_layout.margin_top);
+  options.Set("bottomMargin", page_layout.margin_bottom);
+  options.Set("leftMargin", page_layout.margin_left);
+  options.Set("rightMargin", page_layout.margin_right);
+  // `page_index` is 0-based, so 1 is added to get the page number.
+  options.Set("pageNumber", base::checked_cast<int>(page_index + 1));
+  options.Set("totalPages", base::checked_cast<int>(total_pages));
+  options.Set("url", params.url);
+  std::u16string title = source_frame.GetDocument().Title().Utf16();
+  options.Set("title", title.empty() ? params.title : title);
+  options.Set("headerTemplate", params.header_template);
+  options.Set("footerTemplate", params.footer_template);
+  options.Set("isRtl", base::i18n::IsRTL());
+-->
+
+<!doctype html>
+<html>
+
+<head>
+  <link rel="stylesheet" href="chrome://resources/css/text_defaults.css">
+  <style>
+    body {
+      display: flex;
+      flex-direction: column;
+      margin: 0;
+    }
+
+    #header,
+    #footer {
+      display: flex;
+      flex: none;
+    }
+
+    #header {
+      align-items: flex-start;
+      padding-top: 15pt;
+    }
+
+    #footer {
+      align-items: flex-end;
+      padding-bottom: 15pt;
+    }
+
+    #content {
+      flex: auto;
+    }
+
+    .left {
+      flex: none;
+      padding-left: 24pt;
+      /* csschecker-disable-line left-right */
+      padding-right: 6pt;
+      /* csschecker-disable-line left-right */
+    }
+
+    .center {
+      flex: auto;
+      padding-left: 24pt;
+      /* csschecker-disable-line left-right */
+      padding-right: 24pt;
+      /* csschecker-disable-line left-right */
+      text-align: center;
+    }
+
+    .right {
+      flex: none;
+      /* historically does not account for RTL */
+      padding-left: 6pt;
+      /* csschecker-disable-line left-right */
+      padding-right: 24pt;
+      /* csschecker-disable-line left-right */
+    }
+
+    .grow {
+      flex: auto;
+    }
+
+    .text {
+      font-size: 8pt;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+  </style>
+  <script>
+
+    function getComputedStyleAsFloat(style, value) {
+      return parseFloat(style.getPropertyValue(value).slice(0, -2));
+    }
+
+    function elementIntersects(element, topPos, bottomPos, leftPos, rightPos) {
+      const rect = element.getBoundingClientRect();
+      const style = window.getComputedStyle(element);
+
+      // Only consider the size of |element|, so remove the padding from |rect|.
+      // The padding is used for positioning.
+      rect.top += getComputedStyleAsFloat(style, 'padding-top');
+      rect.bottom -= getComputedStyleAsFloat(style, 'padding-bottom');
+      rect.left += getComputedStyleAsFloat(style, 'padding-left');
+      rect.right -= getComputedStyleAsFloat(style, 'padding-right');
+      return leftPos < rect.right && rightPos > rect.left && topPos < rect.bottom &&
+        bottomPos > rect.top;
+    }
+
+    function setupHeaderFooterTemplate(options) {
+      const body = document.querySelector('body');
+      const header = document.querySelector('#header');
+      const footer = document.querySelector('#footer');
+
+      body.style.width = `${options.width}px`;
+      body.style.height = `${options.height}px`;
+      header.style.height = `${options.topMargin}px`;
+      footer.style.height = `${options.bottomMargin}px`;
+
+      const topMargin = options.topMargin;
+      const bottomMargin = options.height - options.bottomMargin;
+      const leftMargin = options.leftMargin;
+      const rightMargin = options.width - options.rightMargin;
+
+      header.innerHTML = options['headerTemplate'] || `
+      <div class='date text left'></div>
+      <div class='title text center'></div>`;
+      footer.innerHTML = options['footerTemplate'] || `
+      <div class='url text left grow'></div>
+      <div class='text right'>
+        <span class='pageNumber'></span>/<span class='totalPages'></span>
+      </div>`;
+
+      const date = new Date(options.date);
+      const formatter =
+        new Intl.DateTimeFormat(
+          navigator.languages[0].split('@')[0],
+          { dateStyle: 'short', timeStyle: 'short' });
+      options.date = formatter.format(date);
+      for (const cssClass of ['date', 'title', 'url', 'pageNumber', 'totalPages']) {
+        for (const element of document.querySelectorAll(`.${cssClass}`)) {
+          element.textContent = options[cssClass];
+        }
+      }
+      for (const element of document.querySelectorAll(`.text`)) {
+        if (options.isRtl &&
+          !element.classList.contains('url') &&
+          !element.classList.contains('title')) {
+          element.dir = 'rtl';
+        }
+        if (elementIntersects(element, topMargin, bottomMargin, leftMargin,
+          rightMargin)) {
+          element.style.visibility = 'hidden';
+        }
+      }
+    }
+
+  </script>
+</head>
+
+<body>
+  <div id="header"></div>
+  <div id="content"></div>
+  <div id="footer"></div>
+</body>
+
+</html>

data/examples/headers_and_footers.rb

@@ -3,47 +3,18 @@
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'palapala'
 
-HEADER_HTML = <<~HTML
-  <style type="text/css">
-    .header {
-      -webkit-print-color-adjust: exact;
-      border-bottom: 1px solid lightgray;
-      color: black;
-      font-family: Arial, Helvetica, sans-serif;
-      font-size: 12pt;
-      margin: 0 auto;
-      padding: 5px;
-      text-align: center;
-      vertical-align: middle;
-      width: 100%;
-      border: 1px solid black;
-    }
-  </style>
-  <div class="header" style="text-align: center">
-    Page <span class="pageNumber"></span> of <span class="totalPages"></span>
-  </div>
-HTML
+header_template =
+  '<div style="text-align: center; font-size: 12pt; padding: 1rem; width: 100%;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>'
 
-Palapala.setup do |config|
-  config.debug = true
-  config.headless_chrome_url = 'http://localhost:9222' # run against a remote Chrome instance
-  # config.headless_chrome_path = '/usr/bin/google-chrome-stable' # path to Chrome executable
-end
+footer_template =
+  '<div style="text-align: center; font-size: 12pt; padding: 1rem; width: 100%;">Generated with Palapala PDF</div>'
 
-result = Palapala::Pdf.new(
-  # "<style>@page { size: A4 landscape; }</style><p>Hello world #{Time.now}</>",
+Palapala::Pdf.new(
   "<h1>Title</h1><p>Hello world #{Time.now}</>",
-  header_html: HEADER_HTML,
-  footer_html: '<div style="text-align: center;">Generated with Palapala PDF</div>',
-  scale: 0.75,
-  prefer_css_page_size: false,
-  margin: { top: 3, bottom: 2 }
-).save('tmp/headers_and_footers.pdf',
-       generateDocumentOutline: false,
-       #  marginTop: 1,
-       #  paperWidth: 3,
-       displayHeaderFooter: true,
-       #  landscape: false,
-       headerTemplate: HEADER_HTML)
+  header_template:,
+  footer_template:,
+  margin_top: 3,
+  margin_bottom: 3).save('headers_and_footers.pdf')
 
-puts result
+puts "Generated headers_and_footers.pdf"
+# `open headers_and_footers.pdf`

data/examples/js_based_rendering.rb

@@ -14,9 +14,8 @@ DOCUMENT = <<~HTML
   </html>
 HTML
 
-Palapala.setup do |config|
-  config.debug = true
-end
+Palapala::Pdf.new(DOCUMENT).save('js_based_rendering.pdf')
 
-result = Palapala::Pdf.new(DOCUMENT).save('tmp/js_based_rendering.pdf')
-puts result
+puts "Generated js_based_rendering.pdf"
+
+# `open tmp/js_based_rendering.pdf`

data/examples/paged_css.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "palapala"
+
+long_text = (1..30).map { "Demonstrate a paragraph that is not split across pages." }.join(" ")
+
+def table(rows)
+  <<~HTML
+  <table>
+    <thead>
+      <tr>
+        <th>Header 1</th>
+        <th>Header 2</th>
+      </tr>
+    </thead>
+    <tbody>
+    #{ (1..rows).map { |i| "<tr><td>Row #{i}, Cell 1</td><td>Row #{i}, Cell 2</td></tr>" }.join }
+    </tbody>
+    <tfoot>
+      <tr>
+        <td>Footer 1</td>
+        <td>Footer 2</td>
+      </tr>
+    </tfoot>
+  </table>
+  HTML
+end
+
+big_table = table(35)
+small_table = table(5)
+
+document = <<~HTML
+  <html>
+    <style>
+      @page {
+        size: A4;
+        margin: 2cm;
+        margin-top: 3cm;
+        margin-bottom: 3cm;
+      }
+      body, html {
+        margin: 0;
+        padding: 0;
+        font-family: Arial, sans-serif;
+      }
+      h1 {
+        page-break-before: always;
+        border-bottom: 1px solid black;
+      }
+      h2 {
+        /* keep with next */
+        page-break-after: avoid;
+      }
+      @page:first {
+        size: A4 landscape;
+        margin: 0; /* no margin for the first page */
+        padding: 0;
+      }
+      div.titlepage {
+        background-color: black;
+        color: white;
+        font-size: 72pt;
+        text-align: center;
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        height: 100%;
+        width: 100vw;
+      }
+      table {
+        font-size: 10pt;
+        width: 100%;
+        border-collapse: collapse;
+        td, th {
+          border: 1px solid black;
+          padding: 0.5rem;
+        }
+        & thead, & tfoot {
+          tr {
+            background-color: lightgray;
+            & th, & td {
+              padding-top: 0.5rem;
+              padding-bottom: 0.5rem;
+            }
+          }
+        }
+      }
+      /* Initialize counters */
+      body {
+        counter-reset: h1Counter h2Counter;
+      }
+      /* Numbering for H1 elements */
+      h1 {
+        counter-increment: h1Counter;
+        counter-reset: h2Counter; /* Reset h2 counter when a new h1 appears */
+      }
+      h1::before {
+        content: counter(h1Counter) ". ";
+        /* font-weight: bold; */
+      }
+      /* Numbering for H2 elements */
+      h2 {
+        counter-increment: h2Counter;
+      }
+      h2::before {
+        content: counter(h1Counter) "." counter(h2Counter) " ";
+        /* font-weight: bold; */
+      }
+      /* named pages */
+      @page addendum {
+        size: A5;
+        margin: 1cm;
+        margin-top: 3cm;
+      }
+      .addendum {
+        page: addendum;
+        counter-reset: h1Counter h2Counter;
+      }
+  </style>
+    <body>
+      <div class="titlepage">
+        <c-title>Title Page</c-title>
+      </div>
+      <h1>New Section</h1>
+      <h2>Subsection tables</h2>
+      <p>This demonstrates a table with a header and footer that spans multiple pages.</p>
+      #{big_table}
+      <h2>Subsection page break inside</h2>
+      <p style="page-break-inside: avoid; text-align: justify">
+        #{long_text}
+      </p>
+      <p>Note that the section title has moved to the second page because the paragraph above was moved to the second page.</p>
+      <h1>New Section</h1>
+      <p>Page 3 content</p>
+      <p>A small table</p>
+      #{small_table}
+      <h2>Subsection</h2>
+      <p>Some content</p>
+      <h2>Subsection</h2>
+      <p>Some content</p>
+      <div class="addendum">
+        This is an addendum and the page size is A5.
+        Headers are starting again from 1.
+        <h1>Some addendum header</h1>
+        <h2>Subsection</h2>
+        <h2>Subsection</h2>
+        <h1>Some addendum header</h1>
+      </div>
+    </body>
+  </html>
+HTML
+
+def debug(color: "red")
+  <<~HTML
+    <style>
+      /* this is a class chrome assigns to the header, footer and content in the main template */
+      #header, #content, #footer {
+        border: 1px dotted #{color}; /* uncomment to see the areas */
+      }
+    </style>
+  HTML
+end
+
+def header_footer_template(debug_color: nil)
+  <<~HTML
+  #{ debug(color: debug_color) if debug_color }
+  <div style="text-align: center; font-size: 12pt; padding: 1rem; width: 100%;">#{yield}</div>
+  HTML
+end
+
+footer_template = header_footer_template do
+  "Page <span class='pageNumber'></span> of <span class='totalPages'></span>"
+end
+
+header_template = header_footer_template do
+  "Generated with Palapala PDF"
+end
+
+Palapala::Pdf.new(document,
+                  header_template:,
+                  footer_template:).save("paged_css.pdf")
+
+puts "Generated paged_css.pdf"
+
+# `open paged_css.pdf`

data/examples/performance_benchmark.rb

@@ -5,14 +5,10 @@ $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'benchmark'
 require 'palapala'
 
-debug = ARGV[0] == 'debug'
+$debug = ARGV[0] == 'debug'
+$save = ARGV[0] == 'save'
 
-Palapala.setup do |config|
-  # config.headless_chrome_url = 'http://localhost:9222'
-  config.debug = debug
-  config.defaults.merge! scale: 0.75, format: :A4
-  config.chrome_headless_shell_version = 'canary'
-end
+Palapala.debug = $debug
 
 # @param concurrency Number of concurrent threads
 # @param iterations Number of iterations per thread
@@ -22,7 +18,8 @@ def benchmark(concurrency, iterations)
       Thread.new do
         iterations.times do |j|
           doc = "Hello #{i}, world #{j}! #{Time.now}."
-          Palapala::Pdf.new(doc).save("tmp/benchmark_#{i}_#{j}.pdf")
+          pdf = Palapala::Pdf.new(doc)
+          $save ? pdf.save("tmp/benchmark_#{i}_#{j}.pdf") : pdf.binary_data
         end
       end
     end
@@ -32,18 +29,9 @@ def benchmark(concurrency, iterations)
   time
 end
 
-puts 'warmup'
+puts "Warmup..."
+benchmark(1, 5)
+puts "Starting benchmark..."
 benchmark(1, 10)
-
-# benchmark(1, 20)
-benchmark(2, 10)
-# benchmark(4, 5)
-# benchmark(5, 4)
-# benchmark(20, 1)
-
-# benchmark(1, 320)
-# benchmark(2, 320 / 2)
+benchmark(2, 20 / 2)
 benchmark(4, 320 / 4)
-# benchmark(8, 320 / 8)
-# benchmark(20, 2)
-# benchmark(40, 1)

data/lib/palapala/chrome_process.rb

@@ -25,9 +25,9 @@ module Palapala
       end
     end
 
-    # Check if a Chrome is running
+    # Check if a Chrome is running locally
     def self.chrome_running?
-      port_in_use? || # Check if the port is in use and Chrome is running externally
+      port_in_use? || # Check if the port is in use
       chrome_process_healthy? # Check if the process is still alive
     end
 
@@ -59,9 +59,9 @@ module Palapala
       system("which npx > /dev/null 2>&1")
     end
 
-    def self.spawn_chrome_headless_server
+    def self.spawn_chrome_headless_server_with_npx
       # Run the command and capture the output
-      puts "Installing latest stable chrome-headless-shell..."
+      puts "Installing/launching chrome-headless-shell@#{Palapala.chrome_headless_shell_version}"
       output, status = Open3.capture2("npx --yes @puppeteer/browsers install chrome-headless-shell@#{Palapala.chrome_headless_shell_version}")
 
       if status.success?
@@ -82,28 +82,37 @@ module Palapala
         # Display the version
         system("#{chrome_path} --version") if Palapala.debug
         # Launch chrome-headless-shell with the --remote-debugging-port parameter
-        if Palapala.debug
-          spawn(chrome_path, "--remote-debugging-port=9222", "--disable-gpu")
+        params = [ "--disable-gpu", "--remote-debugging-port=9222" ]
+        params.merge!(Palapala.chrome_params) if Palapala.chrome_params
+        pid = if Palapala.debug
+          spawn(chrome_path, *params)
         else
-          spawn(chrome_path, "--remote-debugging-port=9222", "--disable-gpu", out: "/dev/null", err: "/dev/null")
+          spawn(chrome_path, *params, out: "/dev/null", err: "/dev/null")
         end
+        Palapala.headless_chrome_url = "http://localhost:9222"
+        pid
       else
         raise "Failed to install chrome-headless-shell"
       end
     end
 
+    def self.spawn_chrome_from_path
+      params = [ "--headless", "--disable-gpu", "--remote-debugging-port=9222" ]
+      params.merge!(Palapala.chrome_params) if Palapala.chrome_params
+      # Spawn an existing chrome with the path and parameters
+      Process.spawn(chrome_path, *params)
+    end
+
     # Spawn a Chrome child process
     def self.spawn_chrome
       return if chrome_running?
 
-      if self.npx_installed?
-        @chrome_process_id = spawn_chrome_headless_server
-      else
-        params = [ "--headless", "--disable-gpu", "--remote-debugging-port=9222" ]
-        params.merge!(Palapala.chrome_params) if Palapala.chrome_params
-        # Spawn an existing chrome with the path and parameters
-        @chrome_process_id = Process.spawn(chrome_path, *params)
-      end
+      @chrome_process_id =
+        if Palapala.headless_chrome_path.nil? && self.npx_installed?
+          spawn_chrome_headless_server_with_npx
+        else
+          spawn_chrome_from_path
+        end
 
       # Wait until the port is in use
       sleep 0.1 until port_in_use?

data/lib/palapala/pdf.rb

@@ -42,20 +42,22 @@ module Palapala
                    scale: nil)
       @content = content || raise(ArgumentError, "Content is required and can't be nil")
       @opts = {}
-      @opts[:headerTemplate]    = header_template      || Palapala.defaults[:header_template]
-      @opts[:footerTemplate]    = footer_template      || Palapala.defaults[:footer_template]
-      @opts[:pageRanges]        = page_ranges          || Palapala.defaults[:page_ranges]
-      @opts[:generateTaggedPDF] = generate_tagged_pdf  || Palapala.defaults[:generate_tagged_pdf]
-      @opts[:paperWidth]        = paper_width          || Palapala.defaults[:paper_width]
-      @opts[:paperHeight]       = paper_height         || Palapala.defaults[:paper_height]
-      @opts[:landscape]         = landscape            || Palapala.defaults[:landscape]
-      @opts[:marginTop]         = margin_top           || Palapala.defaults[:margin_top]
-      @opts[:marginLeft]        = margin_left          || Palapala.defaults[:margin_left]
-      @opts[:marginBottom]      = margin_bottom        || Palapala.defaults[:margin_bottom]
-      @opts[:marginRight]       = margin_right         || Palapala.defaults[:margin_right]
-      @opts[:preferCSSPageSize] = prefer_css_page_size || Palapala.defaults[:prefer_css_page_size]
-      @opts[:printBackground]   = print_background     || Palapala.defaults[:print_background]
-      @opts[:scale]             = scale                || Palapala.defaults[:scale]
+      @opts[:headerTemplate]      = header_template      || Palapala.defaults[:header_template]
+      @opts[:footerTemplate]      = footer_template      || Palapala.defaults[:footer_template]
+      @opts[:pageRanges]          = page_ranges          || Palapala.defaults[:page_ranges]
+      @opts[:generateTaggedPDF]   = generate_tagged_pdf  || Palapala.defaults[:generate_tagged_pdf]
+      @opts[:paperWidth]          = paper_width          || Palapala.defaults[:paper_width]
+      @opts[:paperHeight]         = paper_height         || Palapala.defaults[:paper_height]
+      @opts[:landscape]           = landscape            || Palapala.defaults[:landscape]
+      @opts[:marginTop]           = margin_top           || Palapala.defaults[:margin_top]
+      @opts[:marginLeft]          = margin_left          || Palapala.defaults[:margin_left]
+      @opts[:marginBottom]        = margin_bottom        || Palapala.defaults[:margin_bottom]
+      @opts[:marginRight]         = margin_right         || Palapala.defaults[:margin_right]
+      @opts[:preferCSSPageSize]   = prefer_css_page_size || Palapala.defaults[:prefer_css_page_size]
+      @opts[:printBackground]     = print_background     || Palapala.defaults[:print_background]
+      @opts[:scale]               = scale                || Palapala.defaults[:scale]
+      @opts[:displayHeaderFooter] = (@opts[:headerTemplate] || @opts[:footerTemplate]) ? true : false
+      @opts[:encoding]            = :binary
       @opts.compact!
     end
 

data/lib/palapala/renderer.rb

@@ -22,6 +22,13 @@ module Palapala
       send_command_and_wait_for_result("Page.enable")
     end
 
+    def websocket_url
+      self.class.websocket_url
+    rescue Errno::ECONNREFUSED
+      ChromeProcess.spawn_chrome # Spawn a new Chrome process
+      self.class.websocket_url # Retry (once)
+    end
+
     # Create a thread-local instance of the renderer
     def self.thread_local_instance
       Thread.current[:renderer] ||= Renderer.new
@@ -37,6 +44,9 @@ module Palapala
     def on_message(e)
       puts "Received: #{e.data[0..64]}" if Palapala.debug
       @response = JSON.parse(e.data) # Parse the JSON response
+      if @response["error"] # Raise an error if the response contains an error
+        raise "#{@response["error"]["message"]}: #{@response["error"]["data"]} (#{@response["error"]["code"]})"
+      end
     end
 
     # Update the current ID to the next ID (increment by 1)
@@ -102,16 +112,8 @@ module Palapala
       @client.close
     end
 
-    private
-
-    # Convert the HTML content to a data URL
-    def data_url_for_html(html)
-      "data:text/html;base64,#{Base64.strict_encode64(html)}"
-    end
-
     # Open a new tab in the remote chrome and return the WebSocket URL
-    def websocket_url
-      ChromeProcess.spawn_chrome
+    def self.websocket_url
       uri = URI("#{Palapala.headless_chrome_url}/json/new")
       http = Net::HTTP.new(uri.host, uri.port)
       request = Net::HTTP::Put.new(uri)
@@ -122,5 +124,12 @@ module Palapala
       puts "WebSocket URL: #{websocket_url}" if Palapala.debug
       websocket_url
     end
+
+    private
+
+    # Convert the HTML content to a data URL
+    def data_url_for_html(html)
+      "data:text/html;base64,#{Base64.strict_encode64(html)}"
+    end
   end
 end

data/lib/palapala/version.rb

@@ -1,3 +1,3 @@
 module Palapala
-  VERSION = "0.1.9"
+  VERSION = "0.1.11"
 end

data/lib/palapala.rb

@@ -19,18 +19,16 @@ module Palapala
     # path to the headless Chrome executable when using the child process renderer
     attr_accessor :headless_chrome_path
 
-    # URL to the headless Chrome instance when using the remote renderer
+    # URL to the headless Chrome instance when using the remote renderer (priority)
     attr_accessor :headless_chrome_url
 
-    # Chrome headless shell version to use
+    # Chrome headless shell version to use (stable, beta, dev, canary, etc.)
+    # when launching a new Chrome instance using npx
     attr_accessor :chrome_headless_shell_version
   end
-  puts "setting defaults on palapala"
   self.debug = false
-  self.defaults = { displayHeaderFooter: true, encoding: :binary }
-  self.headless_chrome_path = nil
-  self.headless_chrome_url = "http://localhost:9222"
+  self.defaults = { print_background: true, prefer_css_page_size: true, margin_left: 0, margin_right: 0, margin_top: 0, margin_bottom: 0 }
+  self.headless_chrome_path = ENV.fetch("HEADLESS_CHROME_PATH", nil)
+  self.headless_chrome_url = ENV.fetch("HEADLESS_CHROME_URL", "http://localhost:9222")
   self.chrome_headless_shell_version = ENV.fetch("CHROME_HEADLESS_SHELL_VERSION", "stable")
 end
-
-puts "hoo"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: palapala_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Koen Handekyn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-29 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -56,8 +56,16 @@ files:
 - assets/images/logo-variant2.webp
 - assets/images/logo.webp
 - bin/chrome-headless-server
+- doc/installing_node.md
+- doc/paged_css.md
+- examples/all.rb
+- examples/chrome_base_header_footer_template.html
+- examples/headers_and_footers.pdf
 - examples/headers_and_footers.rb
+- examples/js_based_rendering.pdf
 - examples/js_based_rendering.rb
+- examples/paged_css.pdf
+- examples/paged_css.rb
 - examples/performance_benchmark.rb
 - lib/palapala.rb
 - lib/palapala/chrome_process.rb
@@ -66,6 +74,7 @@ files:
 - lib/palapala/version.rb
 - lib/palapala/web_socket_client.rb
 - lib/palapala_pdf.rb
+- paged_css.pdf
 - palapala_pdf.gemspec
 homepage: https://github.com/palapala-app/palapala_pdf
 licenses: