Pdf service client side
This is the client side of PDF service description. The main aim of this part is to build html file with inline css, font and images. To use it you should start the server first.
Index
Overview
This is the client library that provides easy pdf and image generation. Here some features that can help you to develop awesome things:
-
🚴 Handlebars under the hood. You create your images and pdfs with dynamical content. -
📦 Webpack will manage all your assets. You just need to save assets near to your html template. -
❓ Maybe is it your feature? You can request new feature in issues or add new pr
Init
You should install @paralect/pdf-service-client:
npm i @paralect/pdf-service-client
Quick example
In your js file write these lines (be sure that you started server):
const PdfService = require('@paralect/pdf-service-client'); // require client pdf service library
const fs = require('fs'); // fs to write file
// pdf service init
const pdfService = new PdfService({
serverUrl: 'http://localhost:3000',
mode: 'development',
});
// generate pdf by html string
pdfService.generatePdfByContent('<body><h1>Hello, {{name}}!</h1></body>', {
pdfOptions: {
format: 'Letter',
},
templateSystem: {
params: {
name: 'Your name',
},
},
}).then((pdfStream) => {
const writeStream = fs.createWriteStream('./hello.pdf');
pdfStream.pipe(writeStream);
writeStream.on('finish', () => {
console.log('Hello pdf was created!');
});
});
Execution of this code should generate pdf file with 'Hello, Your name' string.
A bit of constructor explanation:
const pdfService = new PdfService({
serverUrl: 'http://localhost:3000', // optional
mode: 'development', // optional
});- serverUrl - you can provide url to server (look options sections here). http://localhost:3000 will be used as default.
- mode - mode can be production or development. In production mode you have to build assets before you invoke generatePdf method.
API
When you initialise pdf service it will provide you several methods.
generatePdf(pdfPath, [options])
Let's describe these options:
- pagePath - it is the path to html file which will be transformed to pdf.
- options - it is optional param. You can see more in Pdf options section.
This method returns stream with your pdf file.
Note: You page that was specified by pagePath should be placed with all assets in one directory. This directory should be isolated from other codebase. You have this restriction because build of all assets looks for all files that was placed in the same directory with your html source. Look to Example for more details.
generatePdfByContent(html, [options])
Let's describe these options:
- html - it is the html text which will be transformed to pdf.
- options - it is optional param. You can see more in Pdf options section.
This method returns stream with your pdf file.
Pdf options
Here is the example of image options:
{
pdfOptions: { // optional
format: 'Letter',
},
headers: { // optional
Authorization: 'Bearer ...'
},
templateSystem: { // optional
params: {
tasks: [{}],
},
helpers: {
hours: Handlebars => (hours) => {
const htmlData = parseFloat(Handlebars.escapeExpression(hours)).toFixed(2);
return new Handlebars.SafeString(htmlData);
},
},
partials: {
hello: '<h1> Hello! </h1>',
},
},
}Let's describe these options: 2. pdfOptions - you can provide pdf options (look options sections here). 3. headers - you can provide headers which will be used on the page, for example you can add authorization header (look here) 4. templateSystem - if you are using Handlebars template then you can provide properties which is used on template (params, helpers, partials).
generateImage(imgPath, [options])
Let's describe these options:
- pagePath - it is the path to html file which will be transformed to pdf.
- options - it is optional param. You can see more in Image options section.
This method returns stream with your img file.
Note: You page that was specified by pagePath should be placed with all assets in one directory. This directory should be isolated from other codebase. You have this restriction because build of all assets looks for all files that was placed in the same directory with your html source. Look to Example for more details.
generateImageByContent(html, [options])
Let's describe these options:
- html - it is the html text which will be transformed to pdf.
- options - it is optional param. You can see more in Image options section.
Image options
Here is the example of pdf options:
{
imgOptions: { // optional
format: 'Letter',
},
headers: { // optional
Authorization: 'Bearer ...'
},
templateSystem: { // optional
params: {
tasks: [{}],
},
helpers: {
hours: Handlebars => (hours) => {
const htmlData = parseFloat(Handlebars.escapeExpression(hours)).toFixed(2);
return new Handlebars.SafeString(htmlData);
},
},
partials: {
hello: '<h1> Hello! </h1>',
},
},
}Let's describe these options: 2. imgOptions - you can provide image options (look options sections here). 3. headers - you can provide headers which will be used on the page, for example you can add authorization header (look here) 4. templateSystem - if you are using Handlebars template then you can provide properties which is used on template (params, helpers, partials).
Debugging
To start library in debug mode you just need to start it with DEBUG=pdf-service. This will provide additional logs.
Examples
You can find the samples in here. To run the sample just write in samples directory:
docker-compose up -d
node index.js
The first command should start pdf server which listen on 4444 port. You can specify another port in docker-compose.yml file. All works in this way:
That's all folks!
Change Log
This project adheres to Semantic Versioning. Every release is documented on the Github Releases page.
License
Ship is released under the MIT License.
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Contributors
Thanks goes to these wonderful people (emoji key):
 KuhArt |
 Uladzimir Mitskevich |
 NesterenkoNikita |
 Andrew Orsich |
 Evgeny Zhivitsa |
 Женя Филиппович |
|---|
This project follows the all-contributors specification. Contributions of any kind welcome!