ferrum_pdf 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd59867787cfd16bf19645eda1dce8c8f21541d3d8b52614e025a60847787930
-  data.tar.gz: 5dd180545309a3a0c61ba90286943404382478c44337495c81237f49953559dd
+  metadata.gz: f7537d25768b2cf12df0322c63ad643c5a56dfbce85d812db0cab2f46e5f280a
+  data.tar.gz: b36728c8686eacf59543f756ff2c3daddc20a4d9eb806580dd87faa732471cf0
 SHA512:
-  metadata.gz: 4b42648daf392f18fc9f1b8dfa947a1b26a1af29eb615af558dd23440222e80f9d846c40fe44206b1dd9f8bfcad5be64f5987559c6e833a2547b246a97093226
-  data.tar.gz: 649e5d9b57f8bfd4ad9e0c62d23cba3f1b435ec3a7a13a237e8e0cd567914e4958d93489519c103166bed3912327547bfe443af0f8f04697043a05e33658a7ed
+  metadata.gz: 8f1b5d33362700a1ed42ff99068b968dc696fdb6f573b5c59f1f7be0207dc891cad8dd13994d8881fcb8a49ed774ed7aa7312445ccc15955f243dea30a8b66ce
+  data.tar.gz: 702c650ee2f84c7eee9562cd989cb938dac2e7ca3dfe2d0e800b9315882e6309817743c639e1f8b9b47ecb2d775a1cb023a33cc68f4ef84f526aa62247358e3d

data/README.md

@@ -1,28 +1,73 @@
 # FerrumPdf
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+PDFs for Rails using [Ferrum](https://github.com/rubycdp/ferrum) & headless Chrome
 
 ## Installation
-Add this line to your application's Gemfile:
+
+Run the following or add the gem to your Gemfile:
 
 ```ruby
-gem "ferrum_pdf"
+bundle add "ferrum_pdf"
 ```
 
-And then execute:
-```bash
-$ bundle
+## Usage
+
+### Rails controllers
+
+Use the `render_pdf` helper in Rails controllers to render a PDF from the current action.
+
+```ruby
+def show
+  respond_to do |format|
+    format.html
+    format.pdf { send_data render_pdf, disposition: :inline, filename: "example.pdf" }
+  end
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install ferrum_pdf
+You can also customize which template is rendered:
+
+```ruby
+render_pdf(name = action_name, formats: [ :html ], pdf_options: {})
 ```
 
+This will render the template to string with `render_to_string` in Rails, then pass it along to FerrumPdf.
+
+For example, you can add headers and footers using `pdf_options`
+
+```ruby
+render_pdf(pdf_options: {
+  display_header_footer: true,
+  header_template: FerrumPdf::DEFAULT_HEADER_TEMPLATE,
+  footer_template: FerrumPdf::DEFAULT_FOOTER_TEMPLATE
+})
+```
+
+### Directly with HTML
+
+FerrumPdf can generate a PDF from HTML directly:
+
+```ruby
+FerrumPdf.render_pdf(html: content)
+```
+
+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: {}
+)
+```
+
+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
-Contribution directions go here.
+
+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.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ferrum_pdf/version.rb

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

data/lib/ferrum_pdf.rb

@@ -4,22 +4,25 @@ require "ferrum_pdf/railtie"
 require "ferrum"
 
 module FerrumPdf
+  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
+
   def self.browser(**options)
     @browser ||= Ferrum::Browser.new(options)
   end
 
-  def self.render_pdf(host:, protocol:, html: nil, url: nil)
-    Tempfile.create do |file|
-      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(path: file.path)
-        file.read
+  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
 
@@ -51,13 +54,14 @@ module FerrumPdf
   module Controller
     extend ActiveSupport::Concern
 
-    def render_pdf(name = action_name, formats: [ :html ])
+    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
+        protocol: request.protocol,
+        pdf_options: pdf_options
       )
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.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
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.1
+        version: 6.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.1
+        version: 6.0.0
 - !ruby/object:Gem::Dependency
   name: ferrum
   requirement: !ruby/object:Gem::Requirement
@@ -74,7 +74,7 @@ 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