Open Source docxtemplater image module
This repository holds an maintained version of docxtemplater image module.
This package is open source. There is also a paid version maintained by docxtemplater author.
Note this version is compatible with docxtemplater 3.x.
Installation
You first need to install docxtemplater by following its installation guide.
For Node.js install this package:
npm install docxtemplater-image-module-free
For the browser find builds in build/
directory.
Alternatively, you can create your own build from the sources:
npm run compilenpm run browserifynpm run uglify
Usage
Assuming your docx or pptx template contains only the text {%image}
:
//Node.js examplevar ImageModule = ; //Below the options that will be passed to ImageModule instancevar opts = {}optscentered = false; //Set to true to always center imagesoptsfileType = "docx"; //Or pptx //Pass your image loaderopts { //tagValue is 'examples/image.png' //tagName is 'image' return fs;} //Pass the function that return image sizeopts { //img is the image returned by opts.getImage() //tagValue is 'examples/image.png' //tagName is 'image' //tip: you can use node module 'image-size' here return 150 150;} var imageModule = opts; var zip = content;var doc = ; var buffer = doc ; fs;
Some notes regarding templates:
- docx files: the placeholder
{%image}
must be in a dedicated paragraph. - pptx files: the placeholder
{%image}
must be in a dedicated text cell.
In the browser, this shows how to get the image asynchronously :
Centering images
You can center all images by setting the global switch to true opts.centered = true
.
If you would like to choose which images should be centered one by one:
- Set the global switch to false
opts.centered = false
. - Use
{%image}
for images that shouldn't be centered. - Use
{%%image}
for images that you would like to see centered.
In pptx generated documents, images are centered vertically and horizontally relative to the parent cell.
Async support
It is possible to get images asynchronously by returning a Promise in the getImage function and use the docxtemplater async api : http://docxtemplater.readthedocs.io/en/latest/async.html
You can also return a promise in the getSize function if you want to resolve the size asynchronously (like in the browser example above).
Here is an example in node that allows you to retrieve values from an URL and use a fixed width, and keep the aspect ratio.
const fs = ;const DocxTemplater = ;const https = ;const Stream = Transform; const ImageModule = ;const JSZip = ; const content = fs; const data = image: "https://docxtemplater.com/xt-pro.png"; const opts = {};opts { console; // tagValue is "https://docxtemplater.com/xt-pro-white.png" and tagName is "image" return { ; };}; opts { console; // img is the value that was returned by getImage // This is to force the width to 600px, but keep the same aspect ration const sizeOf = ; const sizeObj = ; console; const forceWidth = 600; const ratio = forceWidth / sizeObjwidth; return forceWidth // calculate height taking into account aspect ratio Math ;}; const imageModule = opts; const zip = content;const doc = ; doc ; { https ;}
Size and path based on placeholder
You can have customizable image loader using the template's placeholder name.
opts.getImage = function (tagValue, tagName) {
if(tagName === 'logo')
return fs.readFileSync(__dirname + '/logos/' + tagValue);
return fs.readFileSync(__dirname + '/images/' + tagValue);
};
The same thing can be used to customize image size.
opts.getSize = function (img, tagValue, tagName) {
if(tagName === 'logo')
return [100, 100];
return [300, 300];
};
Base64 include
You can use base64 images with the following code:
{ const base64Regex = /^data:image\/;base64,/; if !base64Regex return false; const stringBase64 = dataURL; let binaryString; if typeof window !== "undefined" binaryString = window; else binaryString = stringBase64 "base64"; const len = binaryStringlength; const bytes = len; for let i = 0; i < len; i++ const ascii = binaryString; bytesi = ascii; return bytesbuffer;}const imageOpts = { return ; } { return 100 100; };doc;