Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/prawn_plus

A Rails renderer for Prawn PDFs.
https://github.com/bkuhlmann/prawn_plus

pdf prawn template-engine

Last synced: 6 days ago
JSON representation

A Rails renderer for Prawn PDFs.

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



= Prawn+



Prawn+ is a lightweight Rails Engine that wraps the link:https://github.com/prawnpdf/prawn[Prawn]

PDF generator in order to render PDFs within Rails views. This allows you to build view templates

which render PDFs using the Prawn syntax.



toc::[]



== Features



* Loads the https://github.com/prawnpdf/prawn[Prawn] gem by default (no Gemfile entry necessary).

* Registers PDF as a MIME type.

* Registers a template handler for rendering "`.prawn`" template view files.



== Requirements



. https://www.ruby-lang.org[Ruby]

. https://rubyonrails.org[Ruby on Rails]

. https://github.com/prawnpdf/prawn[Prawn]



== Setup



To install _with_ security, run:



[source,bash]

----

# 💡 Skip this line if you already have the public certificate installed.

gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)

gem install prawn_plus --trust-policy HighSecurity

----



To install _without_ security, run:



[source,bash]

----

gem install prawn_plus

----



You can also add the gem directly to your project:



[source,bash]

----

bundle add prawn_plus

----



Once the gem is installed, you only need to require it:



[source,ruby]

----

require "prawn_plus"

----



== Usage



=== Views



Within your views you can craft Prawn templates using Ruby code. For example, assuming there are

document resources, then the following structure might exist:



....

/views/documents/show.html.slim

/views/documents/show.pdf.prawn

....



The `show.html.slim` could have a link to the PDF download. Example:



....

= link_to "PDF Download", action: "show", id: @document.id, format: "pdf"

....



The `show.pdf.prawn` file would contain the Prawn syntax for crafting the PDF. A simple example

might look like this:



[source,ruby]

----

pdf.text "Hello, I'm a PDF!"

----



...which would render the following output:



image::https://alchemists.io/images/projects/prawn_plus/screenshots/basic.png[Basic Example]



You could also render a more complex PDF with tabular information, for example:



[source,ruby]

----

pdf.text "Metals"

pdf.move_down 10

pdf.font_size = 10



data = [

  ["Name", "Atomic Number", "Price"],

  ["Mercury", "80", number_to_currency(10)],

  ["Platinum", "78", number_to_currency(25)],

  ["Titanium", "22", number_to_currency(50)]

]



pdf.table data, header: true, column_widths: [100, 50, 50], row_colors: ["FFFFFF", "E5ECF9"] do

  columns(0).align = :left

  columns(1..2).align = :right

  row(0).text_color = "FFFFFF"

  row(0).background_color = "000000"

  row(0).columns(0..2).font_style = :bold

  row(0).columns(0..2).align = :center

end

----



...which would render the following output:



image::https://alchemists.io/images/projects/prawn_plus/screenshots/complex.png[Complex Example]



_NOTE: The `pdf` object must always be referenced when making using of the Prawn syntax - it is

initialized for you as a Prawn::Document instance._



=== Controllers



Within your controller, only the `respond_to` method is required. Example:



[source,ruby]

----

class DocumentsController < ApplicationController

  respond_to :pdf



  def show

  end

end

----



That’s it!



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/prawn_plus

cd prawn_plus

bin/setup

----



You can also use the IRB console for direct access to all objects:



[source,bash]

----

bin/console

----



== Tests



To test, run:



[source,bash]

----

bin/rake

----



== link:https://alchemists.io/policies/license[License]



== link:https://alchemists.io/policies/security[Security]



== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]



== link:https://alchemists.io/policies/contributions[Contributions]



== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]



== link:https://alchemists.io/projects/prawn_plus/versions[Versions]



== link:https://alchemists.io/community[Community]



== Credits



* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].