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