DocSpring vs Prawn

Where the coordinates come from

Prawn gives you a canvas. You call draw_text, bounding_box, table, and image with positions in PDF points measured from the bottom-left corner of the page. It has no concept of an existing form or a field. To fill a government form or a partner's PDF you generate a transparent overlay and stamp it onto the original with another library, and the positions come from measurement.

The extension gems that used to close those gaps are no longer looked after. prawn-templates, the official way to use an existing PDF as a background, has not had a release since 2019 and is documented as unsupported. prawn-blank and prawn-forms, which created AcroForm fields, stopped in 2013 and 2014 and predate every current Prawn release. What remains is Prawn for drawing plus HexaPDF or CombinePDF for stamping, held together by code you write.

DocSpring's template editor shows the PDF page and lets you drag fields onto it, import existing AcroForm fields, set types and validation, and preview with sample data. The field positions become part of a versioned template that the API fills. The drawing is still done by Prawn behind the scenes.

Feature comparison

Follow the feature links for details in DocSpring's documentation. Sources for each Prawn cell are listed at the end of the page.

Scroll the table sideways to see both products.

"Limited or your responsibility" marks things the library only partly covers or leaves to your own code and infrastructure. Plan requirements and product boundaries are noted in the cells.

Fill an application form with a name and email address

Suppose you have an application form as a PDF with spaces for a customer's name and email. Your Ruby application already has both values. Compare how each approach decides where they go on the page.

Fill the form with Prawn

Two libraries, hand-measured coordinates, and a stamping step. This is the workflow DocSpring replaces.

require 'prawn'
require 'hexapdf'

# Prawn draws a blank overlay. Every value needs x/y coordinates in PDF points,
# measured from the bottom-left corner of the page, found by trial and error.
Prawn::Document.generate('overlay.pdf', page_size: 'LETTER', margin: 0) do
  font_size 11
  draw_text 'Mira Patel', at: [118, 642]
  draw_text '[email protected]', at: [118, 618]
end

# Then stamp the overlay onto the original form with another library.
form = HexaPDF::Document.open('application.pdf')
overlay = HexaPDF::Document.open('overlay.pdf')
form.pages.first.canvas(type: :overlay).xobject(form.import(overlay.pages.first.to_form_xobject), at: [0, 0])
form.write('filled.pdf')

Fill the form with DocSpring

The fields were placed in the browser. The request only carries the data.

curl --fail-with-body \
  "https://sync.api.docspring.com/api/v1/templates/${DOCSPRING_TEMPLATE_ID}/submissions" \
  --user "${DOCSPRING_TEST_TOKEN_ID}:${DOCSPRING_TEST_TOKEN_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{
    "test": true,
    "data": {
      "customer_name": "Mira Patel",
      "customer_email": "[email protected]"
    }
  }'

Set the environment variables to your template ID and test API credentials. Accounts in our EU region send requests to sync.api-eu.docspring.com instead. The response includes a download URL for a watermarked PDF. See the request and response guide.

Change the form's layout by a few millimeters and see how long it takes to update each approach. Then hand the task to someone who does not write Ruby.

A free gem, and the hours to place every field

A ten-field form filled with Prawn is an afternoon of coordinate tuning the first time and an hour every time the form changes. In DocSpring it is a few minutes of dragging fields, by anyone on the team.

Moving from Prawn to DocSpring

Upload each original PDF to DocSpring and place the fields visually. If a PDF has AcroForm fields, import them and the names are done. Your existing coordinate constants can guide the first placement, but you will not need to keep them.

Replace the Prawn and stamping code with an API call using the DocSpring Ruby client. Map your data hash to the field names. Keep Prawn for any documents you genuinely draw from scratch, or move those to HTML/CSS templates in DocSpring.

Test each form with long values, checkboxes, and multi-page output. Then delete the overlay code.

Discuss your documents with us.

Questions about Prawn and DocSpring

Does DocSpring use Prawn?

Yes. DocSpring uses Prawn to draw field values onto uploaded PDFs. The difference is that the coordinates come from a visual editor and a versioned template, not from constants in your code.

Can Prawn fill an existing PDF form?

Not by itself. Prawn creates new pages. To fill an existing form you draw an overlay at measured coordinates and stamp it onto the original with another library such as HexaPDF.

Is Prawn still maintained?

Prawn receives occasional releases, the latest being 2.5.0 in March 2024, and works fine for drawing new documents. The extension gems for existing PDFs and form fields, prawn-templates, prawn-blank, and prawn-forms, have had no releases since 2019, 2013, and 2014 and should not be used in new projects.

I only use Ruby. Is DocSpring a good fit?

Yes. DocSpring has an official Ruby client library, and the JSON API works from any language. The editor runs in the browser, so non-developers can adjust templates too.