easy-template-x 3.2.1 → 4.0.0

package/README.md

@@ -14,6 +14,7 @@ Generate docx documents from templates, in Node or in the browser.
   - [Loop plugin](#loop-plugin)
     - [Conditions](#conditions)
     - [Nested Conditions](#nested-conditions)
+    - [Controlling loop behavior](#controlling-loop-behavior)
   - [Image plugin](#image-plugin)
   - [Link plugin](#link-plugin)
   - [Raw xml plugin](#raw-xml-plugin)
@@ -253,6 +254,39 @@ Output document:
 
 _If you are looking for a yet more powerful conditional syntax see the [alternative syntax](#advanced-syntax-and-custom-resolvers) section._
 
+#### Controlling loop behavior
+
+To control the loop (or condition) behavior you can use the `loopOver` option.
+
+Given this data:
+
+```javascript
+{
+    students: [
+        { name: "Alice" },
+        { name: "Bob" }
+    ]
+}
+```
+
+You can use either this template:
+
+![input template](./docs/assets/loop-over-row-in.png?raw=true)
+
+Or this one:
+
+![input template](./docs/assets/loop-over-content-in.png?raw=true)
+
+The first will produce this document:
+
+![output document](./docs/assets/loop-over-row-out.png?raw=true)
+
+And the second will produce this one:
+
+![output document](./docs/assets/loop-over-content-out.png?raw=true)
+
+By default `easy-template-x` will loop over "content" if the opening and closing loop tags are in the same table cell and "row" otherwise.
+
 ### Image plugin
 
 Embed images into the document.
@@ -480,7 +514,9 @@ const handler = new TemplateHandler({
         tagStart: "{",
         tagEnd: "}",
         containerTagOpen: "#",
-        containerTagClose: "/"
+        containerTagClose: "/",
+        tagOptionsStart: "[",
+        tagOptionsEnd: "]"
     },
 
     maxXmlDepth: 20,

package/dist/cjs/easy-template-x.js

@@ -1,15 +1,11 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var xmldom = require('@xmldom/xmldom');
 var getProp = require('lodash.get');
+var JSON5 = require('json5');
 var JSZip = require('jszip');
 
-function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
-
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
+function _interopNamespaceDefault(e) {
   var n = Object.create(null);
   if (e) {
     Object.keys(e).forEach(function (k) {
@@ -22,40 +18,34 @@ function _interopNamespace(e) {
       }
     });
   }
-  n["default"] = e;
+  n.default = e;
   return Object.freeze(n);
 }
 
-var getProp__default = /*#__PURE__*/_interopDefaultLegacy(getProp);
-var JSZip__namespace = /*#__PURE__*/_interopNamespace(JSZip);
+var JSON5__namespace = /*#__PURE__*/_interopNamespaceDefault(JSON5);
+var JSZip__namespace = /*#__PURE__*/_interopNamespaceDefault(JSZip);
 
-function _defineProperty(obj, key, value) {
-  key = _toPropertyKey(key);
-  if (key in obj) {
-    Object.defineProperty(obj, key, {
-      value: value,
-      enumerable: true,
-      configurable: true,
-      writable: true
-    });
-  } else {
-    obj[key] = value;
-  }
-  return obj;
+function _defineProperty(e, r, t) {
+  return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+    value: t,
+    enumerable: !0,
+    configurable: !0,
+    writable: !0
+  }) : e[r] = t, e;
 }
-function _toPrimitive(input, hint) {
-  if (typeof input !== "object" || input === null) return input;
-  var prim = input[Symbol.toPrimitive];
-  if (prim !== undefined) {
-    var res = prim.call(input, hint || "default");
-    if (typeof res !== "object") return res;
+function _toPrimitive(t, r) {
+  if ("object" != typeof t || !t) return t;
+  var e = t[Symbol.toPrimitive];
+  if (void 0 !== e) {
+    var i = e.call(t, r || "default");
+    if ("object" != typeof i) return i;
     throw new TypeError("@@toPrimitive must return a primitive value.");
   }
-  return (hint === "string" ? String : Number)(input);
+  return ("string" === r ? String : Number)(t);
 }
-function _toPropertyKey(arg) {
-  var key = _toPrimitive(arg, "string");
-  return typeof key === "symbol" ? key : String(key);
+function _toPropertyKey(t) {
+  var i = _toPrimitive(t, "string");
+  return "symbol" == typeof i ? i : i + "";
 }
 
 class MalformedFileError extends Error {
@@ -63,9 +53,6 @@ class MalformedFileError extends Error {
     super(`Malformed file detected. Make sure the file is a valid ${expectedFileType} file.`);
     _defineProperty(this, "expectedFileType", void 0);
     this.expectedFileType = expectedFileType;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, MalformedFileError.prototype);
   }
 }
 
@@ -74,9 +61,6 @@ class MaxXmlDepthError extends Error {
     super(`XML maximum depth reached (max depth: ${maxDepth}).`);
     _defineProperty(this, "maxDepth", void 0);
     this.maxDepth = maxDepth;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, MaxXmlDepthError.prototype);
   }
 }
 
@@ -85,9 +69,6 @@ class MissingArgumentError extends Error {
     super(`Argument '${argName}' is missing.`);
     _defineProperty(this, "argName", void 0);
     this.argName = argName;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, MissingArgumentError.prototype);
   }
 }
 
@@ -96,9 +77,6 @@ class MissingCloseDelimiterError extends Error {
     super(`Close delimiter is missing from '${openDelimiterText}'.`);
     _defineProperty(this, "openDelimiterText", void 0);
     this.openDelimiterText = openDelimiterText;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, MissingCloseDelimiterError.prototype);
   }
 }
 
@@ -107,9 +85,16 @@ class MissingStartDelimiterError extends Error {
     super(`Open delimiter is missing from '${closeDelimiterText}'.`);
     _defineProperty(this, "closeDelimiterText", void 0);
     this.closeDelimiterText = closeDelimiterText;
+  }
+}
 
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, MissingStartDelimiterError.prototype);
+class TagOptionsParseError extends Error {
+  constructor(tagRawText, parseError) {
+    super(`Failed to parse tag options of '${tagRawText}': ${parseError.message}.`);
+    _defineProperty(this, "tagRawText", void 0);
+    _defineProperty(this, "parseError", void 0);
+    this.tagRawText = tagRawText;
+    this.parseError = parseError;
   }
 }
 
@@ -118,18 +103,12 @@ class UnclosedTagError extends Error {
     super(`Tag '${tagName}' is never closed.`);
     _defineProperty(this, "tagName", void 0);
     this.tagName = tagName;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, UnclosedTagError.prototype);
   }
 }
 
 class UnidentifiedFileTypeError extends Error {
   constructor() {
     super(`The filetype for this file could not be identified, is this file corrupted?`);
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, UnidentifiedFileTypeError.prototype);
   }
 }
 
@@ -142,9 +121,6 @@ class UnknownContentTypeError extends Error {
     this.contentType = contentType;
     this.tagRawText = tagRawText;
     this.path = path;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, UnknownContentTypeError.prototype);
   }
 }
 
@@ -153,9 +129,6 @@ class UnopenedTagError extends Error {
     super(`Tag '${tagName}' is closed but was never opened.`);
     _defineProperty(this, "tagName", void 0);
     this.tagName = tagName;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, UnopenedTagError.prototype);
   }
 }
 
@@ -164,9 +137,6 @@ class UnsupportedFileTypeError extends Error {
     super(`Filetype "${fileType}" is not supported.`);
     _defineProperty(this, "fileType", void 0);
     this.fileType = fileType;
-
-    // typescript hack: https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
-    Object.setPrototypeOf(this, UnsupportedFileTypeError.prototype);
   }
 }
 
@@ -416,12 +386,48 @@ function utf8Encode(str) {
   return utfStr;
 }
 
+// Copied from: https://gist.github.com/thanpolas/244d9a13151caf5a12e42208b6111aa6
+// And see: https://unicode-table.com/en/sets/quotation-marks/
+const nonStandardDoubleQuotes = ['“',
+// U+201c
+'”',
+// U+201d
+'«',
+// U+00AB
+'»',
+// U+00BB
+'„',
+// U+201E
+'“',
+// U+201C
+'‟',
+// U+201F
+'”',
+// U+201D
+'❝',
+// U+275D
+'❞',
+// U+275E
+'〝',
+// U+301D
+'〞',
+// U+301E
+'〟',
+// U+301F
+'＂' // U+FF02
+];
+const standardDoubleQuotes = '"'; // U+0022
+
+const nonStandardDoubleQuotesRegex = new RegExp(nonStandardDoubleQuotes.join('|'), 'g');
 function stringValue(val) {
   if (val === null || val === undefined) {
     return '';
   }
   return val.toString();
 }
+function normalizeDoubleQuotes(text) {
+  return text.replace(nonStandardDoubleQuotesRegex, standardDoubleQuotes);
+}
 
 class XmlDepthTracker {
   constructor(maxDepth) {
@@ -536,31 +542,39 @@ const XmlNode = {
    * The conversion is always deep.
    */
   fromDomNode(domNode) {
-    var _domNode$textContent;
     let xmlNode;
 
     // basic properties
     switch (domNode.nodeType) {
       case domNode.TEXT_NODE:
-        xmlNode = this.createTextNode(domNode.textContent);
-        break;
+        {
+          xmlNode = this.createTextNode(domNode.textContent);
+          break;
+        }
       case domNode.COMMENT_NODE:
-        xmlNode = this.createCommentNode((_domNode$textContent = domNode.textContent) === null || _domNode$textContent === void 0 ? void 0 : _domNode$textContent.trim());
-        break;
+        {
+          var _domNode$textContent;
+          xmlNode = this.createCommentNode((_domNode$textContent = domNode.textContent) === null || _domNode$textContent === void 0 ? void 0 : _domNode$textContent.trim());
+          break;
+        }
       case domNode.ELEMENT_NODE:
-        const generalNode = xmlNode = this.createGeneralNode(domNode.nodeName);
-        const attributes = domNode.attributes;
-        if (attributes) {
-          generalNode.attributes = {};
-          for (let i = 0; i < attributes.length; i++) {
-            const curAttribute = attributes.item(i);
-            generalNode.attributes[curAttribute.name] = curAttribute.value;
+        {
+          const generalNode = xmlNode = this.createGeneralNode(domNode.nodeName);
+          const attributes = domNode.attributes;
+          if (attributes) {
+            generalNode.attributes = {};
+            for (let i = 0; i < attributes.length; i++) {
+              const curAttribute = attributes.item(i);
+              generalNode.attributes[curAttribute.name] = curAttribute.value;
+            }
           }
+          break;
         }
-        break;
       default:
-        xmlNode = this.createGeneralNode(domNode.nodeName);
-        break;
+        {
+          xmlNode = this.createGeneralNode(domNode.nodeName);
+          break;
+        }
     }
 
     // children
@@ -836,9 +850,11 @@ const XmlNode = {
  *
  * * **Note:** Prefer calling with explicit index.
  */
+
 /**
  * Remove a child node from it's parent. Returns the removed child.
  */
+
 function removeChild(parent, childOrIndex) {
   if (!parent) throw new MissingArgumentError("parent");
   if (childOrIndex === null || childOrIndex === undefined) throw new MissingArgumentError("childOrIndex");
@@ -1115,7 +1131,7 @@ class ScopeData {
     const curPath = args.strPath.slice();
     while (result === undefined && curPath.length) {
       curPath.pop();
-      result = getProp__default["default"](args.data, curPath.concat(lastKey));
+      result = getProp(args.data, curPath.concat(lastKey));
     }
     return result;
   }
@@ -1165,7 +1181,8 @@ class TagParser {
     _defineProperty(this, "tagRegex", void 0);
     if (!docParser) throw new MissingArgumentError("docParser");
     if (!delimiters) throw new MissingArgumentError("delimiters");
-    this.tagRegex = new RegExp(`^${Regex.escape(delimiters.tagStart)}(.*?)${Regex.escape(delimiters.tagEnd)}`, 'm');
+    const tagOptionsRegex = `${Regex.escape(delimiters.tagOptionsStart)}(?<tagOptions>.*?)${Regex.escape(delimiters.tagOptionsEnd)}`;
+    this.tagRegex = new RegExp(`^${Regex.escape(delimiters.tagStart)}(?<tagName>.*?)(${tagOptionsRegex})?${Regex.escape(delimiters.tagEnd)}`, 'm');
   }
   parse(delimiters) {
     const tags = [];
@@ -1264,23 +1281,44 @@ class TagParser {
     closeDelimiter.xmlTextNode = endTextNode;
   }
   processTag(tag) {
+    var _tagParts$groups, _tagParts$groups2;
     tag.rawText = tag.xmlTextNode.textContent;
     const tagParts = this.tagRegex.exec(tag.rawText);
-    const tagContent = (tagParts[1] || '').trim();
-    if (!tagContent || !tagContent.length) {
+    const tagName = (((_tagParts$groups = tagParts.groups) === null || _tagParts$groups === void 0 ? void 0 : _tagParts$groups["tagName"]) || '').trim();
+
+    // Ignoring empty tags.
+    if (!(tagName !== null && tagName !== void 0 && tagName.length)) {
       tag.disposition = TagDisposition.SelfClosed;
       return;
     }
-    if (tagContent.startsWith(this.delimiters.containerTagOpen)) {
+
+    // Tag options.
+    const tagOptionsText = (((_tagParts$groups2 = tagParts.groups) === null || _tagParts$groups2 === void 0 ? void 0 : _tagParts$groups2["tagOptions"]) || '').trim();
+    if (tagOptionsText) {
+      try {
+        tag.options = JSON5__namespace.parse("{" + normalizeDoubleQuotes(tagOptionsText) + "}");
+      } catch (e) {
+        throw new TagOptionsParseError(tag.rawText, e);
+      }
+    }
+
+    // Container open tag.
+    if (tagName.startsWith(this.delimiters.containerTagOpen)) {
       tag.disposition = TagDisposition.Open;
-      tag.name = tagContent.slice(this.delimiters.containerTagOpen.length).trim();
-    } else if (tagContent.startsWith(this.delimiters.containerTagClose)) {
+      tag.name = tagName.slice(this.delimiters.containerTagOpen.length).trim();
+      return;
+    }
+
+    // Container close tag.
+    if (tagName.startsWith(this.delimiters.containerTagClose)) {
       tag.disposition = TagDisposition.Close;
-      tag.name = tagContent.slice(this.delimiters.containerTagClose.length).trim();
-    } else {
-      tag.disposition = TagDisposition.SelfClosed;
-      tag.name = tagContent;
+      tag.name = tagName.slice(this.delimiters.containerTagClose.length).trim();
+      return;
     }
+
+    // Self-closed tag.
+    tag.disposition = TagDisposition.SelfClosed;
+    tag.name = tagName;
   }
 }
 
@@ -1323,8 +1361,6 @@ class MimeTypeHelper {
   }
 }
 
-/* eslint-disable @typescript-eslint/member-ordering */
-
 class TemplatePlugin {
   constructor() {
     /**
@@ -1877,6 +1913,7 @@ class Docx {
   //
   // static methods
   //
+
   static async open(zip, xmlParser) {
     const mainDocumentPath = await Docx.getMainDocumentPath(zip, xmlParser);
     if (!mainDocumentPath) throw new MalformedFileError('docx');
@@ -2023,6 +2060,7 @@ class DocxParser {
   //
   // constructor
   //
+
   constructor(xmlParser) {
     this.xmlParser = xmlParser;
   }
@@ -2547,6 +2585,12 @@ class LoopParagraphStrategy {
   }
 }
 
+let LoopOver = /*#__PURE__*/function (LoopOver) {
+  LoopOver["Row"] = "row";
+  LoopOver["Content"] = "content";
+  return LoopOver;
+}({});
+
 class LoopTableStrategy {
   constructor() {
     _defineProperty(this, "utilities", void 0);
@@ -2555,9 +2599,18 @@ class LoopTableStrategy {
     this.utilities = utilities;
   }
   isApplicable(openTag, closeTag) {
-    const containingParagraph = this.utilities.docxParser.containingParagraphNode(openTag.xmlTextNode);
-    if (!containingParagraph.parentNode) return false;
-    return this.utilities.docxParser.isTableCellNode(containingParagraph.parentNode);
+    const openParagraph = this.utilities.docxParser.containingParagraphNode(openTag.xmlTextNode);
+    if (!openParagraph.parentNode) return false;
+    if (!this.utilities.docxParser.isTableCellNode(openParagraph.parentNode)) return false;
+    const closeParagraph = this.utilities.docxParser.containingParagraphNode(closeTag.xmlTextNode);
+    if (!closeParagraph.parentNode) return false;
+    if (!this.utilities.docxParser.isTableCellNode(closeParagraph.parentNode)) return false;
+    const options = openTag.options;
+    const forceRowLoop = (options === null || options === void 0 ? void 0 : options.loopOver) === LoopOver.Row;
+
+    // If both tags are in the same cell, assume it's a paragraph loop (iterate content, not rows).
+    if (!forceRowLoop && openParagraph.parentNode === closeParagraph.parentNode) return false;
+    return true;
   }
   splitBefore(openTag, closeTag) {
     const firstRow = this.utilities.docxParser.containingTableRowNode(openTag.xmlTextNode);
@@ -2596,7 +2649,6 @@ class LoopPlugin extends TemplatePlugin {
     _defineProperty(this, "loopStrategies", [new LoopTableStrategy(), new LoopListStrategy(), new LoopParagraphStrategy() // the default strategy
     ]);
   }
-
   setUtilities(utilities) {
     this.utilities = utilities;
     this.loopStrategies.forEach(strategy => strategy.setUtilities(utilities));
@@ -2607,7 +2659,7 @@ class LoopPlugin extends TemplatePlugin {
     // Non array value - treat as a boolean condition.
     const isCondition = !Array.isArray(value);
     if (isCondition) {
-      if (!!value) {
+      if (value) {
         value = [{}];
       } else {
         value = [];
@@ -2978,7 +3030,6 @@ class Zip {
         level: 6 // between 1 (best speed) and 9 (best compression)
       }
     });
-
     return output;
   }
 }
@@ -2989,6 +3040,8 @@ class Delimiters {
     _defineProperty(this, "tagEnd", "}");
     _defineProperty(this, "containerTagOpen", "#");
     _defineProperty(this, "containerTagClose", "/");
+    _defineProperty(this, "tagOptionsStart", "[");
+    _defineProperty(this, "tagOptionsEnd", "]");
     Object.assign(this, initial);
     this.encodeAndValidate();
     if (this.containerTagOpen === this.containerTagClose) throw new Error(`${"containerTagOpen"} can not be equal to ${"containerTagClose"}`);
@@ -3211,6 +3264,7 @@ exports.ScopeData = ScopeData;
 exports.TEXT_CONTENT_TYPE = TEXT_CONTENT_TYPE;
 exports.TEXT_NODE_NAME = TEXT_NODE_NAME;
 exports.TagDisposition = TagDisposition;
+exports.TagOptionsParseError = TagOptionsParseError;
 exports.TagParser = TagParser;
 exports.TemplateCompiler = TemplateCompiler;
 exports.TemplateExtension = TemplateExtension;
@@ -3236,6 +3290,7 @@ exports.inheritsFrom = inheritsFrom;
 exports.isNumber = isNumber;
 exports.isPromiseLike = isPromiseLike;
 exports.last = last;
+exports.normalizeDoubleQuotes = normalizeDoubleQuotes;
 exports.pushMany = pushMany;
 exports.sha1 = sha1;
 exports.stringValue = stringValue;