docmake v0.0.2

docmake

docmake is a document templating language library for javascript.

Installation

Installation uses the npm package manager. Just type the following command after installing npm.

npm install docmake

usage

var Docmake = require('docmake');
var fs = require('fs');

var doc = new Docmake();
doc.compile('{{hello}}', { hello: 'hello world!' }, function(err) {
  if (err) {
    return console.log(err);
  }
  doc.getPdf().pipe(fs.createWriteStream('document.pdf')); 
});

doc.compile takes three arguments:

• template: a string containing the template
• scope: an object containing data used in template
• cb: a callback

doc.getPdf takes one optional argument:

• options: an object describing document shape return a pdf document stream

doc.getPcl takes one optional argument:

• options: an object describing document shape return a pcl document stream

options:

• size: document format, default 'A4'
• margins: pages margins containing left, top, right and bottom margin, default {left: 10, top: 10, right: 10, bottom: 10}

template language

docmake simple expressions starts with {{ , some content, and ends with }}. when the document is rendered with the template, the expression is evaluated and the value is printed in the document. in the previous exemple, {{hello}} expression is replaced by the corresponding value in the scope.

nested object scope

Sometimes, scope contains other objects or arrays. For example:

{
  person: {
    firsname: "Alexandre",
    lastname: "Tiertant"
  }
}

In such a case, you can use a dot-notation to gain access to the nested properties

{{person.firstname}}
{{person.lastname}}

text

Text tag starts with {{text, a text, some attributes , and ends with }}.

{{text person.firstname fontSize=24}}
{{text "some text here" bold=true}}

available attributes for text:

• font: (string) name of the font
• fontSize: (number) size of the font in pt
• lineHeight: (number) the line height (default: 1)
• bold: (boolean) whether to use bold text (default: false)
• italics: (boolean) whether to use italic text (default: false)
• characterSpacing: (number) size of the letter spacing in pt
• color: (string) the color of the text (color name e.g., ‘blue’ or hexadecimal color e.g., ‘#ff5500’)
• decoration: (string) the text decoration to apply (‘none’ or ‘underline’ or ‘strike’)
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the text
• valignment: (string) (‘top’ or ‘center’ or ‘bottom’) the vertical alignment of elements if height is defined.
• width: (number or string containing a number and ends with %) width of the text
• height: (number or string containing a number and ends with %) height of the text
• fillColor: (string) the background color of the text
• margin: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) space arround the text
• border: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) size of the border

comment

comments can be used to explain template code, and to make it more readable. Any text between // and the end of the line will be ignored by template (will not be executed).

// some comment here

image

Image tag starts with {{image, an image jpg or png (filepath or buffer or base64 string), and ends with }}.

{{image "/home/user/image.png"}}

available attributes for image:

• width: (number or string containing a number and ends with %) width of the image
• height: (number or string containing a number and ends with %) height of the image
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the image

svg

Svg tag starts with {{svg, an svg image (filepath or string), and ends with }}.

{{svg "/home/user/image.svg"}}

available attributes for svg:

• width: (number or string containing a number and ends with %) width of the svg
• height: (number or string containing a number and ends with %) height of the svg
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the svg

barcode

Barcode tag starts with {{barcode, a string value, and ends with }}.

{{barcode "this is a barcode"}}

available attributes for qr:

• width: (number or string containing a number and ends with %) width of the barcode
• height: (number or string containing a number and ends with %) height of the barcode
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the barcode

qr

Qr tag starts with {{qr, a string value, and ends with }}.

{{qr "this is a qrcode"}}

available attributes for qr:

• width: (number or string containing a number and ends with %) width of the qrcode
• height: (number or string containing a number and ends with %) height of the qrcode
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the qrcode

columns

by default, elements are placed one below other. using columns, elements are placed horizontally. the tag {{#columns}} require a closing tag {{/columns}}.

{{#columns widths=["auto", 25, "*"]}}
  {{text "column one"}}
  {{text "column two"}}
  {{text "column three"}}
{{/columns}}

available attributes for columns:

• columnGap: (number) specify gap (space) between columns
• width: (number or string containing a number and ends with %) total width of the columns
• widths: (array) width of each column that could be:
  • a number: fixed width
  • a string containing a number and ends with %: a percent of total width
  • "auto": auto-sized columns have their widths based on their content
  • "*": star-sized columns fill the remaining space. if there's more than one star-column, available width is divided equally
• font: (string) name of the font
• fontSize: (number) size of the font in pt
• lineHeight: (number) the line height (default: 1)
• bold: (boolean) whether to use bold text (default: false)
• italics: (boolean) whether to use italic text (default: false)
• characterSpacing: (number) size of the letter spacing in pt
• color: (string) the color of the text (color name e.g., ‘blue’ or hexadecimal color e.g., ‘#ff5500’)
• decoration: (string) the text decoration to apply (‘none’ or ‘underline’ or ‘strike’)
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the columns
• valignment: (string) (‘top’ or ‘center’ or ‘bottom’) the vertical alignment of elements in columns.
• fillColor: (string) the background color of the columns
• margin: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) space arround columns element
• border: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) size of the border

stack

in columns, elements are placed horizontally, using stack, elements are placed vertically. the tag {{#stack}} require a closing tag {{/stack}}.

{{#stack}}
  {{text "top"}}
  {{text "middle"}}
  {{text "bottom"}}
{{/stack}}

available attributes for stack:

• width: (number or string containing a number and ends with %) total width of the stack

table

tables allow you to arrange elements into rows and columns of cells. table element starts with tag {{#table}} and ends with {{/table}}, it must contain one or more row element. row element starts with tag {{#row}} and ends with {{/row}}, it must contain one or more header or column element. header element starts with tag {{#header}} and ends with {{/header}}. column element starts with tag {{#column}} and ends with {{/column}}.

{{#table width="75%" repeatHeader=true}}
  {{#row}}
    {{#header}}"firstname"{{/header}}
    {{#header}}"lastname"{{/header}}
  {{/row}}
  {{#row}}
    {{#column}}"Alexandre"{{/column}}
    {{#column}}"Tiertant"{{/column}}
  {{/row}}
{{/table}}

available attributes for table:

• repeatHeader: (boolean) repeat headers on page break when true
• width: (number or string containing a number and ends with %) total width of the table
• widths: (array) width of each column that could be:
  • a number: fixed width
  • a string containing a number and ends with %: a percent of total width
  • "auto": auto-sized columns have their widths based on their content
  • "*": star-sized columns fill the remaining space. if there's more than one star-column, available width is divided equally

available attributes for table, row, header and columns:

• colspan: (number) specifies the number of columns the cell should span
• rowspan: (number) specifies the number of rows the cell should span
• font: (string) name of the font
• fontSize: (number) size of the font in pt
• lineHeight: (number) the line height (default: 1)
• bold: (boolean) whether to use bold text (default: false)
• italics: (boolean) whether to use italic text (default: false)
• characterSpacing: (number) size of the letter spacing in pt
• color: (string) the color of the text (color name e.g., ‘blue’ or hexadecimal color e.g., ‘#ff5500’)
• decoration: (string) the text decoration to apply (‘none’ or ‘underline’ or ‘strike’)
• alignment: (string) (‘left’ or ‘center’ or ‘right’) the alignment of the elements in it.
• valignment: (string) (‘top’ or ‘center’ or ‘bottom’) the vertical alignment of elements in it.
• fillColor: (string) the background color of the element
• margin: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) space arround element
• border: (left, top, right, bottom, horizontal, vertical, number equalLeftTopRightBottom) size of the border

hspace and vspace

hspace tag add an horizontal space wheras vspace add a vertical one. they only take one integer size parameter.

{{hspace 100}}
{{vspace 50}}

style

Style tag add some basic css style to document Style tag starts with {{style, a simple css string, and ends with }}. docmake css implement tag, class(.), id(#) selector

{{style "text { color=#FF0000; }"}}
{{text "all text are displayed in red"}}

class

Class tag define a class that can be applyed to any element. Class tag starts with {{class, a class name string, some attributes, and ends with }}.

{{class "red" color="#FF0000"}}
{{text "text displayed in red" class=["red"]}}

font

Font tag add .ttf files as font Font tag starts with {{font, a font name string, some attributes, and ends with }}.

{{font myFont normal="/home/user/myfont.ttf"}}
{{text "text displayed in red" class=["red"]}}

available attributes for font:

• normal: (string) .ttf filepath for normal text
• bold: (string) .ttf filepath for bold text
• italics: (string) .ttf filepath for italics text
• bolditalics: (string) .ttf filepath for bold and italics text

page header and page footer

contents of page header and page footer are repeat on each page on top for page header and at the bottom for page footer. text {{currentPage}} in page footer is replaced by the number of the current page. text {{pageCount}} in page footer is replaced by the count of pages.

{{#pageHeader}}
  {{image "/home/user/header.png" width="100%"}}
{{/pageHeader}}
{{#pageFooter}}
  {{image "/home/user/footer.png" width="100%"}}
  {{text "{{currentPage}} / {{pageCount}}" alignment="right"}}
{{/pageFooter}}

page break

{{pageBreak}} tag move to the next page.

reset page count

{{resetPageCount}} tag break the page and reset the number of page and page count.

if

If tag include its contents in document only if a condition is satisfied. If tag starts with {{#if, a conditional expression, and ends with }}. If tag must be close with tag {{/if}}

{{#if person.firstname == "Alexandre"}}
  {{person.firstname}}
{{/if}}

each

Each tag include its contents in document once for each element in an array, in order and replace scope by it.

{
  my_array: [
    {
      data: "first"
    },
    {
      data: "second"
    }
  ]
}

{{#each my_array}}
  {{data}}
{{/each}}

inside a Each tag, some keywords could be used:

• $root to access root scope.
• $item to access current iteration item.
• $key to access the current key in object iteration (same as $index in array).
• $index to access the index of the iterated item.
• $first only true on first iteration.
• $last only true on last iteration.

{{#each ["1","2","3"]}}
  {{#if $first}}
    {{text "first"}}
  {{/if}}
  {{text concat("item: ", $item, " index: ", $index)}}
  {{#if $last==true}}
    {{text "last"}}
  {{/if}}
{{/each}}