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 1.x and 2.x series.

Using prawn-svg

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

Supply :at if you want to render it at a specific location on the page. Use :position with a value of :left, :center, :right or a number to render it at the current cursor position, or use :vposition with a value of :top, :center, :bottom or a number to specify its Y position too.

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 supports most but not all of the full SVG 1.1 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 text-anchor, font-size, font-family, font-weight, font-style, letter-spacing, dx, dy

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

• <use>

• <style> plus id, class and style attributes (see CSS section below)

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

• <clipPath>

• <linearGradient> but only with Prawn 2.0.3+. gradientTransform, spreadMethod and stop-opacity are unimplemented.

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

• 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

prawn-svg uses the css_parser gem to parse CSS <style> blocks. It only handles simple tag, class or id selectors; attribute and other advanced selectors are not supported.

Not supported

prawn-svg does not support external url() references, measurements in en or em, sub-viewports, radial 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 [email protected]. MIT licence.