palapala_pdf 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ceecc9fff4323ef8cdf26b9e20aeb35f21610e8b55f716a0b8e0c27c0e38613
-  data.tar.gz: 4f9f412514ad9a9b63e4b6484488ff245bb0769352374a652845749ac230b6e6
+  metadata.gz: f4a479307ef1a9d4ebe8aee6d8b3f2d7da1f96c854252ba69cc19bbaba45f6cf
+  data.tar.gz: d8f184150f5b43eb1abcbaceaf4e37a643b9a3fdfbcca7dff075f56ec1d5622b
 SHA512:
-  metadata.gz: 62c62530b7034a687012bea224b8d284616cef97a2e749ab26151ee2e925ffb3b72ab0d96b13e970ab9d2630bca188c1e134ca59e81bcb37f245dbb1b888f000
-  data.tar.gz: 352245729e62e3df55c23848b684af2deb642b3d506de83ef71f8cf0bc4964ac94219baac3e06e776957f15cb15fba41cf3f864ecb4a381c7e057bed75e598f6
+  metadata.gz: a094985ed908279fac68ed43d7fbf83b333591d97ca723af840263425c94d530647388417bd935618680f402e617af6097c55eb8e09a98dd69df5a61a7eaa495
+  data.tar.gz: '07382dfb24841886ba2c09ae20b240701cb57d37963f16fd8e9e135f299f63962a5c4f09f6f14d4b2a0e86ae33a80cd2bc45426605b9137f3cdbc70c50cb34b2'

data/README.md

@@ -2,13 +2,13 @@
 
 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 stack, this project builds on [Ferrum](https://github.com/rubycdp/ferrum) to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficient, thread-safe operations, providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.
+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 builds on [Ferrum](https://github.com/rubycdp/ferrum) to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficient, thread-safe operations, providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.
 
-This is how easy and powerfull PDF generation should be:
+This is how easy and powerfull PDF generation should be in Ruby:
 
 ```ruby
 require "palapala"
-Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
+Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
 ```
 
 And this while having the most modern HTML/CSS/JS availlable to you: flex, grid, canvas, you name it.
@@ -57,7 +57,7 @@ end
 
 2. **Create a PDF from HTML**:
 
-Create a PDF file from HTML in IRB
+Create a PDF file from HTML in `irb`
 
 ```sh
 gem install palapala_pdf
@@ -65,22 +65,105 @@ gem install palapala_pdf
 
 in IRB, load palapala and create a PDF from an HTML snippet:
 
-```sh
->irb
+```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.
+
 ```ruby
 require "palapala"
-Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
+binary_data = Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
 ```
 
-Instantiate a new Palapala::Pdf object with your HTML content and generate the PDF 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
+
+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_html` and `footer_html` options. These allow you to insert HTML content directly into the header or footer areas.
 
 ```ruby
-require "palapala"
-binary_data = Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
+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")
+```
+
+### Page size, orientation and margins
+
+#### With CSS
+
+todo example
+
+#### As params
+
+todo example
+
+## JS based rendering
+
+```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>
 ```
 
+## Customisation
+
+### Ferrum
+
+It is Ruby clean and high-level API to Chrome. All you need is Ruby and
+[Chrome](https://www.google.com/chrome/) or
+[Chromium](https://www.chromium.org/). Ferrum connects to the browser by [CDP
+protocol](https://chromedevtools.github.io/devtools-protocol/).
+
+Highlighting some key Ferrum options in the context of PDF generation
+
+* options `Hash`
+  * `:headless` (String | Boolean) - Set browser as headless or not, `true` by default. You can set `"new"` to support
+      [new headless mode](https://developer.chrome.com/articles/new-headless/).
+  * `:xvfb` (Boolean) - Run browser in a virtual framebuffer, `false` by default.
+  * `:extensions` (Array[String | Hash]) - An array of paths to files or JS
+      source code to be preloaded into the browser e.g.:
+      `["/path/to/script.js", { source: "window.secret = 'top'" }]`
+  * `:logger` (Object responding to `puts`) - When present, debug output is
+      written to this object.
+  * `:timeout` (Numeric) - The number of seconds we'll wait for a response when
+      communicating with browser. Default is 5.
+  * `:js_errors` (Boolean) - When true, JavaScript errors get re-raised in Ruby.
+  * `:pending_connection_errors` (Boolean) - When main frame is still waiting for slow responses while timeout is
+      reached `PendingConnectionsError` is raised. It's better to figure out why you have slow responses and fix or
+      block them rather than turn this setting off. Default is true.
+  * `:browser_path` (String) - Path to Chrome binary, you can also set ENV
+      variable as `BROWSER_PATH=some/path/chrome`.
+  * `:browser_options` (Hash) - Additional command line options,
+      [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
+      e.g. `{ "ignore-certificate-errors" => nil }`
+  * `:ignore_default_browser_options` (Boolean) - Ferrum has a number of default
+      options it passes to the browser, if you set this to `true` then only
+      options you put in `:browser_options` will be passed to the browser,
+      except required ones of course.
+  * `:url` (String) - URL for a running instance of Chrome. If this is set, a
+      browser process will not be spawned.
+  * `:process_timeout` (Integer) - How long to wait for the Chrome process to
+      respond on startup.
+  * `:ws_max_receive_size` (Integer) - How big messages to accept from Chrome
+      over the web socket, in bytes. Defaults to 64MB. Incoming messages larger
+      than this will cause a `Ferrum::DeadBrowserError`.
+
+More [details](https://github.com/rubycdp/ferrum#customization)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -109,6 +192,8 @@ Your support is greatly appreciated and helps maintain the project!
 
 For Chrome, mode headless=new seems to be slower for pdf rendering cases.
 
+On mac m3 (aug 24), chromium (brew install chromium) is about 3x slower then chrome? Maybe the chromium that get's installed is not ARM optimized?
+
 ## Primitive benchmark
 
 On a macbook m3, the throughput for 'hello world' PDF generation can reach around 25 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)
@@ -123,10 +208,57 @@ Total time c:5, n:4 = 0.72492800001055 seconds
 Total time c:20, n:1 = 0.7156629998935387 seconds
 ```
 
-## Advanced stuf
 
-### Headers and Footers
+## Rails
+
+### `send_data`
+
+The `send_data` method in Rails is used to send binary data as a file download to the user's browser. It allows you to send any type of data, such as PDF files, images, or CSV files, directly to the user without saving the file on the server.
+
+Here's an example of how to use `send_data` to send a PDF file:
+
+```ruby
+def download_pdf
+    pdf_data = Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
+    send_data pdf_data, filename: "document.pdf", type: "application/pdf"
+end
+```
+
+In this example, `pdf_data` is the binary data of the PDF file. The `filename` option specifies the name of the file that will be downloaded by the user, and the `type` option specifies the MIME type of the file.
+
+### `render_to_string`
+
+The `render_to_string` method in Rails is used to render a view template to a string without sending it as a response to the user's browser. It allows you to generate HTML or other text-based content that can be used in various ways, such as sending it as an email, saving it to a file, or manipulating it further before sending it as a response.
+
+Here's an example of how to use `render_to_string` to render a view template to a string:
+
+```ruby
+def download_pdf
+    html_string = render_to_string(template: "example/template", layout: "print", locals: { } )
+    pdf_data = Palapala::PDF.new(html_string).binary_data
+    send_data pdf_data, filename: "document.pdf", type: "application/pdf"
+end
+```
+
+## Docker
+
+In docker as root you must pass the no-sandbox browser option:
+
+```ruby
+Palapala.setup do |config|
+  config.ferrum_opts = { 'no-sandbox': nil }
+end
+```
+(from Ferrum) It has also been reported that the Chrome process repeatedly crashes when running inside a Docker container on an M1 Mac preventing Ferrum from working. Ferrum should work as expected when deployed to a Docker container on a non-M1 Mac.
+
+## Heroku
+
+possible buildpacks
+
+https://github.com/heroku/heroku-buildpack-chrome-for-testing
+
+this buildpack install chrome and chromedriver, which is actually not needed, but it's maintained
 
-### Title pages
+https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-google-chrome
 
-### Page sizes in CSS
+this buildpack installs chrome, which is all we need, but it's deprecated

data/lib/palapala/pdf.rb

@@ -4,20 +4,19 @@ require 'ferrum'
 
 module Palapala
   # Page class to generate PDF from HTML content using Chrome in headless mode in a thread-safe way
-  class Pdf
+  # @param page_ranges Empty string means all pages, e.g., "1-3, 5, 7-9"
+  class PDF
     def initialize(content = nil,
                    url: nil,
-                   path: nil,
                    header_html: nil,
                    footer_html: nil,
-                   generate_tagged_pdf: false,
-                   prefer_css_page_size: true,
+                   generate_tagged_pdf: Palapala.defaults.fetch(:generate_tagged_pdf, false),
+                   prefer_css_page_size: Palapala.defaults.fetch(:prefer_css_page_size, true),
                    scale: Palapala.defaults.fetch(:scale, 1),
-                   page_ranges: Palapala.defaults.fetch(:page_ranges, ''),
+                   page_ranges: Palapala.defaults.fetch(:page_ranges, nil),
                    margin: Palapala.defaults.fetch(:margin, {}))
       @content = content
       @url = url
-      @path = path
       @header_html = header_html
       @footer_html = footer_html
       @generate_tagged_pdf = generate_tagged_pdf
@@ -27,11 +26,21 @@ module Palapala
       @margin = margin
     end
 
+    def binary_data(**opts)
+      pdf(**opts)
+    end
+
+    def save(path, **opts)
+      pdf(path:, **opts)
+    end
+
+    private
+
     def pdf(**opts)
       browser_context = browser.contexts.create
       browser_page = browser_context.page
       # # output console logs for this page
-      if opts[:debug]
+      if Palapala.debug
         browser_page.on('Runtime.consoleAPICalled') do |params|
           params['args'].each { |r| puts(r['value']) }
         end
@@ -40,25 +49,15 @@ module Palapala
       url = @url || data_url
       browser_page.go_to(url)
       # Wait for the page to load
-      browser_page.network.wait_for_idle
+      # browser_page.network.wait_for_idle
       # Generate PDF
       pdf_binary_data = browser_page.pdf(**opts_with_defaults.merge(opts))
       # Dispose the context
       browser_context.dispose
       # Return the PDF data
-      pdf_binary_data
+      opts[:path] ? opts[:path] : pdf_binary_data
     end
 
-    def binary_data(**opts)
-      pdf(**opts)
-    end
-
-    def save(path, **opts)
-      pdf(path:, **opts)
-    end
-
-    private
-
     def data_url
       encoded_html = Base64.strict_encode64(@content)
       "data:text/html;base64,#{encoded_html}"
@@ -68,23 +67,24 @@ module Palapala
       opts = { scale: @scale,
                printBackground: true,
                dispayHeaderFooter: true,
-               pageRanges: @page_ranges, # Empty string means all pages, e.g., "1-3, 5, 7-9"
                encoding: :binary,
-               preferCSSPageSize: true,
-               headerTemplate: @header_html || '',
-               footerTemplate: @footer_html || '' }
+               preferCSSPageSize: @prefer_css_page_size }
 
+      opts[:headerTemplate] = @header_html unless @header_html.nil?
+      opts[:footerTemplate] = @footer_html unless @footer_html.nil?
+      opts[:pageRanges] = @page_ranges unless @page_ranges.nil?
       opts[:path] = @path unless @path.nil?
       opts[:generateTaggedPDF] = @generate_tagged_pdf unless @generate_tagged_pdf.nil?
       opts[:format] = @format unless @format.nil?
-      opts[:paperWidth] = @paper_width unless @paper_width.nil?
-      opts[:paperHeight] = @paper_height unless @paper_height.nil?
+      # opts[:paperWidth] = @paper_width unless @paper_width.nil?
+      # opts[:paperHeight] = @paper_height unless @paper_height.nil?
       opts[:landscape] = @landscape unless @landscape.nil?
       opts[:marginTop] = @margin[:top] unless @margin[:top].nil?
       opts[:marginLeft] = @margin[:left] unless @margin[:left].nil?
       opts[:marginBottom] = @margin[:bottom] unless @margin[:bottom].nil?
       opts[:marginRight] = @margin[:right] unless @margin[:right].nil?
 
+      puts "opts: #{opts}" if Palapala&.debug
       opts
     end
 

data/lib/palapala/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Palapala
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/lib/palapala.rb

@@ -8,19 +8,13 @@ module Palapala
     yield self
   end
 
-  def self.ferrum_opts=(ferrum_opts)
-    @ferrum_opts = ferrum_opts
+  class << self
+    attr_accessor :ferrum_opts
+    attr_accessor :defaults
+    attr_accessor :debug
   end
 
-  def self.ferrum_opts
-    @ferrum_opts
-  end
-
-  def self.defaults=(defaults)
-    @defaults = defaults
-  end
-
-  def self.defaults
-    @defaults ||= {}
-  end
+  self.ferrum_opts = {}
+  self.defaults = {}
+  self.debug = false
 end

data/palapala_pdf.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency 'ferrum', '~> 0.15'
+  spec.add_dependency 'ferrum', '~> 0'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: palapala_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Koen Handekyn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-23 00:00:00.000000000 Z
+date: 2024-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0'
 description: This gem uses Ferrum to render HTML into a PDF using Chrom(e)(ium) with
   minimal dependencies.
 email: