prawn-svg

An SVG renderer for the Prawn PDF library.

This will take an SVG file as input and render it into your PDF. Find out more about the Prawn PDF library at:

http://wiki.github.com/sandal/prawn/

prawn-svg is compatible with all versions of Prawn from 0.8.4 onwards, including the version 1.0 series.

Using prawn-svg

Prawn::Document.generate("svg.pdf") do
  svg svg_data, :at => [x, y], :width => w
end

:at must be specified.

Either :width, :height, or neither may be specified; if neither is present, the dimensions specified in the SVG will be used, or if the dimensions aren't specified, it'll fit to the space available on the page.

:cache_images, if set to true, will cache images per document based on their URL.

:fallback_font_name takes a font name which will override the default fallback font of Times-Roman. If this value is set to nil, prawn-svg will ignore a request for an unknown font and log a warning.

Supported features

prawn-svg does not support the full SVG specification. It currently supports:

  • <line>, <polyline>, <polygon>, <circle> and <ellipse>

  • <rect>. Rounded rects are supported, but only one radius is applied to all corners.

  • <path> supports all commands defined in SVG 1.1, although the implementation of elliptical arc is a bit rough at the moment.

  • <text> and <tspan> with attributes size, text-anchor, font-family, font-weight, dx, dy

  • <svg>, <g> and <symbol>

  • <use>

  • <style>, if css_parser gem is installed on the system (see CSS section below)

  • <image> with http:, https: and data:image/*;base64 schemes

  • <clipPath>

  • attributes/styles: fill, stroke, stroke-width, opacity, fill-opacity, stroke-opacity, transform, clip-path

  • the viewBox attribute on the <svg> tag

  • the preserveAspectRatio attribute on the <svg> and <image> tags

  • transform methods: translate, rotate, scale, matrix

  • colors: HTML standard names, #xxx, #xxxxxx, rgb(1, 2, 3), rgb(1%, 2%, 3%)

  • measurements specified in pt, cm, dm, ft, in, m, mm, yd, pc, %

  • fonts: generic CSS fonts, built in PDF fonts, and any TTF fonts in your fonts path

CSS

If the css_parser gem is installed, it will handle CSS style definitions, but only simple tag, class or id definitions. It's very basic so do not expect too much of it.

Not supported

prawn-svg does not support external references, measurements in en or em, sub-viewports, gradients/patterns or markers.

Configuration

Fonts

By default, prawn-svg has a fonts path of ["/Library/Fonts", "/System/Library/Fonts", "#{ENV["HOME"]}/Library/Fonts", "/usr/share/fonts/truetype"] to catch Mac OS X and Debian Linux users. You can add to the font path:

  Prawn::Svg::Interface.font_path << "/my/font/directory"

Copyright Roger Nesbitt roger@seriousorange.com. MIT licence.