Documents and components

Everything about the PDF as a whole is declared on the class. Subclasses inherit a copy of the parent's configuration, so a base ApplicationPdf can hold the house style.

class ApplicationPdf < Stationery::Document
  page size: :a4, margin: [40, 44, 56, 44]
  font_family "Brand", regular: "fonts/Brand-Regular.ttf", bold: "fonts/Brand-Bold.ttf"
  font_fallbacks "Noto Sans Symbols"
  default_text font: "Brand", size: 9, color: "#1F2937"
  metadata author: "Acme Studio AB", creator: "stationery"
end

class InvoicePdf < ApplicationPdf
  metadata title: "Invoice"
  strict
end

to_pdf(target = nil, strict: <class setting>, debug: false) builds the element tree, paginates it, runs page templates, resolves links and bookmarks and returns the PDF as a binary String. With a target it also writes to that path or IO.

document = InvoicePdf.new(invoice)
document.to_pdf("invoice.pdf")
document.warnings.each { |warning| Rails.logger.warn(warning.message) }
document.page_count # => 2, the pages the last render laid out

With a block, to_pdf { |chunk| … } streams the file in pieces as it is written and answers the number of bytes: the first bytes leave sooner and no output buffer is built. Every page is laid out and painted before the first byte. A signed document cannot go to a block.

incremental: true (or incremental at class level) writes each page's content as soon as the page is painted and lets go of it, to a block before the next page is painted. It is for long documents with headers, footers, page templates or a table of contents, which are painted once every page is known and become content streams of their own; the file lists its page contents first and is a little larger. A render with conformance: or sign:, and a strict one that goes to a block, take the usual path, since they must be checked before a byte is written. To a block, an error on a late page leaves the start of a file. The figures are on the Performance page.

strict: false opts one render out of a class-level strict; debug: outlines layout rectangles (see Pages).

A Stationery::Component is a reusable piece of a document with Phlex's lifecycle — around_template, before_template, view_template, after_template — and every element. Content passed as a block is yielded from view_template:

class Callout < Stationery::Component
  def initialize(color:) = (super(); @color = color)
  def view_template(&) = box(background: @color, padding: 12, radius: 6, &)
end

class Report < Stationery::Document
  def view_template
    render Callout.new(color: "#F3F4F6") { text "Amount due" }
  end
end

A Document is itself a component, so documents can render other components, and components can render components.

Anything else raises ArgumentError. Blocks that take an argument receive the component, so { |c| c.text @title } keeps your own self inside the block.