ferrum_pdf 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7537d25768b2cf12df0322c63ad643c5a56dfbce85d812db0cab2f46e5f280a
-  data.tar.gz: b36728c8686eacf59543f756ff2c3daddc20a4d9eb806580dd87faa732471cf0
+  metadata.gz: 9b709d6f3d6b9472b389f08891e3ec59f90a2e0a962f034acd31a2ee4efdb79c
+  data.tar.gz: c1353b79300829afd212880fbcb76633e3fe7da2c2facc3b96d8305a7c5fc6ae
 SHA512:
-  metadata.gz: 8f1b5d33362700a1ed42ff99068b968dc696fdb6f573b5c59f1f7be0207dc891cad8dd13994d8881fcb8a49ed774ed7aa7312445ccc15955f243dea30a8b66ce
-  data.tar.gz: 702c650ee2f84c7eee9562cd989cb938dac2e7ca3dfe2d0e800b9315882e6309817743c639e1f8b9b47ecb2d775a1cb023a33cc68f4ef84f526aa62247358e3d
+  metadata.gz: a4145a37dc89ac2dbaeb0512fffafbd6056291e0521734ed57affd66a45d32489fd412d0f8fbbde7b53046ffbc8d030f602ee6914224ea76bdb1e95c78adf50f
+  data.tar.gz: 57c44da1352bac877910af6193f7104da77580bd9edaafa1d3dbbb4faa2175d8ec05215bccc40c7f85fa4e93d84089f15c1e2c606bcf886a46625f3c2b3ba61a

data/README.md

@@ -1,9 +1,13 @@
 # FerrumPdf
 
-PDFs for Rails using [Ferrum](https://github.com/rubycdp/ferrum) & headless Chrome
+PDFs & screentshots for Rails using [Ferrum](https://github.com/rubycdp/ferrum) & headless Chrome.
+
+Inspired by [Grover](https://github.com/Studiosity/grover).
 
 ## Installation
 
+First, make sure Chrome is installed.
+
 Run the following or add the gem to your Gemfile:
 
 ```ruby
@@ -12,7 +16,16 @@ bundle add "ferrum_pdf"
 
 ## Usage
 
-### Rails controllers
+You can use FerrumPdf to render [PDFs](#-pdfs) and [Screenshots](#-screenshots)
+
+### 📄 PDFs
+
+There are two ways to render PDFs:
+
+* [FerrumPdf.render_pdf](#render-pdfs)
+* [render_pdf in Rails](#render-pdfs-from-rails-controllers)
+
+#### Render PDFs from Rails controllers
 
 Use the `render_pdf` helper in Rails controllers to render a PDF from the current action.
 
@@ -20,54 +33,235 @@ Use the `render_pdf` helper in Rails controllers to render a PDF from the curren
 def show
   respond_to do |format|
     format.html
-    format.pdf { send_data render_pdf, disposition: :inline, filename: "example.pdf" }
+    format.pdf {
+      pdf = render_pdf()
+      send_data pdf, disposition: :inline, filename: "example.pdf"
+    }
   end
 end
 ```
 
-You can also customize which template is rendered:
+You can also customize which template is rendered. This will render the template to string with `render_to_string` in Rails, then pass it along to Chrome. For example, you can add headers and footers using `pdf_options` and use a specific layout:
 
 ```ruby
-render_pdf(name = action_name, formats: [ :html ], pdf_options: {})
+render_pdf(
+  layout: "pdf,
+  pdf_options: {
+    display_header_footer: true,
+    header_template: FerrumPdf::DEFAULT_HEADER_TEMPLATE,
+    footer_template: FerrumPdf::DEFAULT_FOOTER_TEMPLATE
+  }
+)
 ```
 
-This will render the template to string with `render_to_string` in Rails, then pass it along to FerrumPdf.
+#### Render PDFs
 
-For example, you can add headers and footers using `pdf_options`
+FerrumPdf can generate a PDF from HTML or a URL:
 
 ```ruby
-render_pdf(pdf_options: {
-  display_header_footer: true,
-  header_template: FerrumPdf::DEFAULT_HEADER_TEMPLATE,
-  footer_template: FerrumPdf::DEFAULT_FOOTER_TEMPLATE
-})
+FerrumPdf.render_pdf(html: content)
+FerrumPdf.render_pdf(url: "https://google.com")
 ```
 
-### Directly with HTML
+The full list of options:
+
+```ruby
+FerrumPdf.render_pdf(
+  url: "https://example.com/page", # Provide a URL to the content
+
+  html: content, # or provide HTML
+  base_url: request.base_url, # Preprocesses `html` to convert relative paths and protocols. Example: "https://example.org"
+
+  authorize: { user: "username", password: "password" }, # Used for authenticating with basic auth
+  wait_for_idle_options: { connections: 0, duration: 0.05, timeout: 5 }, # Used for setting network wait_for_idle options
+
+  pdf_options: {
+    landscape: false, # paper orientation
+    scale: 1, # Scale of the webpage rendering
+    format: nil,
+    paper_width: 8.5, # Paper width in inches
+    paper_height: 11, # Paper height in inches
+    page_ranges: nil, # Paper ranges to print "1-5, 8 11-13"
+
+    # Margins (in inches, defaults to 1cm)
+    margin_top: 0.4,
+    margin_bottom: 0.4,
+    margin_left: 0.4,
+    margin_right: 0.4,
+
+    # Header, footer, and background options
+    #
+    # Variables can be used with CSS classes. For example <span class="date"></span>
+    # * date: formatted print date
+    # * title: document title
+    # * url: document location
+    # * pageNumber: current page number
+    # *totalPages: total pages in the document
+
+    display_header_footer: false,
+    print_background: false, # Print background graphics
+    header_template: "", # HTML template for the header
+    footer_template: "", # HTML template for the footer
+  }
+)
+```
+
+See [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) and [Ferrum's `#pdf` docs](https://github.com/rubycdp/ferrum?tab=readme-ov-file#pdfoptions--string--boolean) for the full set of options.
+
+### 🎆 Screenshots
 
-FerrumPdf can generate a PDF from HTML directly:
+There are two ways to render Screenshots:
+
+* [FerrumPdf.render_screenshot](#render-screenshots)
+* [render_screenshot in Rails](#render-screenshots-from-rails-controllers)
+
+#### Render Screenshots from Rails controllers
+
+Use the `render_screenshot` helper in Rails controllers to render a PDF from the current action.
 
 ```ruby
-FerrumPdf.render_pdf(html: content)
+def show
+  respond_to do |format|
+    format.html
+    format.png {
+      screenshot = render_screenshot()
+      send_data screenshot, disposition: :inline, filename: "example.png"
+    }
+  end
+end
 ```
 
-You can also pass host and protocol to convert any relative paths to full URLs. This is helpful for converting relative asset paths to full URLs.
+You can also customize which template is rendered. This will render the template to string with `render_to_string` in Rails, then pass it along to Chrome.
 
 ```ruby
-FerrumPdf.render_pdf(
-  html: content,
-  host: request.host_with_port,
-  protocol: request.protocol,
-  pdf_options: {}
+render_screenshot(
+  screenshot_options: {
+    format: "png" # or "jpeg"
+    quality: nil # Integer 0-100 works for jpeg only
+    full: true # Boolean whether you need full page screenshot or a viewport
+    selector: nil # String css selector for given element, optional
+    area: nil # Hash area for screenshot, optional. {x: 0, y: 0, width: 100, height: 100}
+    scale: nil # Float zoom in/out
+    background_color: nil # Ferrum::RGBA.new(0, 0, 0, 0.0)
+  }
 )
 ```
 
-See Chrome DevTools Protocol docs: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF
-And Ferrum's `#pdf` docs: https://github.com/rubycdp/ferrum?tab=readme-ov-file#pdfoptions--string--boolean
+See [Ferrum screenshot docs](https://github.com/rubycdp/ferrum?tab=readme-ov-file#screenshotoptions--string--integer) for the full set of options.
+
+#### Render Screenshots
+
+FerrumPdf can generate a screenshot from HTML or a URL:
+
+```ruby
+FerrumPdf.render_screenshot(html: content)
+FerrumPdf.render_screenshot(url: "https://google.com")
+```
+
+The full list of options
+
+```ruby
+FerrumPdf.render_screenshot(
+  url: "https://example.com/page", # Provide a URL to the content
+
+  html: content, # or provide HTML
+  base_url: request.base_url, # Preprocesses `html` to convert relative paths and protocols. Example: "https://example.org"
+
+  screenshot_options: {
+    format: "png" # or "jpeg"
+    quality: nil # Integer 0-100 works for jpeg only
+    full: true # Boolean whether you need full page screenshot or a viewport
+    selector: nil # String css selector for given element, optional
+    area: nil # Hash area for screenshot, optional. {x: 0, y: 0, width: 100, height: 100}
+    scale: nil # Float zoom in/out
+    background_color: nil # Ferrum::RGBA.new(0, 0, 0, 0.0)
+  }
+)
+```
+
+## Configuring the Browser
+
+You can set the default browser options with the configure block.
+
+See [Ferrum's Customization docs](https://github.com/rubycdp/ferrum?tab=readme-ov-file#customization) for a full list of options.
+
+```ruby
+FerrumPdf.configure do |config|
+  config.window_size = [1920, 1080]
+
+  # config.process_timeout = 30 # defaults to 10
+  # config.browser_path = '/usr/bin/chromium'
+
+  # For use with Docker, but ensure you trust any sites visited
+  # config.browser_options = {
+  #   "no-sandbox" => true
+  # }
+end
+```
+
+For Docker, `seccomp` is recommend over `--no-sandbox` for security: https://github.com/jlandure/alpine-chrome?tab=readme-ov-file#3-ways-to-securely-use-chrome-headless-with-this-image
+
+To add Chrome to your Docker image:
+
+```dockerfile
+RUN apt-get update && apt-get install gnupg wget -y && \
+    wget --quiet --output-document=- https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/google-archive.gpg && \
+    sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' && \
+    apt-get update && \
+    apt-get install google-chrome-stable -y && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+### Multiple Browser Support
+
+```ruby
+# Create two browsers using the FerrumPdf config, but overriding `window_size`
+FerrumPdf.add_browser(:small, window_size: [1024, 768]))
+FerrumPdf.add_browser(:large, window_size: [1920, 1080]))
+
+FerrumPdf.render_pdf(url: "https://example.org", browser: :small)
+FerrumPdf.render_pdf(url: "https://example.org", browser: :large)
+```
+
+You can also create a `Ferrum::Browser` instance and pass it in as `browser`:
+
+```ruby
+FerrumPdf.render_pdf(url: "https://example.org", browser: Ferrum::Browser.new)
+```
+
+## Debugging
+
+One option for debugging is to use Chrome in regular, non-headless mode:
+
+```ruby
+FerrumPdf.configure do |config|
+  config.headless = false
+end
+```
+
+FerrumPdf also allows you to pass a block for debugging. This block is executed after loading the page but before rendering the PDF or screenshot.
+
+```ruby
+FerrumPdf.render_pdf(url: "https://gooogle.com") do |browser, page|
+  # Open Chrome DevTools to remotely inspect the browser
+  browser.debug
+
+  # Or pause and poke around
+  binding.irb
+end
+```
+
+The block will receive the `Ferrum::Browser` and `Ferrum::Page` objects which you can use for debugging.
 
 ## Contributing
 
 If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
 
+To run the test suite, run:
+
+```bash
+bin/test
+```
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ferrum_pdf/assets_helper.rb

@@ -0,0 +1,65 @@
+module FerrumPdf
+  module AssetsHelper
+    class BaseAsset
+      def initialize(asset)
+        @asset = asset
+      end
+    end
+
+    class PropshaftAsset < BaseAsset
+      def content_type
+        @asset.content_type.to_s
+      end
+
+      def content
+        @asset.content
+      end
+    end
+
+    class SprocketsAsset < BaseAsset
+      def content_type
+        @asset.content_type
+      end
+
+      def content
+        @asset.source
+      end
+    end
+
+    class AssetFinder
+      class << self
+        def find(path)
+          if Rails.application.assets.respond_to?(:load_path)
+            propshaft_asset(path)
+          elsif Rails.application.assets.respond_to?(:find_asset)
+            sprockets_asset(path)
+          else
+            nil
+          end
+        end
+
+        def propshaft_asset(path)
+          (asset = Rails.application.assets.load_path.find(path)) ? PropshaftAsset.new(asset) : nil
+        end
+
+        def sprockets_asset(path)
+          (asset = Rails.application.assets.find_asset(path)) ? SprocketsAsset.new(asset) : nil
+        end
+      end
+    end
+
+    def ferrum_pdf_inline_stylesheet(path)
+      (asset = AssetFinder.find(path)) ? "<style>#{asset.content}</style>".html_safe : nil
+    end
+
+    def ferrum_pdf_inline_javascript(path)
+      (asset = AssetFinder.find(path)) ? "<script>#{asset.content}</script>".html_safe : nil
+    end
+
+    def ferrum_pdf_base64_asset(path)
+      return nil unless (asset = AssetFinder.find(path))
+
+      "data:#{asset.content_type};base64,#{Base64.encode64(asset.content).gsub(/\s+/, '')}"
+    end
+  end
+end

data/lib/ferrum_pdf/controller.rb

@@ -0,0 +1,27 @@
+module FerrumPdf
+  module Controller
+    extend ActiveSupport::Concern
+
+    def render_pdf(pdf_options: {}, **rendering, &block)
+      content = render_to_string(**rendering.with_defaults(formats: [ :html ]))
+
+      FerrumPdf.render_pdf(
+        html: content,
+        base_url: request.base_url,
+        pdf_options: pdf_options,
+        &block
+      )
+    end
+
+    def render_screenshot(screenshot_options: {}, **rendering, &block)
+      content = render_to_string(**rendering.with_defaults(formats: [ :html ]))
+
+      FerrumPdf.render_screenshot(
+        html: content,
+        base_url: request.base_url,
+        screenshot_options: screenshot_options,
+        &block
+      )
+    end
+  end
+end

data/lib/ferrum_pdf/html_preprocessor.rb

@@ -0,0 +1,31 @@
+module FerrumPdf
+  # Helper module for preparing HTML for conversion
+  #
+  # Sourced from the PDFKit project
+  # @see https://github.com/pdfkit/pdfkit
+  module HTMLPreprocessor
+    # Change relative paths to absolute, and relative protocols to absolute protocols
+    #
+    #   process("Some HTML", "https://example.org")
+    #
+    def self.process(html, base_url)
+      base_url += "/" unless base_url.end_with? "/"
+      protocol = base_url.split("://").first
+      html = translate_relative_paths(html, base_url) if base_url
+      html = translate_relative_protocols(html, protocol) if protocol
+      html
+    end
+
+    def self.translate_relative_paths(html, base_url)
+      # Try out this regexp using rubular http://rubular.com/r/hiAxBNX7KE
+      html.gsub(%r{(href|src)=(['"])/([^/"']([^"']*|[^"']*))?['"]}, "\\1=\\2#{base_url}\\3\\2")
+    end
+    private_class_method :translate_relative_paths
+
+    def self.translate_relative_protocols(body, protocol)
+      # Try out this regexp using rubular http://rubular.com/r/0Ohk0wFYxV
+      body.gsub(%r{(href|src)=(['"])//([^"']*|[^"']*)['"]}, "\\1=\\2#{protocol}://\\3\\2")
+    end
+    private_class_method :translate_relative_protocols
+  end
+end

data/lib/ferrum_pdf/railtie.rb

@@ -1,8 +1,14 @@
 module FerrumPdf
   class Railtie < ::Rails::Railtie
+    initializer "ferrum_pdf.assets_helper" do
+      ActiveSupport.on_load(:action_view) do
+        include FerrumPdf::AssetsHelper if FerrumPdf.include_assets_helper_module
+      end
+    end
+
     initializer "ferrum_pdf.controller" do
       ActiveSupport.on_load(:action_controller) do
-        include FerrumPdf::Controller
+        include FerrumPdf::Controller if FerrumPdf.include_controller_module
       end
     end
   end

data/lib/ferrum_pdf/version.rb

@@ -1,3 +1,3 @@
 module FerrumPdf
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/ferrum_pdf.rb

@@ -1,6 +1,5 @@
 require "ferrum_pdf/version"
 require "ferrum_pdf/railtie"
-
 require "ferrum"
 
 module FerrumPdf
@@ -10,59 +9,96 @@ module FerrumPdf
     <div class='text right'><span class='pageNumber'></span>/<span class='totalPages'></span></div>
   HTML
 
-  def self.browser(**options)
-    @browser ||= Ferrum::Browser.new(options)
-  end
+  autoload :AssetsHelper, "ferrum_pdf/assets_helper"
+  autoload :Controller, "ferrum_pdf/controller"
+  autoload :HTMLPreprocessor, "ferrum_pdf/html_preprocessor"
 
-  def self.render_pdf(host:, protocol:, html: nil, url: nil, pdf_options: {})
-    browser.create_page do |page|
-      if html
-        page.content = FerrumPdf::HTMLPreprocessor.process(html, host, protocol)
-        page.network.wait_for_idle
-      else
-        page.go_to(url)
-      end
-      page.pdf(**pdf_options.with_defaults(encoding: :binary))
+  mattr_accessor :include_assets_helper_module, default: true
+  mattr_accessor :include_controller_module, default: true
+  mattr_accessor :browsers, default: {}
+  mattr_accessor :config, default: ActiveSupport::OrderedOptions.new.merge(
+    window_size: [ 1920, 1080 ]
+  )
+
+  class << self
+    def configure
+      yield config
     end
-  end
 
-  # Helper module for preparing HTML for conversion
-  #
-  # Sourced from the PDFKit project
-  # @see https://github.com/pdfkit/pdfkit
-  module HTMLPreprocessor
-    # Change relative paths to absolute, and relative protocols to absolute protocols
-    def self.process(html, root_url, protocol)
-      html = translate_relative_paths(html, root_url) if root_url
-      html = translate_relative_protocols(html, protocol) if protocol
-      html
+    def add_browser(name, **options)
+      @@browsers[name] = Ferrum::Browser.new(@@config.merge(options))
     end
 
-    def self.translate_relative_paths(html, root_url)
-      # Try out this regexp using rubular http://rubular.com/r/hiAxBNX7KE
-      html.gsub(%r{(href|src)=(['"])/([^/"']([^"']*|[^"']*))?['"]}, "\\1=\\2#{root_url}\\3\\2")
+    # Renders HTML or URL to PDF
+    #
+    #   render_pdf(url: "https://example.org/receipts/example.pdf")
+    #   render_pdf(html: "<h1>Hello world</h1>")
+    #
+    # For rendering HTML, we also need the base_url for preprocessing URLs with relative paths & protocols
+    #
+    #   render_pdf(html: "<h1>Hello world</h1>", base_url: "https://example.org/")
+    #
+    def render_pdf(pdf_options: {}, **load_page_args)
+      load_page(**load_page_args) do |browser, page|
+        yield browser, page if block_given?
+        page.pdf(**pdf_options.with_defaults(encoding: :binary))
+      end
     end
-    private_class_method :translate_relative_paths
 
-    def self.translate_relative_protocols(body, protocol)
-      # Try out this regexp using rubular http://rubular.com/r/0Ohk0wFYxV
-      body.gsub(%r{(href|src)=(['"])//([^"']*|[^"']*)['"]}, "\\1=\\2#{protocol}://\\3\\2")
+    # Renders HTML or URL to Screenshot
+    #
+    # render_screenshot(url: "https://example.org/receipts/example.pdf")
+    # render_screenshot(html: "<h1>Hello world</h1>")
+    #
+    # For rendering HTML, we also need the base_url for preprocessing URLs with relative paths & protocols
+    #
+    #   render_screenshot(html: "<h1>Hello world</h1>", base_url: "https://example.org/")
+    #
+    def render_screenshot(screenshot_options: {}, **load_page_args)
+      load_page(**load_page_args) do |browser, page|
+        yield browser, page if block_given?
+        page.screenshot(**screenshot_options.with_defaults(encoding: :binary, full: true))
+      end
     end
-    private_class_method :translate_relative_protocols
-  end
 
-  module Controller
-    extend ActiveSupport::Concern
+    # Loads page into the browser to be used for rendering PDFs or screenshots
+    #
+    # This automatically applies HTML preprocessing if `html:` is present
+    #
+    def load_page(url: nil, html: nil, base_url: nil, authorize: nil, wait_for_idle_options: nil, browser: :default, retries: 1)
+      try = 0
+
+      # Lookup browser if a name was passed
+      browser = @@browsers[browser] || add_browser(browser) if browser.is_a? Symbol
+
+      # Automatically restart the browser if it was disconnected
+      browser.restart unless browser.client.present?
+
+      # Closes page automatically after block finishes
+      # https://github.com/rubycdp/ferrum/blob/main/lib/ferrum/browser.rb#L169
+      browser.create_page do |page|
+        page.network.authorize(**authorize) { |req| req.continue } if authorize
 
-    def render_pdf(name = action_name, formats: [ :html ], pdf_options: {})
-      content = render_to_string(name, formats: formats)
+        # Load content
+        if html
+          page.content = FerrumPdf::HTMLPreprocessor.process(html, base_url)
+        else
+          page.go_to(url)
+        end
 
-      FerrumPdf.render_pdf(
-        html: content,
-        host: request.host_with_port,
-        protocol: request.protocol,
-        pdf_options: pdf_options
-      )
+        # Wait for everything to load
+        page.network.wait_for_idle(**wait_for_idle_options)
+
+        yield browser, page
+      end
+    rescue Ferrum::DeadBrowserError
+      try += 1
+      if try <= retries
+        browser.restart
+        retry
+      else
+        raise
+      end
     end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chris Oliver
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,7 +37,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
-description: Export PDFs from HTML in Rails using Ferrum & headless Chrome
+description: Export PDFs & screenshots from HTML in Rails using Ferrum & headless
+  Chrome
 email:
 - excid3@gmail.com
 executables: []
@@ -49,6 +49,9 @@ files:
 - README.md
 - Rakefile
 - lib/ferrum_pdf.rb
+- lib/ferrum_pdf/assets_helper.rb
+- lib/ferrum_pdf/controller.rb
+- lib/ferrum_pdf/html_preprocessor.rb
 - lib/ferrum_pdf/railtie.rb
 - lib/ferrum_pdf/version.rb
 - lib/tasks/ferrum_pdf_tasks.rake
@@ -59,7 +62,6 @@ metadata:
   homepage_uri: https://github.com/excid3/ferrum_pdf
   source_code_uri: https://github.com/excid3/ferrum_pdf
   changelog_uri: https://github.com/excid3/ferrum_pdf/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: PDFs for Rails using Ferrum & headless Chrome
+summary: PDFs & screenshots for Rails using Ferrum & headless Chrome
 test_files: []