: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/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].