Introducing the "Browserless" gem - a Ruby gem that provides a convenient wrapper around the Browserless PDF API. Browserless relies on puppeteer to convert modern CSS into a PDF. The goal of this gem is to enables developers to easily generate PDF documents from the HTML you already have.
By utilizing a managed service such as Browserless.io, you can concentrate on your core application functionality while relying on a simple API call to address your PDF generation requirements.
The free trial of browerless includes upto 1,000 PDFs a month, 10 concurrent browsers.
Benefits
- turn your existing HTML and CSS into a PDF
- supports modern CSS frameworks such as TailwindCSS
- no need to install, run and maintain puppeteer
Add this line to your application's Gemfile:
gem'browserless'And then execute: ** $ bundle install**
Or install it yourself as:
$ gem install browserless
Add your Browserless.io API key in an initializer file, like config/browserless.rb. You can set default configuration options in the initializer.
Browserless.configuredo |config|
config.api_key="your_api_key_here"config.emulate_media="print"# choose between print or screen (default)config.style_tag=File.read(Rails.root.join("app/assets/builds/application.css"))# Pass public asset URL or CSS string content config.options={landscape: false# defaultprint_background: false,format: "A4"# default https://pptr.dev/api/puppeteer.paperformat#remarksdisplay_header_footer: false,# default header_template: "<div>...</div>",# ensure display_header_footer is truefooter_template: "<div>...</div>",# ensure display_header_footer is truemargin: {top: "2cm",left: "0.5cm",right: "0.5cm",bottom: "2cm"},}endapi_key
Make sure to replace "your_api_key_here" with your actual Browserless.io API key.
emulate_media
You can specify the media type by passing in the optional emulate_media keyword argument. Choose between screen (default) or print.
TailwindCSS supports the print modifier, so you can conditional add styles to only be displayed with the PDF is being generated.
style_tag You can use both a public URL or pass the CSS as a string to add CSS to your PDF. Note that browserless can't asses any url refering to your local environment. Therefore, in your local environment pass the CSS as a string.
defcss_assetifRails.env.production?ActionController::Base.helpers.asset_path("application.css")elseFile.read(Rails.root.join("app/assets/builds/application.css"))endendBrowserless.configuredo |config|
# ... config.style_tag=css_assetendHere's an example of how to use the Browserless::Client to generate a PDF from HTML content:
client=Browserless::Client.new(html: "<html></html>")pdf_data=client.to_pdfYou can customize the PDF generation by passing options. Passed in options will overwrite options set in the intializer.
client=Browserless::Client.new(html: "<html>...</html>",emulate_media: "print",options: {landscape: truedisplay_header_footer: true})pdf_data=client.to_pdfYou can pass the following options:
landscapedefault falseprint_backgrounddefault falsemargindefault noneformatdefault A4header_templatedefault emptyfooter_templatedefault X of X pagedisplay_header_footerdefault true
Note that the above options are nested in an options hash.
classPolicy# ...defto_pdfhtml=ApplicationController.render(partial: "policies/document",locals: {policy: policy})Browserless::Client.new(html: html,options: {display_header_footer: true}).to_pdfendendclassPoliciesController# ...defshow# ... respond_todo |format|
format.pdf{send_data@policy.to_pdf,type: "application/pdf",disposition: "attachment",filename: "privacy_policy.pdf"}endendIn your view::
link_to"Download",policy_path(@policy,format: :pdf)After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/thomasvanholder/browserless. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Browserless project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.