ferrum_pdf 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ea0c6aba4254ef7d958dec7d9f51048ce82e106ab068a413c1e3b83ec470b01
-  data.tar.gz: e34df1014f457e4ad42a41a5a29ab9a0d0ab42027cb8d8374aeacf6557a49833
+  metadata.gz: ad27a3b666b15d934cc1bbf678ac52bfe86fc421723c89a60a123b3599aa2c39
+  data.tar.gz: 0a9bf56518d53ff03f84b9a9143280f97effe45b26edda3695a767d871bb0f73
 SHA512:
-  metadata.gz: 68e840f65f0c0821cb8dfe6f3e249e2b5b567f8d3655c1a71a59f143beb25241aedea29fe33d95b18763a32fd5eea88bec9f6a9f4b0b6181df082544cc2453c2
-  data.tar.gz: 123f094697e37dcee391c157ca5ba379b1b9557e8a4e7c017cb7b45861936bf24e484bec74092793dd3e64e36ffaee0a98bc613f56ed9a5e4e2dfefdbf7f1ac1
+  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,34 +33,145 @@ 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 ])
+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, then pass it along to FerrumPdf.
-
-### Directly with HTML
+#### Render PDFs
 
-FerrumPdf can generate a PDF from HTML directly:
+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,
-  host: request.host_with_port,
-  protocol: request.protocol
+  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
+  }
+)
+```
+
+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
+
+Use the `render_screenshot` helper in Rails controllers to render a PDF from the current action.
+
+```ruby
+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 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
+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_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_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)
+  }
 )
 ```
 

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.1.1"
+  VERSION = "0.3.0"
 end

data/lib/ferrum_pdf.rb

@@ -1,15 +1,38 @@
 require "ferrum_pdf/version"
 require "ferrum_pdf/railtie"
-
 require "ferrum"
 
 module FerrumPdf
-  def self.browser(**options)
-    @browser ||= Ferrum::Browser.new(options)
-  end
+  DEFAULT_HEADER_TEMPLATE = "<div class='date text left'></div><div class='title text center'></div>"
+  DEFAULT_FOOTER_TEMPLATE = <<~HTML
+    <div class='url text left grow'></div>
+    <div class='text right'><span class='pageNumber'></span>/<span class='totalPages'></span></div>
+  HTML
+
+  autoload :Controller, "ferrum_pdf/controller"
+  autoload :HTMLPreprocessor, "ferrum_pdf/html_preprocessor"
+
+  mattr_accessor :include_controller_module
+  @@include_controller_module = true
+
+  class << self
+    def browser(**options)
+      @browser ||= Ferrum::Browser.new(options)
+    end
+
+    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
+
+    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
 
-  def self.render_pdf(host:, protocol:, html: nil, url: nil)
-    Tempfile.create do |file|
+    def render(host:, protocol:, html: nil, url: nil)
       browser.create_page do |page|
         if html
           page.content = FerrumPdf::HTMLPreprocessor.process(html, host, protocol)
@@ -17,48 +40,10 @@ module FerrumPdf
         else
           page.go_to(url)
         end
-        page.pdf(path: file.path)
-        file.read
+        yield page
       end
-    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
-    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
-
-  module Controller
-    extend ActiveSupport::Concern
-
-    def render_pdf(name = action_name, formats: [ :html ])
-      content = render_to_string(name, formats: formats)
-
-      FerrumPdf.render_pdf(
-        html: content,
-        host: request.host_with_port,
-        protocol: request.protocol
-      )
+    rescue Ferrum::DeadBrowserError
+      retry
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris Oliver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-20 00:00:00.000000000 Z
+date: 2024-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -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
@@ -74,8 +77,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
+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: []