PrawnEx

CIHex.pmHex.pmHex.pmElixir

Version 0.2.0 · Elixir ~> 1.16

Prawn-style declarative PDF generation for Elixir. Pure Elixir, no Chrome or HTML: build a document spec and emit PDF 1.4.

Features

Getting started

Add the dependency and build your first PDF:

# mix.exs
def deps do
  [{:prawn_ex, "~> 0.2.0"}]
end
PrawnEx.build("output.pdf", fn doc ->
  doc
  |> PrawnEx.add_page()
  |> PrawnEx.set_font("Helvetica", 12)
  |> PrawnEx.text_at({72, 700}, "Hello, PDF!")
end)

See Demo for a full tour, or try the invoice or report with chart examples.

Usage

PrawnEx.build("output.pdf", fn doc ->
  doc
  |> PrawnEx.set_font("Helvetica", 12)
  |> PrawnEx.text_at({100, 700}, "Hello, PDF!")
  |> PrawnEx.rectangle(100, 600, 200, 50)
  |> PrawnEx.stroke()
end)

Or build a document and get binary:

binary =
  PrawnEx.Document.new()
  |> PrawnEx.add_page()
  |> PrawnEx.set_font("Helvetica", 12)
  |> PrawnEx.text_at({72, 72}, "Hello")
  |> PrawnEx.to_binary()

Coordinates use PDF points (72 pt = 1 inch); origin is bottom-left.

Tables

Draw tables with an optional header row (Phase 2):

rows = [["Product", "Qty", "Price"], ["Widget", "2", "$10"], ["Gadget", "1", "$25"]]
doc
|> PrawnEx.table(rows, at: {50, 650}, column_widths: [200, 80, 80], header: true)

Options: :at, :column_widths (list or :auto), :row_height, :cell_padding, :header, :border, :align (:left / :center / :right or list per column), :font_size, :header_font_size.

Headers and footers

Use build(path, opts, fun) with :header and/or :footer callbacks (receiving doc and page number). Ideal for "Page N" and repeating titles:

PrawnEx.build("out.pdf", [
  footer: fn doc, page_num ->
    doc
    |> PrawnEx.set_font("Helvetica", 9)
    |> PrawnEx.text_at({50, 30}, "Page \#{page_num}")
  end
], fn doc ->
  # your content; footer is injected on every page
  doc |> PrawnEx.add_page() |> ...
end)

Charts

Bar and line charts (Phase 3), built from drawing primitives:

# Bar chart: list of {label, value}
PrawnEx.bar_chart(doc, [{"Jan", 40}, {"Feb", 55}, {"Mar", 70}],
  at: {50, 500}, width: 400, height: 200, bar_color: 0.4)

# Line chart: list of y-values (x = index) or [{x, y}, ...]
PrawnEx.line_chart(doc, [10, 25, 15, 40, 35], at: {50, 400}, width: 400, height: 150)

Options: :at, :width, :height, :bar_color / :stroke_color, :axis, :labels, :padding.

Flow layout (PrawnEx.Layout)

For documents that are mostly stacked blocks (title, paragraphs, table), a positional API forces you to repeat page_h - N math. PrawnEx.Layout tracks a baseline cursor inside a margin box and emits the same PrawnEx ops (text_at, text_box, table).

There is no automatic pagination or flex/grid; overflow is still yours to handle. See mix run scripts/invoice.exs for a full example.

Images

Embed JPEG or PNG via PrawnEx.image/3 (file path or raw bytes). Use :at (required), and optionally :width / :height in pt; default size is the image’s pixel dimensions treated as pt.

Format Notes
JPEG Stream is embedded as-is with /DCTDecode.
PNG 8-bit truecolor RGB or RGBA only, no interlacing. Decoded in pure Elixir; pixels are written as /DeviceRGB with /FlateDecode. RGBA is composited on white (simple transparency handling). Indexed-palette, grayscale-only, or interlaced PNGs are not supported and return {:error, ...}.

Image / asset path: Set config :prawn_ex, image_dir: "priv/images" (or any directory) in your application config. Relative paths passed to PrawnEx.image/3 are resolved from that directory. Absolute paths and raw JPEG or PNG binaries are used as-is.

# In your config/config.exs:
config :prawn_ex, image_dir: "priv/images"

# In your code — paths are under image_dir:
doc
|> PrawnEx.image("photo.jpg", at: {50, 400})
|> PrawnEx.image("logo.png", at: {400, 700}, width: 80, height: 40)

Other image types produce {:error, :unsupported_image_format}.

Colors

Gray: PrawnEx.set_stroking_gray(doc, 0.8), PrawnEx.set_non_stroking_gray(doc, 0.2) (0 = black, 1 = white).
RGB: PrawnEx.set_non_stroking_rgb(doc, r, g, b), PrawnEx.set_stroking_rgb(doc, r, g, b) (0–1).

Demo

Generate the demo PDF:

mix run scripts/gen_demo.exs

Output: output/prawn_ex_demo.pdf (4 pages: hero, table, charts, images). Page 4 shows JPEG (demo.jpg or a tiny embedded fallback) and PNG (assets/demo.png is included; falls back to a test fixture if demo.png is missing). Set config :prawn_ex, image_dir: "path/to/images" in config/config.exs if you keep assets elsewhere.

Examples

Installation

If available in Hex, the package can be installed by adding prawn_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:prawn_ex, "~> 0.2.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/prawn_ex.