PDFML - PDF Markup Language
Write dynamic PDF files using a markdown language similar to HTML, Using the EJS rendering engine.
This project is built using pdfmake and ejs
Additionally, this will improve and auto fix your document defintion, so you don't have to worry about the PDF file being broken.
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Usage](#usage)
- [EJS file](#ejs-file)
- [Convert to DocDefinition Object](#convert-to-docdefinition-object)
- [Get A Buffer](#get-a-buffer)
- [Serve with express.js](#serve-with-express.js)
- [Use Templates](#use-templates)
- [Elements](#elements)
- [PDFML](#pdfml)
- [p](#p)
- [div](#div)
- [columns](#columns)
- [Table](#table)
- [Br](#br)
- [Image](#image)
- [hr](#hr)
- [Features](#features)
- [Conditional Elements](#conditional-elements)
- [Fonts](#Fonts)
## Installation
```sh
npm i pdfml --save
```
## Usage
```js
const pdfml = require('pdfml');
pdfml.render({
path : PATH_TO_FILE_NAME
data : RENDER_DATA
});
```
### EJS file
Create an ejs file, for example:
```
<%= text %>
```
### Convert to DocDefinition Object
```js
const pdfml = require('pdfml');
let dd = pdfml.getDD(STRING_OR_PATH_TO_FILE, RENDER_DATA, OPTIONS);
```
### Get A Buffer
```js
const pdfml = require('pdfml');
let buffer = await pdfml.generatePDF(docDefinition, OPTIONS);
```
### Serve with express.js
```js
const pdfml = require('pdfml');
///in your express router
app.get("/:filename", async (req, res, next) => {
try {
//you can query some data here
let doc = await pdfml.render({
path: Path.join(__dirname, req.params.filename), //path to your ejs file
data: {}, // data for context in your ejs file,
fonts: {}, //if you want to supply fonts
});
//set the content type to pdf
res.setHeader("Content-type", "application/pdf");
//set the attachment header
res.attachment("PDF_FILE.pdf"); // remove this if you want to open the pdf in the browser
res.send(doc);
} catch (err) {
next(err);
}
});
```
### Use Templates
Synce this is powered by ejs, you can use the include function and setup multiple templates.
This is very useful when you have generic parts of your document that you want to reuse.
Consider the following file structure:
- templates/
- header.pdfml
- footer.pdfml
- main.pdfml
You can then use the include function to include the header and footer in your main file:
```xml
<%- include('./templates/header.pdfml') %>
Main Content
<%- include('./templates/footer.pdfml') %>
```
## Elements
### PDFML
PDFML is the root element for the PDF document, and there is where you define all document-level Settings.
Using the attributes of the `````` element ([see example](#pdfml-attributes-example)) you can define document level settings, such as page size, orientation, margins, etc.
#### PDFML Attributes Example
```xml
```
### p
(or text)
A ```p``` element is for displaying a paragraph of text.
```xml
This is plain text
```
### div
(also known as ```stack```)
A ```div``` will keep the inner elements together, the inner elemets will be diplayed in block mode.
```xml
This is one block of text
This is another block of text
```
### columns
```columns``` will keep the inner elements together, the inner elemets will be diplayed inline mode.
```xml
This is one block of text
This is another block of text
```
### table
For tables use the the following elements (body, row, cell):
Note: The table will be rendered in a single page, if you want to break the table in multiple pages use the ```dont-break-rows="true"``` attribute.
Note: PDFML is resilent to a mismatched number of columns in each row, it will fill the missing columns with empty cells. It will also fill in the widths and/or the heights attribute with the default width (auto) for each missing column.
```xml
```xml
<% rows.forEach((row, rIdx) => { %>
<% row.forEach((clm, cIdx) => { %>
|
<%= clm %>
|
<% }) %>
<% }) %>
```
## Br
Just to break a line
```xml
```
## Image
```xml
```
## hr
```xml
```
## Features
### Conditional Elements
Use the attribute ```print-if``` and pass a boolean value to include this elements (and it's children or not).
Note - that the inner content is still rendered with ejs, so the variables need to be defined.
## Fonts
Supported fonts are:
- Avenir
- Geo
- Roboto