ferrum_pdf 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7537d25768b2cf12df0322c63ad643c5a56dfbce85d812db0cab2f46e5f280a
-  data.tar.gz: b36728c8686eacf59543f756ff2c3daddc20a4d9eb806580dd87faa732471cf0
+  metadata.gz: ad27a3b666b15d934cc1bbf678ac52bfe86fc421723c89a60a123b3599aa2c39
+  data.tar.gz: 0a9bf56518d53ff03f84b9a9143280f97effe45b26edda3695a767d871bb0f73
 SHA512:
-  metadata.gz: 8f1b5d33362700a1ed42ff99068b968dc696fdb6f573b5c59f1f7be0207dc891cad8dd13994d8881fcb8a49ed774ed7aa7312445ccc15955f243dea30a8b66ce
-  data.tar.gz: 702c650ee2f84c7eee9562cd989cb938dac2e7ca3dfe2d0e800b9315882e6309817743c639e1f8b9b47ecb2d775a1cb023a33cc68f4ef84f526aa62247358e3d
+  metadata.gz: 9a2fa255b8d7484952959023ac2ca320ce68259857adbba20fbb0dc9c455e40e6db6a7088daf22b8f70f85da2d31f8fc2c1550a6f6a2ad97cb9920a1841bfd2b
+  data.tar.gz: ed0d20754dee52a621880ef3ffc95894749b8ddfc5796226029d2417c2b6c18e4b29fb94bbae0dd3249d9f7e56e936c6b429f7640ebc7eb33bc5ba72556fb9dc

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,51 +33,148 @@ 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
+  }
+)
+```
+
+#### Render PDFs
+
+FerrumPdf can generate a PDF from HTML or a URL:
+
+```ruby
+FerrumPdf.render_pdf(html: content)
+FerrumPdf.render_pdf(url: "https://google.com")
+```
+
+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.
+
+```ruby
+FerrumPdf.render_pdf(
+  html: content, # Provide HTML
+  url: "https://example.com", # or provide a URL to the content
+  host: request.base_url + "/", # Used for setting the host for relative paths
+  protocol: request.protocol, # Used for handling relative protocol paths
+
+  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
+  }
+)
 ```
 
-This will render the template to string with `render_to_string` in Rails, then pass it along to FerrumPdf.
+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
+
+There are two ways to render Screenshots:
+
+* [FerrumPdf.render_screenshot](#render-screenshot)
+* [render_screenshot in Rails](#render-screenshots-from-rails-controllers)
+
+#### Render Screenshot from Rails controller
 
-For example, you can add headers and footers using `pdf_options`
+Use the `render_screenshot` helper in Rails controllers to render a PDF from the current action.
 
 ```ruby
-render_pdf(pdf_options: {
-  display_header_footer: true,
-  header_template: FerrumPdf::DEFAULT_HEADER_TEMPLATE,
-  footer_template: FerrumPdf::DEFAULT_FOOTER_TEMPLATE
-})
+def show
+  respond_to do |format|
+    format.html
+    format.png {
+      screenshot = render_screenshot()
+      send_data screenshot, disposition: :inline, filename: "example.png"
+    }
+  end
+end
 ```
 
-### Directly with HTML
+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.
 
-FerrumPdf can generate a PDF from HTML directly:
+```ruby
+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 [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_pdf(html: content)
+FerrumPdf.render_screenshot(html: content)
+FerrumPdf.render_screenshot(url: "https://google.com")
 ```
 
 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.
 
 ```ruby
-FerrumPdf.render_pdf(
-  html: content,
-  host: request.host_with_port,
-  protocol: request.protocol,
-  pdf_options: {}
+FerrumPdf.render_screenshot(
+  html: "",
+  url: "",
+  root_url: "",
+  protocol: "",
+  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
-
 ## 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.

data/lib/ferrum_pdf/controller.rb

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

data/lib/ferrum_pdf/html_preprocessor.rb

@@ -0,0 +1,26 @@
+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
+    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
+    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")
+    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

@@ -2,7 +2,7 @@ module FerrumPdf
   class Railtie < ::Rails::Railtie
     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.3.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,41 @@ 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 :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))
-    end
-  end
+  mattr_accessor :include_controller_module
+  @@include_controller_module = true
 
-  # 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
+  class << self
+    def browser(**options)
+      @browser ||= Ferrum::Browser.new(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")
+    def render_pdf(html: nil, url: nil, host: nil, protocol: nil, pdf_options: {})
+      render(host: host, protocol: protocol, html: html, url: url) do |page|
+        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")
+    def render_screenshot(html: nil, url: nil, host: nil, protocol: nil, screenshot_options: {})
+      render(host: host, protocol: protocol, html: html, url: url) do |page|
+        page.screenshot(**screenshot_options.with_defaults(encoding: :binary, full: true))
+      end
     end
-    private_class_method :translate_relative_protocols
-  end
-
-  module Controller
-    extend ActiveSupport::Concern
 
-    def render_pdf(name = action_name, formats: [ :html ], pdf_options: {})
-      content = render_to_string(name, formats: formats)
-
-      FerrumPdf.render_pdf(
-        html: content,
-        host: request.host_with_port,
-        protocol: request.protocol,
-        pdf_options: pdf_options
-      )
+    def render(host:, protocol:, html: nil, url: nil)
+      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
+        yield page
+      end
+    rescue Ferrum::DeadBrowserError
+      retry
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris Oliver
@@ -38,7 +38,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 +50,8 @@ files:
 - README.md
 - Rakefile
 - lib/ferrum_pdf.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
@@ -77,5 +80,5 @@ requirements: []
 rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: PDFs for Rails using Ferrum & headless Chrome
+summary: PDFs & screenshots for Rails using Ferrum & headless Chrome
 test_files: []