https://github.com/bkuhlmann/prawn_plus

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

pdf prawn template-engine

Last synced: about 2 months ago
JSON representation

A Rails renderer for Prawn PDFs.

• Host: GitHub
• URL: https://github.com/bkuhlmann/prawn_plus
• Owner: bkuhlmann
• License: other
• Created: 2012-05-26T23:25:16.000Z (over 12 years ago)
• Default Branch: main
• Last Pushed: 2024-07-23T00:05:51.000Z (about 2 months ago)
• Last Synced: 2024-07-23T03:20:21.196Z (about 2 months ago)
• Topics: pdf, prawn, template-engine
• Language: Ruby
• Homepage: https://alchemists.io/projects/prawn_plus
• Size: 738 KB
• Stars: 31
• Watchers: 4
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • Funding: .github/FUNDING.yml
  • License: LICENSE.adoc
  • Citation: CITATION.cff

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