Yipt: Yipt is PDF Template

Yipt is a YAML based template engine generates PDF document.

Yipt uses PDFKit for PDF generation and JSONata for template variables.

Install

npm i yipt

Usage

CLI

yipt [options] <template> [output]

options

-p, --prams <file>

A json or yaml file includes template variables.

args

template

Path to template file.

output

Path to output file. STDOUT will be used when "-" is supplied or ommitted.

Example

yipt -p params.yml my-template.yml out.pdf

in JavaScript or TypeScript

import yipt from "yipt";
import * as PDFKit from "pdfkit";

const doc = new PDFKit();
const templateVariables = { foo: "template variables" };

yipt.render(doc, "/path/to/template.yml", templateVariables);
// yipt.render returns Promise<void>

It's also possible to create new Yipt instance.

import { Yipt } from "yipt";

const yipt = new Yipt();

Variable evaluation

Yipt supports template variables. Many of parameters in template are evaluated with template variables using JSONata.

Values in template other than text value such as content property of TextElement, are evaluated as a JSONata expression. Of course, you can also specify raw values instead of JSONata expressions for properties. Types of properties documented in this doc, are types of evaluated value.

On the other hand, in text, JSONata expression is wrapped with "{" and "}". For escape "\" is available.

Example

template:

yipt:
  version: "1.0"
  content:
    - type: text
      top: myVariableForTop
      left: myObject.left
      content: This text placed on (myObject.left, myVariableForTop).

variables:

{
  myVariableForTop: 10,
  myObject: { left: 20 },
}   

Then, "This text placed on (myObject.left, myVariableForTop)." is rendered at (20, 10).

template:

yipt:
  version: "1.0"
  content:
    - |
    Hello {foo.bar}! You can also use JSONata expression a + 1 = {a + 1}.
    \{but this never evaluted} because \{ is escaped.
    Then "\\\{" and "\\\\" is rendered as "\{" and "\\".

variables:

{
  foo: { bar: "world" },
  a: 2
}

output:

    Hello world! You can also use JSONata expression a + 1 = 3.
    {but this never evaluted} because { is escaped.
    Then "\{" and "\\" is rendered as "{" and "\".

Template

Absatract

Yipt template is a YAML file whose root object has yipt property, which is a Yipt object. And Yipt object has content property, which is an array of Element object or string. If element of content is a string, it is treated as TextElement.

Yipt renders Elements in order of array.

Element object is one of:

Element name	Description
TextElement	Renders text.
ImageElement	Renders JPEG/PNG image.
VectorElement	Renders vector graphics.
FontElement	Setup font for text.
PageBreakElement	Insert page break.
BlockElement	Groups elements and control offset.
CaseElement	Logical flow control in similar way to SQL's CASE syntax.
ForeachElement	Loop flow control.

Spec

Yipt Object

Property	Type	Description
version	string	fixed "1.0". Version of template format.
content	Content[]	List of content.

Content

Content is one of Element or string.

TextElement

Property	Type	Description
content	string	The text to print with variable reference.
top	number	The position in y axis.
left	number	The position in x axis.
options	TextOptions	Options for text rendering.

TextOptions

See Text in PDFKit for more detail.

ImageElement

Property	Type	Description
src	string	Path to image(JPEG/PNG) file.
top	number	The position in y axis.
left	number	The position in x axis.
options	ImageOptions	Options for text rendering.

ImageOptions

See Images in PDFKit for more detail.

VectorElement

Property	Type	Description
paths	VectorPath[]	Ordered array of vector paths.
top	number	The position in y axis.
left	number	The position in x axis.
render	"stroke" | "fill" | "fillAndStroke"	How render the path.
lineWidth	number	Line width. lineWidth 0 means hair line.
cap	"butt" | "round" | "square"	Line cap.
join	"miter" | "round" | "bevel"	Line join.
dash	DashParameter	Line dash style.
color	string	Line color. It allows a hex color string, or use any of the named CSS colors.
fillColor	string	Fill color. It allows a hex color string, or use any of the named CSS colors.
windingRule	"even-odd" | "non-zero"	Winding rules define how a path is filled.
opacity	number	Opacity of vector graphic. It value could be 0 to 1.

VectorPath

Type property of VectorPath could be one of:

• line
• verticalLine
• horizontalLine
• quadraticCurve
• bezierCurve
• move
• rect
• roundedRect
• ellipse
• circle
• polygon

The first 5 types(lines and curves) use end point of previous path as start point.(this means they connect previous path). Use move for change start point of them if you want. (0, 0) is used as start position if one of them placed in the first of paths array. Please note that end points of the last 5 types(shapes) is undefined.

VectorPath object has additional properties for each types.

doc.y is set to maximum y of graphics after rendering vector.

line

Property	Type	Description
to	[number, number]	Line end point in [x, y].

verticalLine & horizontalLine

Property	Type	Description
length	number	Line length.

quadraticCurve

Property	Type	Description
to	[number, number]	Curve end point in [x, y].
anchor	[number, number]	Anchor point in [x, y].

bezierCurve

Property	Type	Description
to	[number, number]	Curve end point in [x, y].
anchors	[number, number, number, number]	Anchor points in [x1, y1, x2, y2].

move

Property	Type	Description
to	[number, number]	Move to [x, y].

rect

Property	Type	Description
pos	[number, number]	Position of rectangle in [left, top].

roundedRect

Property	Type	Description
pos	[number, number]	Position of rectangle in [left, top].
cornerRadius	number	Radius of rounded corner.

ellipse

Property	Type	Description
center	[number, number]	Center coordinate in [x, y].
radiusX	number	Radius of x axis.
radiusY	number	Radius of y axis.

circle

Property	Type	Description
center	[number, number]	Center coordinate in [x, y].

polygon

Property	Type	Description
vertices	number[]	Coordinates of vertices in [x1, y1, x2, y2, ...]

FontElement

You can set or register founts using FontElement. Once fount is configured, it affects all text rendering (even where out of BlockElement) until another FontElement configures font.

Property	Type	Description
size	number	Set font size.
name	string	Font name to be used. Standard font name or registered font name.
src	string	Path to font file for register or temporally use.
family	string	Font family for TrueType Collection or Datafork TrueType font file. This property is only used with src property.
registerAs	string	Register font as this value name. This property requires src property.
setOnRegister	boolean	Whether setting font on register or not. This property is only used with registerAs.
Default is false unless size property is set together.

PageBreakElement

Property	Type	Description
options	PageOptions	Options for new page after page break.

NOTE: PageOptions is never evaluated with variables.

PageOptions

Property	Type	Description
size	[number, number] | string	Page size in [width, height] or string such as "A4".
layout	"portrait" | "landscape"	Page layout. Default is "portrait".
margins	Margins	Margins of the new page.
margin	number	Syntax sugar for margins if all margins is the same.

Margins

Property	Type	Description
top	number	The top margin.
left	number	The left margin.
bottom	number	The bottom margin.
right	number	The right margin.

BlockElement

Property	Type	Description
top	number	Top position of the block.
left	number	Left position of the block.
content	Content[]	List of content.

CaseElement

Property	Type	Description
conditions	CaseCondition[]	Ordered list of conditions.
else	Content	This content will be rendered when any conditions isn't satisfied.

CaseCondition

Property	Type	Description
when	boolean	The condition to be satisfied. Usually this is JSONata condition expression.
content	Content	This content will be rendered if condition is satisfied.

ForeachElement

Property	Type	Description
items	any[]	Items to be iterate.
content	Content	This will be rendered foreach loop.

In the loop, special variables are available.

Loop variables

Accessor	Type	Description
$foreach	Foreach	Current loop.
$foreach.total	number	Total number of loop items.
$foreach.index	number	Current item index.
$foreach.count	number	The loop count.
$foreach.item	any	Current item.
$loops	Foreach[]	$loops[0] is the same as $foreach. $loops[1] is one outer loop.

Example

You can see example in tests directory.