- (PR #321) Fix
InvalidCommandError
referring to'Unexpected END-IF outside of IF statement context:'
when the problem was actually an unexpectedEND-FOR
. Thanks @davidjb - Issue #322: Fix silent failure caused by unterminated for-loop in template, leading to a (partially) empty report. Throw new
UnterminatedForLoopError
whenFOR
loop is not properly terminated with anEND-FOR
. - Remove unnecessary runtime dependency (
timm
). - Upgrade
jszip
dependency to latest version.
- Issue #296: Fix bug caused by Shapes having the same ID they are generated from a FOR loop. (PR #315) Thanks @SuchiraD!
- Issue #314: Ensure all custom error types are exported.
- (PR #305) the
IncompleteConditionalStatementError
is now thrown when an 'IF' statement lacks a corresponding 'END-IF' command. Thanks @RoXuS !
- Issue #143: Add optional
processLineBreaksAsNewText
toggle which provides an alternative way of inserting line breaks from commands into the docx XML. This should improve rendering of newlines in a few docx readers, like LibreOffice. (PR #182). Thanks @khaled-iva-docs ! - Updated dependencies.
- Issue #194: add ability to provide captions for images (PR #286).
- Ensure XMLs are processed in a deterministic order (mainly relevant for
listCommands()
), see commit 8b2ba5526df78da675eaf59f88cb76035ffac5bd. - Various minor code quality and typing improvements.
- Bumped dependencies.
- PR 266 Fix types for Deno bundle (by @mathe42).
- Issue #259 Fix issue that caused inserted images to be overwritten when
createReport()
was invoked a second time on the resulting template.
- Updated dependencies.
- PR 253 Add support for Deno through the browser bundle. Thanks @mathe42!
- PR 233 Prevent adding empty paragraph if cell contains altChunk. Thanks @pkozul!
- #239 Fixed issue that prevented the
listCommands
function from detecting commands in the template's header and footer.
- #231 The library now also comes with a pre-compiled and polyfilled browser build. See documentation in README. Thanks @mathe42!
- PR 229 Minor change to how filenames of HTML snippets are formatted in the final .docx file so the resulting documents work with picky parsers.
- #221 New feature: user can now optionally specify image rotation when using IMAGE commands.
- #218 Fixed bug that caused redundant copies of images to be inserted into the docx file.
- #133 Fix for the INTERNAL ERROR thrown when using links inside for loops.
- #222 Fix for bug that caused HTML commands to produce corrupted docx files.
- Fixed bug that caused IMAGE commands in the document body to be ignored when a shape or image was already present in the document's header or footer. (#217).
- Allow arrays as the result of INS commands again (#214). Thanks @LexAckson for pointing this out.
- Fix for issues #190 and #144. Image IDs in the rendered XML are now ensured to be globally unique to avoid warnings of file corruption in some popular editors (like MS Word).
- Fix for issue #213: throw an error when user tries to iterate over a non-array in a template with a FOR loop. This used to create an infinite loop.
- Throw
ObjectCommandResultError
when the result of anINS
command is an Object. This ensures you don't accidentally put'[object Object]'
in your report.
- Add support for
.docm
(macro-enabled) templates (issue #195). Thanks @brockfanning!
- Improve error messages.
- Export error types at the library level.
- Update dependencies.
- Correctly export
getMetadata
function from library index module / entrypoint.
- Corrected check for valid image data. ArrayBuffers are now also valid image data containers, as the type definitions suggest (issue #166).
- Enhancement: extensive validation of
IMAGE
command parameters before execution to prevent silent failures caused by user error, particularly in plain javascript and untyped settings. Related to issue #158.
- Feature: added
fixSmartQuotes
flag (see PR #152). Thanks @speedpro! MS Word usually autocorrects JS string literal quotes with unicode 'smart' quotes ('curly' quotes). E.g. 'aubergine' -> ‘aubergine’. This causes an error when evaluating commands containing these smart quotes, as they are not valid JavaScript. If you setfixSmartQuotes
to 'true', these smart quotes will automatically get replaced with straight quotes (') before command evaluation. Defaults to false.
- Feature: added
getMetadata
function to extract the metadata fields from a document, such as the number of pages or words (see issue #94). - Feature: user can now provide a custom
errorHandler
callback to handle any errors that may occur when executing commands from a template. The value returned by this callback will be inserted into the rendered document instead (see issue #138). - Restructured
CommandExecutionError
to make it contain the full Error original object that caused it to be thrown.
- Feature: added
listCommands
function to find and list all commands in a document (see issue #90). - Minor refactoring.
- Updated jszip dependency.
- Feature: added 'rejectNullish' setting. When set to
true
, this setting ensurescreateReport
throws aNullishCommandResultError
when the result of an INS, HTML, IMAGE, or LINK command isnull
orundefined
. This is useful as nullish return values usually indicate a mistake in the template or the invoking code. Defaults tofalse
. - Enhancement: typed Errors to facilitate more fine-grained downstream error handling.
- PR #121 Improved detection of built-in commands in templates to avoid confusion with javascript symbols.
- #107 Library now correctly recognizes user-defined commands with non-alphanumeric names (like Chinese characters).
- #131: .docx template files originating from Office365 or SharePoint can now be used (PR #132)
- #112 Failing on the first error that is encountered while rendering a template is now optional behaviour (but still the default). Use
failFast: false
to collect all errors in a template before failing. This allows for less cumbersome interactive correction of typos or other mistakes in template commands. - #33 SVGs can now be inserted into the templates directly, based on excellent work by @lwallent.
- #113 fixed a regression caused by relying on incomplete jsZip type definitions.
- #83 fixed a bug that occurred when links were used in FOR loops.
- Added docstrings (thanks @mathe42 !)
-
Removed Flow and switched entire codebase over to TypeScript. In the process a few minor soundness issues were fixed.
-
Breaking change Removed dependency on Node filesystem APIs so the library no longer needs a separate node and browser entrypoint, simplifying maintenance and development. This has the following implications for the public API, justifying the version bump to 4.0.0:
-
You can no longer provide image data as a path, and need to provide an
ArrayBuffer
or base64-encoded string instead. -
You can no longer provide a template as a filesystem path, and you'll need to read it into a Buffer first.
-
Removed
output: 'buffer'
argument. The output ofcreateReport
is now always aUint8Array
, unless the debug argument_probe
is specified.
-
The README and examples have also been updated to reflect the above changes.
- Avoid issue when a single paragraph contains
END-IF/FOR
for a previous loop andIF/FOR
for a new one (#72). - Fix hyperlink styles (#64).
- Allow different left/right command delimiters, e.g.
cmdDelimiter: ['{', '}']
(#66, #70). - Allow omission of the
INS
(or=
) command (#70).
- Breaking change: removed
replaceImages
,replaceImagesBase64
options (deprecated since v2.4.0). Please use theIMAGE
command instead. - Breaking change for users of the
vm2
sandbox: replacedvm2Sandbox
option (which caused headaches for users in the browser) withrunJs
, a custom hook for JS snippet execution. If you want to use vm2:
import createReport from 'docx-templates';
import { VM, VMScript } from 'vm2';
createReport({
template: /* ... */,
data: /* ... */,
runJs: ({ sandbox }) => {
const script = new VMScript(
`
__result__ = eval(__code__);
`
).compile();
const vm2 = new VM({ sandbox });
vm2.run(script);
const { VMError, Buffer, ...modifiedSandbox } = vm2._context;
const result = modifiedSandbox.__result__;
return { modifiedSandbox, result };
}
})
- Let alternate text be specified for images (@emilong, #57).
- Fix race condition in which a file was generated and was later used by another section of the processor (added cache in zip module) (should solve #44).
- Accept Buffer in
template
and'buffer'
inoutput
.
- Support
null
as output from a JS snippet in Word (#39).
IMAGE
: add BMP support (#34).
- Add
HTML
command (!!!) (@vdechef, #32). - Fix browser examples by shimming
vm2
(@vdechef, #35).
- Add
LINK
command (!!!) (#20).
- Bugfix: fix multiline query extraction (#21).
- Bugfix: correctly escape output attributes to avoid issues like #24 (watermask).
- Bugfix: avoid messing up of images inserted in the document body with those inserted in the header (#25).
- Add
vm2Sandbox
option for higher security in JS execution (@nheisterkamp, #26).
- Support
IMAGE
command in headers, footers, etc. (#19).
- Add
IMAGE
command (!!!). - Made it a monorepo: main package + examples.
- Deprecates
replaceImages
andreplaceImagesBase64
options (please use theIMAGE
command).
- Compress generated reports to reduce size (@vdechef, #13).
- Add browser support (@vdechef, #10)
- Add
IF
/END-IF
- Bugfix: Remove
babel-polyfill
dependency, replace by the lightweightbabel-runtime
+babel-plugin-transform-runtime
(#7)
- Add
replaceImages
option (including base64 support viareplaceImagesBase64
option) [based on #5]
- Fix a case in which the tool hangs indefinitely when a query is expected and not found.
- [M] Add support for commands in headers, footers and elsewhere
- Breaking changes:
SHORTHAND
has been renamedALIAS
- Alias resolution syntax has changed:
+++[name]+++
is no longer supported; use+++*name+++
instead (for coherence with other commands)
- Non-breaking:
- [M] Add support for JS code in
INS
,VAR
andFOR
- [M] Add
EXEC
command (no output) - [M] Add shorthand notation:
=
forINS
,!
forEXEC
,*
shorthand for alias resolution - [M] Improve robustness:
- Much more robust internal algorithm
- Now allows command delimiters to be split across multiple
w:t
elements+ - Better handling of spaces in commands
- Better handling of spaces in text with interspersed commands
- [M] Process line breaks in input strings correctly, producing
<w:br/>
tags (can be disabled) - [M] Allow insertion of literal XML (with configurable delimiter,
||
by default) - [m] Allow customisation of the command delimiter
- [M] Allow loops in a single paragraph
- [m] Remove archive.bulk() deprecation warning
- [M] Add support for JS code in
- [M] Add docs
- [M] First public release