yipt v1.0.0-beta.4

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

args

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:

Spec

Yipt Object

Content

Content is one of Element or string.

TextElement

TextOptions

See Text in PDFKit for more detail.

ImageElement

ImageOptions

See Images in PDFKit for more detail.

VectorElement

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

verticalLine & horizontalLine

quadraticCurve

bezierCurve

move

rect

roundedRect

ellipse

circle

polygon

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.

Default is false unless size property is set together.

PageBreakElement

NOTE: PageOptions is never evaluated with variables.

PageOptions

Margins

BlockElement

CaseElement

CaseCondition

ForeachElement

In the loop, special variables are available.

Loop variables

Example

You can see example in tests directory.