easy-template-x 7.0.2 → 7.0.3

package/README.md

@@ -12,10 +12,10 @@ Generate docx documents from templates, in Node or in the browser.
 >
 > Check out [templatedocs.io](https://templatedocs.io) - a cloud platform for document generation with:
 >
-> ✓ PDF support  
-> ✓ REST API integration  
-> ✓ Built-in email delivery  
+> ✓ Built-in workflow automation and email delivery  
 > ✓ Zapier and Make integration  
+> ✓ REST API integration  
+> ✓ PDF output support  
 > ✓ Live preview functionality  
 > ✓ Easy-to-use UI  
 >
@@ -43,7 +43,6 @@ Generate docx documents from templates, in Node or in the browser.
 - [Scope resolution](#scope-resolution)
 - [Extensions](#extensions)
   - [Community Extensions](#community-extensions)
-    - [Data Binding Extension](#data-binding-extension)
 - [Template handler options](#template-handler-options)
   - [Custom tag delimiters](#custom-tag-delimiters)
   - [Advanced syntax and custom resolvers](#advanced-syntax-and-custom-resolvers)
@@ -749,11 +748,7 @@ const handler = new TemplateHandler({
 The following extensions were developed by the community.  
 Want to see your extension here? Submit a pull request or [open an issue](https://github.com/alonrbar/easy-template-x/issues).
 
-#### Data Binding Extension
-
-The [easy-template-x-data-binding](https://github.com/sebastianrogers/easy-template-x-data-binding) extension supports updating [custom XML files](https://docs.microsoft.com/en-gb/archive/blogs/modonovan/word-2007-content-controls-and-xml-part-1-the-basics) inside Word documents.
-
-This allows using `easy-template-x` to automatically fill [Word forms](https://support.office.com/en-us/article/create-forms-that-users-complete-or-print-in-word-040c5cc1-e309-445b-94ac-542f732c8c8b) that uses content controls.
+- **Data Binding Extension** - The [easy-template-x-data-binding](https://github.com/sebastianrogers/easy-template-x-data-binding) extension supports updating [custom XML parts](https://www.google.com/search?q=word+custom+xml+part) inside Word documents.
 
 ## Template handler options
 

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

@@ -1768,6 +1768,26 @@ class W {
   TableCell = 'w:tc';
   Drawing = 'w:drawing';
   NumberProperties = 'w:numPr';
+  /**
+   * Structured document tag (content control).
+   * 
+   * See: ECMA-376, Part 1, sections 17.5 and 17.5.2
+   */
+  StructuredTag = 'w:sdt';
+  /**
+   * Structured document tag properties.
+   */
+  StructuredTagProperties = 'w:sdtPr';
+  /**
+   * Structured document tag content.
+   */
+  StructuredTagContent = 'w:sdtContent';
+  /**
+   * Complex field character (legacy form field).
+   * 
+   * see: http://officeopenxml.com/WPfields.php
+   */
+  FieldChar = 'w:fldChar';
 }
 
 /**
@@ -1853,6 +1873,9 @@ class Pic {
  * used in Office Open XML documents. Including but not limited to
  * Wordprocessing Markup Language, Drawing Markup Language and Spreadsheet
  * Markup Language.
+ * 
+ * - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+ * - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
  */
 class OmlNode {
   /**
@@ -1877,6 +1900,12 @@ class OmlNode {
 }
 class OmlAttribute {
   static SpacePreserve = 'xml:space';
+  /**
+   * Complex field character type.
+   * 
+   * see: http://officeopenxml.com/WPfields.php
+   */
+  static FieldCharType = 'w:fldCharType';
 }
 
 //
@@ -1897,7 +1926,8 @@ class OmlAttribute {
 //   </w:r>
 // </w:p>
 //
-// see: http://officeopenxml.com/WPcontentOverview.php
+// - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+// - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
 //
 
 /**
@@ -2012,6 +2042,13 @@ class Query {
     return xml.query.findParentByName(node, OmlNode.W.Table);
   }
 
+  /**
+   * Search **upwards** for the first `w:sdtContent` node.
+   */
+  containingStructuredTagContentNode(node) {
+    return xml.query.findParentByName(node, OmlNode.W.StructuredTagContent);
+  }
+
   //
   // Advanced queries
   //
@@ -2051,29 +2088,29 @@ class Modify {
     let firstXmlTextNode;
     let secondXmlTextNode;
 
-    // split nodes
+    // Split nodes
     const wordTextNode = officeMarkup.query.containingTextNode(textNode);
     const newWordTextNode = xml.create.cloneNode(wordTextNode, true);
 
-    // set space preserve to prevent display differences after splitting
+    // Set space preserve to prevent display differences after splitting
     // (otherwise if there was a space in the middle of the text node and it
     // is now at the beginning or end of the text node it will be ignored)
     officeMarkup.modify.setSpacePreserveAttribute(wordTextNode);
     officeMarkup.modify.setSpacePreserveAttribute(newWordTextNode);
     if (addBefore) {
-      // insert new node before existing one
+      // Insert new node before existing one
       xml.modify.insertBefore(newWordTextNode, wordTextNode);
       firstXmlTextNode = xml.query.lastTextChild(newWordTextNode);
       secondXmlTextNode = textNode;
     } else {
-      // insert new node after existing one
+      // Insert new node after existing one
       const curIndex = wordTextNode.parentNode.childNodes.indexOf(wordTextNode);
       xml.modify.insertChild(wordTextNode.parentNode, newWordTextNode, curIndex + 1);
       firstXmlTextNode = textNode;
       secondXmlTextNode = xml.query.lastTextChild(newWordTextNode);
     }
 
-    // edit text
+    // Edit text
     const firstText = firstXmlTextNode.textContent;
     const secondText = secondXmlTextNode.textContent;
     firstXmlTextNode.textContent = firstText.substring(0, splitIndex);
@@ -2088,25 +2125,27 @@ class Modify {
    * `false` then the original text node is the first text node of `right`.
    */
   splitParagraphByTextNode(paragraph, textNode, removeTextNode) {
-    // input validation
+    // Input validation
     const containingParagraph = officeMarkup.query.containingParagraphNode(textNode);
-    if (containingParagraph != paragraph) throw new Error(`Node 'textNode' is not a contained in the specified paragraph.`);
+    if (containingParagraph != paragraph) throw new Error(`Node 'textNode' is not contained in the specified paragraph.`);
     const runNode = officeMarkup.query.containingRunNode(textNode);
     const wordTextNode = officeMarkup.query.containingTextNode(textNode);
 
-    // create run clone
+    // 1. Split the run
+
+    // Create run clone (left) and keep the original run (right).
     const leftRun = xml.create.cloneNode(runNode, false);
     const rightRun = runNode;
     xml.modify.insertBefore(leftRun, rightRun);
 
-    // copy props from original run node (preserve style)
+    // Copy props from original run node (preserve style)
     const runProps = rightRun.childNodes.find(node => officeMarkup.query.isRunPropertiesNode(node));
     if (runProps) {
       const leftRunProps = xml.create.cloneNode(runProps, true);
       xml.modify.appendChild(leftRun, leftRunProps);
     }
 
-    // move nodes from 'right' to 'left'
+    // Move all text nodes up to the specified text node, to the new run.
     const firstRunChildIndex = runProps ? 1 : 0;
     let curChild = rightRun.childNodes[firstRunChildIndex];
     while (curChild != wordTextNode) {
@@ -2115,24 +2154,26 @@ class Modify {
       curChild = rightRun.childNodes[firstRunChildIndex];
     }
 
-    // remove text node
+    // Remove text node
     if (removeTextNode) {
       xml.modify.removeChild(rightRun, firstRunChildIndex);
     }
 
-    // create paragraph clone
+    // 2. Split the paragraph
+
+    // Create paragraph clone (left) and keep the original paragraph (right).
     const leftPara = xml.create.cloneNode(containingParagraph, false);
     const rightPara = containingParagraph;
     xml.modify.insertBefore(leftPara, rightPara);
 
-    // copy props from original paragraph (preserve style)
+    // Copy props from original paragraph (preserve style)
     const paragraphProps = rightPara.childNodes.find(node => officeMarkup.query.isParagraphPropertiesNode(node));
     if (paragraphProps) {
       const leftParagraphProps = xml.create.cloneNode(paragraphProps, true);
       xml.modify.appendChild(leftPara, leftParagraphProps);
     }
 
-    // move nodes from 'right' to 'left'
+    // Move all run nodes up to the original run (right), to the new paragraph (left).
     const firstParaChildIndex = paragraphProps ? 1 : 0;
     curChild = rightPara.childNodes[firstParaChildIndex];
     while (curChild != rightRun) {
@@ -2141,7 +2182,7 @@ class Modify {
       curChild = rightPara.childNodes[firstParaChildIndex];
     }
 
-    // clean paragraphs - remove empty runs
+    // Clean paragraphs - remove empty runs
     if (officeMarkup.query.isEmptyRun(leftRun)) xml.modify.remove(leftRun);
     if (officeMarkup.query.isEmptyRun(rightRun)) xml.modify.remove(rightRun);
     return [leftPara, rightPara];
@@ -2151,21 +2192,21 @@ class Modify {
    * Move all text between the 'from' and 'to' nodes to the 'from' node.
    */
   joinTextNodesRange(from, to) {
-    // find run nodes
+    // Find run nodes
     const firstRunNode = officeMarkup.query.containingRunNode(from);
     const secondRunNode = officeMarkup.query.containingRunNode(to);
     const paragraphNode = firstRunNode.parentNode;
     if (secondRunNode.parentNode !== paragraphNode) throw new Error('Can not join text nodes from separate paragraphs.');
 
-    // find "word text nodes"
+    // Find "word text nodes"
     const firstWordTextNode = officeMarkup.query.containingTextNode(from);
     const secondWordTextNode = officeMarkup.query.containingTextNode(to);
     const totalText = [];
 
-    // iterate runs
+    // Iterate runs
     let curRunNode = firstRunNode;
     while (curRunNode) {
-      // iterate text nodes
+      // Iterate text nodes
       let curWordTextNode;
       if (curRunNode === firstRunNode) {
         curWordTextNode = firstWordTextNode;
@@ -2178,11 +2219,11 @@ class Modify {
           continue;
         }
 
-        // move text to first node
+        // Move text to first node
         const curXmlTextNode = xml.query.lastTextChild(curWordTextNode);
         totalText.push(curXmlTextNode.textContent);
 
-        // next text node
+        // Next text node
         const textToRemove = curWordTextNode;
         if (curWordTextNode === secondWordTextNode) {
           curWordTextNode = null;
@@ -2190,13 +2231,13 @@ class Modify {
           curWordTextNode = curWordTextNode.nextSibling;
         }
 
-        // remove current text node
+        // Remove current text node
         if (textToRemove !== firstWordTextNode) {
           xml.modify.remove(textToRemove);
         }
       }
 
-      // next run
+      // Next run
       const runToRemove = curRunNode;
       if (curRunNode === secondRunNode) {
         curRunNode = null;
@@ -2204,13 +2245,13 @@ class Modify {
         curRunNode = curRunNode.nextSibling;
       }
 
-      // remove current run
+      // Remove current run
       if (!runToRemove.childNodes || !runToRemove.childNodes.length) {
         xml.modify.remove(runToRemove);
       }
     }
 
-    // set the text content
+    // Set the text content
     const firstXmlTextNode = xml.query.lastTextChild(firstWordTextNode);
     firstXmlTextNode.textContent = totalText.join('');
   }
@@ -3325,28 +3366,29 @@ class LoopParagraphStrategy {
     return true;
   }
   splitBefore(openTag, closeTag) {
-    // gather some info
+    // Gather some info
     let firstParagraph = officeMarkup.query.containingParagraphNode(openTag.xmlTextNode);
     let lastParagraph = officeMarkup.query.containingParagraphNode(closeTag.xmlTextNode);
     const areSame = firstParagraph === lastParagraph;
 
-    // split first paragraph
-    let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, true);
+    // Split first paragraph
+    const removeTextNode = true;
+    let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, removeTextNode);
     firstParagraph = splitResult[0];
     let afterFirstParagraph = splitResult[1];
     if (areSame) lastParagraph = afterFirstParagraph;
 
-    // split last paragraph
-    splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, true);
+    // Split last paragraph
+    splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, removeTextNode);
     const beforeLastParagraph = splitResult[0];
     lastParagraph = splitResult[1];
     if (areSame) afterFirstParagraph = beforeLastParagraph;
 
-    // disconnect splitted paragraph from their parents
+    // Disconnect splitted paragraph from their parents
     xml.modify.remove(afterFirstParagraph);
     if (!areSame) xml.modify.remove(beforeLastParagraph);
 
-    // extract all paragraphs in between
+    // Extract all paragraphs in between
     let middleParagraphs;
     if (areSame) {
       middleParagraphs = [afterFirstParagraph];
@@ -3363,20 +3405,20 @@ class LoopParagraphStrategy {
   mergeBack(middleParagraphs, firstParagraph, lastParagraph) {
     let mergeTo = firstParagraph;
     for (const curParagraphsGroup of middleParagraphs) {
-      // merge first paragraphs
+      // Merge first paragraphs
       officeMarkup.modify.joinParagraphs(mergeTo, curParagraphsGroup[0]);
 
-      // add middle and last paragraphs to the original document
+      // Add middle and last paragraphs to the original document
       for (let i = 1; i < curParagraphsGroup.length; i++) {
         xml.modify.insertBefore(curParagraphsGroup[i], lastParagraph);
         mergeTo = curParagraphsGroup[i];
       }
     }
 
-    // merge last paragraph
+    // Merge last paragraph
     officeMarkup.modify.joinParagraphs(mergeTo, lastParagraph);
 
-    // remove the old last paragraph (was merged into the new one)
+    // Remove the old last paragraph (was merged into the new one)
     xml.modify.remove(lastParagraph);
   }
 }
@@ -3609,7 +3651,7 @@ class LoopPlugin extends TemplatePlugin {
       }
     }
 
-    // vars
+    // Vars
     const openTag = tags[0];
     const closeTag = last(tags);
     if (openTag.placement !== TagPlacement.TextNode) {
@@ -3618,28 +3660,34 @@ class LoopPlugin extends TemplatePlugin {
     if (closeTag.placement !== TagPlacement.TextNode) {
       throw new TemplateSyntaxError(`Loop closing tag "${closeTag.rawText}" must be placed in a text node but was placed in ${closeTag.placement}`);
     }
+    if (officeMarkup.query.containingStructuredTagContentNode(openTag.xmlTextNode)) {
+      throw new TemplateSyntaxError(`Loop tag "${openTag.rawText}" cannot be placed inside a content control`);
+    }
+    if (officeMarkup.query.containingStructuredTagContentNode(closeTag.xmlTextNode)) {
+      throw new TemplateSyntaxError(`Loop tag "${closeTag.rawText}" cannot be placed inside a content control`);
+    }
 
-    // select the suitable strategy
+    // Select the suitable strategy
     const loopStrategy = this.loopStrategies.find(strategy => strategy.isApplicable(openTag, closeTag, isCondition));
     if (!loopStrategy) throw new Error(`No loop strategy found for tag '${openTag.rawText}'.`);
 
-    // prepare to loop
+    // Prepare to loop
     const {
       firstNode,
       nodesToRepeat,
       lastNode
     } = loopStrategy.splitBefore(openTag, closeTag);
 
-    // repeat (loop) the content
+    // Repeat (loop) the content
     const repeatedNodes = this.repeat(nodesToRepeat, value.length);
 
-    // recursive compilation
+    // Recursive compilation
     // (this step can be optimized in the future if we'll keep track of the
     // path to each token and use that to create new tokens instead of
     // search through the text again)
     const compiledNodes = await this.compile(isCondition, repeatedNodes, data, context);
 
-    // merge back to the document
+    // Merge back to the document
     loopStrategy.mergeBack(compiledNodes, firstNode, lastNode);
   }
   repeat(nodes, times) {
@@ -3654,19 +3702,19 @@ class LoopPlugin extends TemplatePlugin {
   async compile(isCondition, nodeGroups, data, context) {
     const compiledNodeGroups = [];
 
-    // compile each node group with it's relevant data
+    // Compile each node group with it's relevant data
     for (let i = 0; i < nodeGroups.length; i++) {
-      // create dummy root node
+      // Create dummy root node
       const curNodes = nodeGroups[i];
       const dummyRootNode = xml.create.generalNode('dummyRootNode');
       curNodes.forEach(node => xml.modify.appendChild(dummyRootNode, node));
 
-      // compile the new root
+      // Compile the new root
       const conditionTag = this.updatePathBefore(isCondition, data, i);
       await this.utilities.compiler.compile(dummyRootNode, data, context);
       this.updatePathAfter(isCondition, data, conditionTag);
 
-      // disconnect from dummy root
+      // Disconnect from dummy root
       const curResult = [];
       while (dummyRootNode.childNodes && dummyRootNode.childNodes.length) {
         const child = xml.modify.removeChild(dummyRootNode, 0);
@@ -3677,7 +3725,7 @@ class LoopPlugin extends TemplatePlugin {
     return compiledNodeGroups;
   }
   updatePathBefore(isCondition, data, groupIndex) {
-    // if it's a condition - don't go deeper in the path
+    // If it's a condition - don't go deeper in the path
     // (so we need to extract the already pushed condition tag)
     if (isCondition) {
       if (groupIndex > 0) {
@@ -3687,12 +3735,12 @@ class LoopPlugin extends TemplatePlugin {
       return data.pathPop();
     }
 
-    // else, it's an array - push the current index
+    // Else, it's an array - push the current index
     data.pathPush(groupIndex);
     return null;
   }
   updatePathAfter(isCondition, data, conditionTag) {
-    // reverse the "before" path operation
+    // Reverse the "before" path operation
     if (isCondition) {
       data.pathPush(conditionTag);
     } else {
@@ -5188,7 +5236,7 @@ class TemplateHandler {
   /**
    * Version number of the `easy-template-x` library.
    */
-  version = "7.0.2" ;
+  version = "7.0.3" ;
   constructor(options) {
     this.options = new TemplateHandlerOptions(options);
     const delimiters = this.options.delimiters;

package/dist/es/easy-template-x.mjs

@@ -1766,6 +1766,26 @@ class W {
   TableCell = 'w:tc';
   Drawing = 'w:drawing';
   NumberProperties = 'w:numPr';
+  /**
+   * Structured document tag (content control).
+   * 
+   * See: ECMA-376, Part 1, sections 17.5 and 17.5.2
+   */
+  StructuredTag = 'w:sdt';
+  /**
+   * Structured document tag properties.
+   */
+  StructuredTagProperties = 'w:sdtPr';
+  /**
+   * Structured document tag content.
+   */
+  StructuredTagContent = 'w:sdtContent';
+  /**
+   * Complex field character (legacy form field).
+   * 
+   * see: http://officeopenxml.com/WPfields.php
+   */
+  FieldChar = 'w:fldChar';
 }
 
 /**
@@ -1851,6 +1871,9 @@ class Pic {
  * used in Office Open XML documents. Including but not limited to
  * Wordprocessing Markup Language, Drawing Markup Language and Spreadsheet
  * Markup Language.
+ * 
+ * - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+ * - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
  */
 class OmlNode {
   /**
@@ -1875,6 +1898,12 @@ class OmlNode {
 }
 class OmlAttribute {
   static SpacePreserve = 'xml:space';
+  /**
+   * Complex field character type.
+   * 
+   * see: http://officeopenxml.com/WPfields.php
+   */
+  static FieldCharType = 'w:fldCharType';
 }
 
 //
@@ -1895,7 +1924,8 @@ class OmlAttribute {
 //   </w:r>
 // </w:p>
 //
-// see: http://officeopenxml.com/WPcontentOverview.php
+// - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+// - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
 //
 
 /**
@@ -2010,6 +2040,13 @@ class Query {
     return xml.query.findParentByName(node, OmlNode.W.Table);
   }
 
+  /**
+   * Search **upwards** for the first `w:sdtContent` node.
+   */
+  containingStructuredTagContentNode(node) {
+    return xml.query.findParentByName(node, OmlNode.W.StructuredTagContent);
+  }
+
   //
   // Advanced queries
   //
@@ -2049,29 +2086,29 @@ class Modify {
     let firstXmlTextNode;
     let secondXmlTextNode;
 
-    // split nodes
+    // Split nodes
     const wordTextNode = officeMarkup.query.containingTextNode(textNode);
     const newWordTextNode = xml.create.cloneNode(wordTextNode, true);
 
-    // set space preserve to prevent display differences after splitting
+    // Set space preserve to prevent display differences after splitting
     // (otherwise if there was a space in the middle of the text node and it
     // is now at the beginning or end of the text node it will be ignored)
     officeMarkup.modify.setSpacePreserveAttribute(wordTextNode);
     officeMarkup.modify.setSpacePreserveAttribute(newWordTextNode);
     if (addBefore) {
-      // insert new node before existing one
+      // Insert new node before existing one
       xml.modify.insertBefore(newWordTextNode, wordTextNode);
       firstXmlTextNode = xml.query.lastTextChild(newWordTextNode);
       secondXmlTextNode = textNode;
     } else {
-      // insert new node after existing one
+      // Insert new node after existing one
       const curIndex = wordTextNode.parentNode.childNodes.indexOf(wordTextNode);
       xml.modify.insertChild(wordTextNode.parentNode, newWordTextNode, curIndex + 1);
       firstXmlTextNode = textNode;
       secondXmlTextNode = xml.query.lastTextChild(newWordTextNode);
     }
 
-    // edit text
+    // Edit text
     const firstText = firstXmlTextNode.textContent;
     const secondText = secondXmlTextNode.textContent;
     firstXmlTextNode.textContent = firstText.substring(0, splitIndex);
@@ -2086,25 +2123,27 @@ class Modify {
    * `false` then the original text node is the first text node of `right`.
    */
   splitParagraphByTextNode(paragraph, textNode, removeTextNode) {
-    // input validation
+    // Input validation
     const containingParagraph = officeMarkup.query.containingParagraphNode(textNode);
-    if (containingParagraph != paragraph) throw new Error(`Node 'textNode' is not a contained in the specified paragraph.`);
+    if (containingParagraph != paragraph) throw new Error(`Node 'textNode' is not contained in the specified paragraph.`);
     const runNode = officeMarkup.query.containingRunNode(textNode);
     const wordTextNode = officeMarkup.query.containingTextNode(textNode);
 
-    // create run clone
+    // 1. Split the run
+
+    // Create run clone (left) and keep the original run (right).
     const leftRun = xml.create.cloneNode(runNode, false);
     const rightRun = runNode;
     xml.modify.insertBefore(leftRun, rightRun);
 
-    // copy props from original run node (preserve style)
+    // Copy props from original run node (preserve style)
     const runProps = rightRun.childNodes.find(node => officeMarkup.query.isRunPropertiesNode(node));
     if (runProps) {
       const leftRunProps = xml.create.cloneNode(runProps, true);
       xml.modify.appendChild(leftRun, leftRunProps);
     }
 
-    // move nodes from 'right' to 'left'
+    // Move all text nodes up to the specified text node, to the new run.
     const firstRunChildIndex = runProps ? 1 : 0;
     let curChild = rightRun.childNodes[firstRunChildIndex];
     while (curChild != wordTextNode) {
@@ -2113,24 +2152,26 @@ class Modify {
       curChild = rightRun.childNodes[firstRunChildIndex];
     }
 
-    // remove text node
+    // Remove text node
     if (removeTextNode) {
       xml.modify.removeChild(rightRun, firstRunChildIndex);
     }
 
-    // create paragraph clone
+    // 2. Split the paragraph
+
+    // Create paragraph clone (left) and keep the original paragraph (right).
     const leftPara = xml.create.cloneNode(containingParagraph, false);
     const rightPara = containingParagraph;
     xml.modify.insertBefore(leftPara, rightPara);
 
-    // copy props from original paragraph (preserve style)
+    // Copy props from original paragraph (preserve style)
     const paragraphProps = rightPara.childNodes.find(node => officeMarkup.query.isParagraphPropertiesNode(node));
     if (paragraphProps) {
       const leftParagraphProps = xml.create.cloneNode(paragraphProps, true);
       xml.modify.appendChild(leftPara, leftParagraphProps);
     }
 
-    // move nodes from 'right' to 'left'
+    // Move all run nodes up to the original run (right), to the new paragraph (left).
     const firstParaChildIndex = paragraphProps ? 1 : 0;
     curChild = rightPara.childNodes[firstParaChildIndex];
     while (curChild != rightRun) {
@@ -2139,7 +2180,7 @@ class Modify {
       curChild = rightPara.childNodes[firstParaChildIndex];
     }
 
-    // clean paragraphs - remove empty runs
+    // Clean paragraphs - remove empty runs
     if (officeMarkup.query.isEmptyRun(leftRun)) xml.modify.remove(leftRun);
     if (officeMarkup.query.isEmptyRun(rightRun)) xml.modify.remove(rightRun);
     return [leftPara, rightPara];
@@ -2149,21 +2190,21 @@ class Modify {
    * Move all text between the 'from' and 'to' nodes to the 'from' node.
    */
   joinTextNodesRange(from, to) {
-    // find run nodes
+    // Find run nodes
     const firstRunNode = officeMarkup.query.containingRunNode(from);
     const secondRunNode = officeMarkup.query.containingRunNode(to);
     const paragraphNode = firstRunNode.parentNode;
     if (secondRunNode.parentNode !== paragraphNode) throw new Error('Can not join text nodes from separate paragraphs.');
 
-    // find "word text nodes"
+    // Find "word text nodes"
     const firstWordTextNode = officeMarkup.query.containingTextNode(from);
     const secondWordTextNode = officeMarkup.query.containingTextNode(to);
     const totalText = [];
 
-    // iterate runs
+    // Iterate runs
     let curRunNode = firstRunNode;
     while (curRunNode) {
-      // iterate text nodes
+      // Iterate text nodes
       let curWordTextNode;
       if (curRunNode === firstRunNode) {
         curWordTextNode = firstWordTextNode;
@@ -2176,11 +2217,11 @@ class Modify {
           continue;
         }
 
-        // move text to first node
+        // Move text to first node
         const curXmlTextNode = xml.query.lastTextChild(curWordTextNode);
         totalText.push(curXmlTextNode.textContent);
 
-        // next text node
+        // Next text node
         const textToRemove = curWordTextNode;
         if (curWordTextNode === secondWordTextNode) {
           curWordTextNode = null;
@@ -2188,13 +2229,13 @@ class Modify {
           curWordTextNode = curWordTextNode.nextSibling;
         }
 
-        // remove current text node
+        // Remove current text node
         if (textToRemove !== firstWordTextNode) {
           xml.modify.remove(textToRemove);
         }
       }
 
-      // next run
+      // Next run
       const runToRemove = curRunNode;
       if (curRunNode === secondRunNode) {
         curRunNode = null;
@@ -2202,13 +2243,13 @@ class Modify {
         curRunNode = curRunNode.nextSibling;
       }
 
-      // remove current run
+      // Remove current run
       if (!runToRemove.childNodes || !runToRemove.childNodes.length) {
         xml.modify.remove(runToRemove);
       }
     }
 
-    // set the text content
+    // Set the text content
     const firstXmlTextNode = xml.query.lastTextChild(firstWordTextNode);
     firstXmlTextNode.textContent = totalText.join('');
   }
@@ -3323,28 +3364,29 @@ class LoopParagraphStrategy {
     return true;
   }
   splitBefore(openTag, closeTag) {
-    // gather some info
+    // Gather some info
     let firstParagraph = officeMarkup.query.containingParagraphNode(openTag.xmlTextNode);
     let lastParagraph = officeMarkup.query.containingParagraphNode(closeTag.xmlTextNode);
     const areSame = firstParagraph === lastParagraph;
 
-    // split first paragraph
-    let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, true);
+    // Split first paragraph
+    const removeTextNode = true;
+    let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, removeTextNode);
     firstParagraph = splitResult[0];
     let afterFirstParagraph = splitResult[1];
     if (areSame) lastParagraph = afterFirstParagraph;
 
-    // split last paragraph
-    splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, true);
+    // Split last paragraph
+    splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, removeTextNode);
     const beforeLastParagraph = splitResult[0];
     lastParagraph = splitResult[1];
     if (areSame) afterFirstParagraph = beforeLastParagraph;
 
-    // disconnect splitted paragraph from their parents
+    // Disconnect splitted paragraph from their parents
     xml.modify.remove(afterFirstParagraph);
     if (!areSame) xml.modify.remove(beforeLastParagraph);
 
-    // extract all paragraphs in between
+    // Extract all paragraphs in between
     let middleParagraphs;
     if (areSame) {
       middleParagraphs = [afterFirstParagraph];
@@ -3361,20 +3403,20 @@ class LoopParagraphStrategy {
   mergeBack(middleParagraphs, firstParagraph, lastParagraph) {
     let mergeTo = firstParagraph;
     for (const curParagraphsGroup of middleParagraphs) {
-      // merge first paragraphs
+      // Merge first paragraphs
       officeMarkup.modify.joinParagraphs(mergeTo, curParagraphsGroup[0]);
 
-      // add middle and last paragraphs to the original document
+      // Add middle and last paragraphs to the original document
       for (let i = 1; i < curParagraphsGroup.length; i++) {
         xml.modify.insertBefore(curParagraphsGroup[i], lastParagraph);
         mergeTo = curParagraphsGroup[i];
       }
     }
 
-    // merge last paragraph
+    // Merge last paragraph
     officeMarkup.modify.joinParagraphs(mergeTo, lastParagraph);
 
-    // remove the old last paragraph (was merged into the new one)
+    // Remove the old last paragraph (was merged into the new one)
     xml.modify.remove(lastParagraph);
   }
 }
@@ -3607,7 +3649,7 @@ class LoopPlugin extends TemplatePlugin {
       }
     }
 
-    // vars
+    // Vars
     const openTag = tags[0];
     const closeTag = last(tags);
     if (openTag.placement !== TagPlacement.TextNode) {
@@ -3616,28 +3658,34 @@ class LoopPlugin extends TemplatePlugin {
     if (closeTag.placement !== TagPlacement.TextNode) {
       throw new TemplateSyntaxError(`Loop closing tag "${closeTag.rawText}" must be placed in a text node but was placed in ${closeTag.placement}`);
     }
+    if (officeMarkup.query.containingStructuredTagContentNode(openTag.xmlTextNode)) {
+      throw new TemplateSyntaxError(`Loop tag "${openTag.rawText}" cannot be placed inside a content control`);
+    }
+    if (officeMarkup.query.containingStructuredTagContentNode(closeTag.xmlTextNode)) {
+      throw new TemplateSyntaxError(`Loop tag "${closeTag.rawText}" cannot be placed inside a content control`);
+    }
 
-    // select the suitable strategy
+    // Select the suitable strategy
     const loopStrategy = this.loopStrategies.find(strategy => strategy.isApplicable(openTag, closeTag, isCondition));
     if (!loopStrategy) throw new Error(`No loop strategy found for tag '${openTag.rawText}'.`);
 
-    // prepare to loop
+    // Prepare to loop
     const {
       firstNode,
       nodesToRepeat,
       lastNode
     } = loopStrategy.splitBefore(openTag, closeTag);
 
-    // repeat (loop) the content
+    // Repeat (loop) the content
     const repeatedNodes = this.repeat(nodesToRepeat, value.length);
 
-    // recursive compilation
+    // Recursive compilation
     // (this step can be optimized in the future if we'll keep track of the
     // path to each token and use that to create new tokens instead of
     // search through the text again)
     const compiledNodes = await this.compile(isCondition, repeatedNodes, data, context);
 
-    // merge back to the document
+    // Merge back to the document
     loopStrategy.mergeBack(compiledNodes, firstNode, lastNode);
   }
   repeat(nodes, times) {
@@ -3652,19 +3700,19 @@ class LoopPlugin extends TemplatePlugin {
   async compile(isCondition, nodeGroups, data, context) {
     const compiledNodeGroups = [];
 
-    // compile each node group with it's relevant data
+    // Compile each node group with it's relevant data
     for (let i = 0; i < nodeGroups.length; i++) {
-      // create dummy root node
+      // Create dummy root node
       const curNodes = nodeGroups[i];
       const dummyRootNode = xml.create.generalNode('dummyRootNode');
       curNodes.forEach(node => xml.modify.appendChild(dummyRootNode, node));
 
-      // compile the new root
+      // Compile the new root
       const conditionTag = this.updatePathBefore(isCondition, data, i);
       await this.utilities.compiler.compile(dummyRootNode, data, context);
       this.updatePathAfter(isCondition, data, conditionTag);
 
-      // disconnect from dummy root
+      // Disconnect from dummy root
       const curResult = [];
       while (dummyRootNode.childNodes && dummyRootNode.childNodes.length) {
         const child = xml.modify.removeChild(dummyRootNode, 0);
@@ -3675,7 +3723,7 @@ class LoopPlugin extends TemplatePlugin {
     return compiledNodeGroups;
   }
   updatePathBefore(isCondition, data, groupIndex) {
-    // if it's a condition - don't go deeper in the path
+    // If it's a condition - don't go deeper in the path
     // (so we need to extract the already pushed condition tag)
     if (isCondition) {
       if (groupIndex > 0) {
@@ -3685,12 +3733,12 @@ class LoopPlugin extends TemplatePlugin {
       return data.pathPop();
     }
 
-    // else, it's an array - push the current index
+    // Else, it's an array - push the current index
     data.pathPush(groupIndex);
     return null;
   }
   updatePathAfter(isCondition, data, conditionTag) {
-    // reverse the "before" path operation
+    // Reverse the "before" path operation
     if (isCondition) {
       data.pathPush(conditionTag);
     } else {
@@ -5186,7 +5234,7 @@ class TemplateHandler {
   /**
    * Version number of the `easy-template-x` library.
    */
-  version = "7.0.2" ;
+  version = "7.0.3" ;
   constructor(options) {
     this.options = new TemplateHandlerOptions(options);
     const delimiters = this.options.delimiters;

package/dist/types/office/officeMarkup.d.ts

@@ -21,6 +21,7 @@ declare class Query {
     containingTableRowNode(node: XmlNode): XmlGeneralNode;
     containingTableCellNode(node: XmlNode): XmlGeneralNode;
     containingTableNode(node: XmlNode): XmlGeneralNode;
+    containingStructuredTagContentNode(node: XmlNode): XmlGeneralNode;
     isEmptyTextNode(node: XmlNode): boolean;
     isEmptyRun(node: XmlNode): boolean;
 }

package/dist/types/office/omlNode.d.ts

@@ -9,6 +9,10 @@ declare class W {
     readonly TableCell = "w:tc";
     readonly Drawing = "w:drawing";
     readonly NumberProperties = "w:numPr";
+    readonly StructuredTag = "w:sdt";
+    readonly StructuredTagProperties = "w:sdtPr";
+    readonly StructuredTagContent = "w:sdtContent";
+    readonly FieldChar = "w:fldChar";
 }
 declare class A {
     readonly Paragraph = "a:p";
@@ -44,5 +48,6 @@ export declare class OmlNode {
 }
 export declare class OmlAttribute {
     static readonly SpacePreserve = "xml:space";
+    static readonly FieldCharType = "w:fldCharType";
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-template-x",
-  "version": "7.0.2",
+  "version": "7.0.3",
   "description": "Generate docx documents from templates, in Node or in the browser.",
   "keywords": [
     "docx",

package/src/office/officeMarkup.ts

@@ -20,7 +20,8 @@ import { OmlAttribute, OmlNode } from "./omlNode";
 //   </w:r>
 // </w:p>
 //
-// see: http://officeopenxml.com/WPcontentOverview.php
+// - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+// - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
 //
 
 /**
@@ -161,6 +162,13 @@ class Query {
         return xml.query.findParentByName(node, OmlNode.W.Table);
     }
 
+    /**
+     * Search **upwards** for the first `w:sdtContent` node.
+     */
+    public containingStructuredTagContentNode(node: XmlNode): XmlGeneralNode {
+        return xml.query.findParentByName(node, OmlNode.W.StructuredTagContent);
+    }
+
     //
     // Advanced queries
     //
@@ -219,11 +227,11 @@ class Modify {
         let firstXmlTextNode: XmlTextNode;
         let secondXmlTextNode: XmlTextNode;
 
-        // split nodes
+        // Split nodes
         const wordTextNode = officeMarkup.query.containingTextNode(textNode);
         const newWordTextNode = xml.create.cloneNode(wordTextNode, true);
 
-        // set space preserve to prevent display differences after splitting
+        // Set space preserve to prevent display differences after splitting
         // (otherwise if there was a space in the middle of the text node and it
         // is now at the beginning or end of the text node it will be ignored)
         officeMarkup.modify.setSpacePreserveAttribute(wordTextNode);
@@ -231,7 +239,7 @@ class Modify {
 
         if (addBefore) {
 
-            // insert new node before existing one
+            // Insert new node before existing one
             xml.modify.insertBefore(newWordTextNode, wordTextNode);
 
             firstXmlTextNode = xml.query.lastTextChild(newWordTextNode);
@@ -239,7 +247,7 @@ class Modify {
 
         } else {
 
-            // insert new node after existing one
+            // Insert new node after existing one
             const curIndex = wordTextNode.parentNode.childNodes.indexOf(wordTextNode);
             xml.modify.insertChild(wordTextNode.parentNode, newWordTextNode, curIndex + 1);
 
@@ -247,7 +255,7 @@ class Modify {
             secondXmlTextNode = xml.query.lastTextChild(newWordTextNode);
         }
 
-        // edit text
+        // Edit text
         const firstText = firstXmlTextNode.textContent;
         const secondText = secondXmlTextNode.textContent;
         firstXmlTextNode.textContent = firstText.substring(0, splitIndex);
@@ -264,27 +272,29 @@ class Modify {
      */
     public splitParagraphByTextNode(paragraph: XmlNode, textNode: XmlTextNode, removeTextNode: boolean): [XmlNode, XmlNode] {
 
-        // input validation
+        // Input validation
         const containingParagraph = officeMarkup.query.containingParagraphNode(textNode);
         if (containingParagraph != paragraph)
-            throw new Error(`Node 'textNode' is not a contained in the specified paragraph.`);
+            throw new Error(`Node 'textNode' is not contained in the specified paragraph.`);
 
         const runNode = officeMarkup.query.containingRunNode(textNode);
         const wordTextNode = officeMarkup.query.containingTextNode(textNode);
 
-        // create run clone
+        // 1. Split the run
+
+        // Create run clone (left) and keep the original run (right).
         const leftRun = xml.create.cloneNode(runNode, false);
         const rightRun = runNode;
         xml.modify.insertBefore(leftRun, rightRun);
 
-        // copy props from original run node (preserve style)
+        // Copy props from original run node (preserve style)
         const runProps = rightRun.childNodes.find(node => officeMarkup.query.isRunPropertiesNode(node));
         if (runProps) {
             const leftRunProps = xml.create.cloneNode(runProps, true);
             xml.modify.appendChild(leftRun, leftRunProps);
         }
 
-        // move nodes from 'right' to 'left'
+        // Move all text nodes up to the specified text node, to the new run.
         const firstRunChildIndex = (runProps ? 1 : 0);
         let curChild = rightRun.childNodes[firstRunChildIndex];
         while (curChild != wordTextNode) {
@@ -293,24 +303,26 @@ class Modify {
             curChild = rightRun.childNodes[firstRunChildIndex];
         }
 
-        // remove text node
+        // Remove text node
         if (removeTextNode) {
             xml.modify.removeChild(rightRun, firstRunChildIndex);
         }
 
-        // create paragraph clone
+        // 2. Split the paragraph
+
+        // Create paragraph clone (left) and keep the original paragraph (right).
         const leftPara = xml.create.cloneNode(containingParagraph, false);
         const rightPara = containingParagraph;
         xml.modify.insertBefore(leftPara, rightPara);
 
-        // copy props from original paragraph (preserve style)
+        // Copy props from original paragraph (preserve style)
         const paragraphProps = rightPara.childNodes.find(node => officeMarkup.query.isParagraphPropertiesNode(node));
         if (paragraphProps) {
             const leftParagraphProps = xml.create.cloneNode(paragraphProps, true);
             xml.modify.appendChild(leftPara, leftParagraphProps);
         }
 
-        // move nodes from 'right' to 'left'
+        // Move all run nodes up to the original run (right), to the new paragraph (left).
         const firstParaChildIndex = (paragraphProps ? 1 : 0);
         curChild = rightPara.childNodes[firstParaChildIndex];
         while (curChild != rightRun) {
@@ -319,7 +331,7 @@ class Modify {
             curChild = rightPara.childNodes[firstParaChildIndex];
         }
 
-        // clean paragraphs - remove empty runs
+        // Clean paragraphs - remove empty runs
         if (officeMarkup.query.isEmptyRun(leftRun))
             xml.modify.remove(leftRun);
         if (officeMarkup.query.isEmptyRun(rightRun))
@@ -333,7 +345,7 @@ class Modify {
      */
     public joinTextNodesRange(from: XmlTextNode, to: XmlTextNode): void {
 
-        // find run nodes
+        // Find run nodes
         const firstRunNode = officeMarkup.query.containingRunNode(from);
         const secondRunNode = officeMarkup.query.containingRunNode(to);
 
@@ -341,16 +353,16 @@ class Modify {
         if (secondRunNode.parentNode !== paragraphNode)
             throw new Error('Can not join text nodes from separate paragraphs.');
 
-        // find "word text nodes"
+        // Find "word text nodes"
         const firstWordTextNode = officeMarkup.query.containingTextNode(from);
         const secondWordTextNode = officeMarkup.query.containingTextNode(to);
         const totalText: string[] = [];
 
-        // iterate runs
+        // Iterate runs
         let curRunNode: XmlNode = firstRunNode;
         while (curRunNode) {
 
-            // iterate text nodes
+            // Iterate text nodes
             let curWordTextNode: XmlNode;
             if (curRunNode === firstRunNode) {
                 curWordTextNode = firstWordTextNode;
@@ -364,11 +376,11 @@ class Modify {
                     continue;
                 }
 
-                // move text to first node
+                // Move text to first node
                 const curXmlTextNode = xml.query.lastTextChild(curWordTextNode);
                 totalText.push(curXmlTextNode.textContent);
 
-                // next text node
+                // Next text node
                 const textToRemove = curWordTextNode;
                 if (curWordTextNode === secondWordTextNode) {
                     curWordTextNode = null;
@@ -376,13 +388,13 @@ class Modify {
                     curWordTextNode = curWordTextNode.nextSibling;
                 }
 
-                // remove current text node
+                // Remove current text node
                 if (textToRemove !== firstWordTextNode) {
                     xml.modify.remove(textToRemove);
                 }
             }
 
-            // next run
+            // Next run
             const runToRemove = curRunNode;
             if (curRunNode === secondRunNode) {
                 curRunNode = null;
@@ -390,13 +402,13 @@ class Modify {
                 curRunNode = curRunNode.nextSibling;
             }
 
-            // remove current run
+            // Remove current run
             if (!runToRemove.childNodes || !runToRemove.childNodes.length) {
                 xml.modify.remove(runToRemove);
             }
         }
 
-        // set the text content
+        // Set the text content
         const firstXmlTextNode = xml.query.lastTextChild(firstWordTextNode);
         firstXmlTextNode.textContent = totalText.join('');
     }

package/src/office/omlNode.ts

@@ -13,6 +13,26 @@ class W {
     public readonly TableCell = 'w:tc';
     public readonly Drawing = 'w:drawing';
     public readonly NumberProperties = 'w:numPr';
+    /**
+     * Structured document tag (content control).
+     * 
+     * See: ECMA-376, Part 1, sections 17.5 and 17.5.2
+     */
+    public readonly StructuredTag = 'w:sdt';
+    /**
+     * Structured document tag properties.
+     */
+    public readonly StructuredTagProperties = 'w:sdtPr';
+    /**
+     * Structured document tag content.
+     */
+    public readonly StructuredTagContent = 'w:sdtContent';
+    /**
+     * Complex field character (legacy form field).
+     * 
+     * see: http://officeopenxml.com/WPfields.php
+     */
+    public readonly FieldChar = 'w:fldChar';
 }
 
 /**
@@ -98,6 +118,9 @@ class Pic {
  * used in Office Open XML documents. Including but not limited to
  * Wordprocessing Markup Language, Drawing Markup Language and Spreadsheet
  * Markup Language.
+ * 
+ * - For an easy introduction, see: http://officeopenxml.com/WPcontentOverview.php
+ * - For the complete specification, see: https://ecma-international.org/publications-and-standards/standards/ecma-376/
  */
 export class OmlNode {
 
@@ -124,4 +147,10 @@ export class OmlNode {
 
 export class OmlAttribute {
     public static readonly SpacePreserve = 'xml:space';
+    /**
+     * Complex field character type.
+     * 
+     * see: http://officeopenxml.com/WPfields.php
+     */
+    public static readonly FieldCharType = 'w:fldCharType';
 }

package/src/plugins/loop/loopPlugin.ts

@@ -2,6 +2,7 @@ import { PathPart, ScopeData } from "src/compilation/scopeData";
 import { Tag, TagPlacement } from "src/compilation/tag";
 import { TemplateContext } from "src/compilation/templateContext";
 import { TemplateSyntaxError } from "src/errors";
+import { officeMarkup } from "src/office/officeMarkup";
 import { PluginUtilities, TemplatePlugin } from "src/plugins/templatePlugin";
 import { TemplateData } from "src/templateData";
 import { last } from "src/utils";
@@ -39,7 +40,7 @@ export class LoopPlugin extends TemplatePlugin {
             }
         }
 
-        // vars
+        // Vars
         const openTag = tags[0];
         const closeTag = last(tags);
 
@@ -49,25 +50,31 @@ export class LoopPlugin extends TemplatePlugin {
         if (closeTag.placement !== TagPlacement.TextNode) {
             throw new TemplateSyntaxError(`Loop closing tag "${closeTag.rawText}" must be placed in a text node but was placed in ${closeTag.placement}`);
         }
+        if (officeMarkup.query.containingStructuredTagContentNode(openTag.xmlTextNode)) {
+            throw new TemplateSyntaxError(`Loop tag "${openTag.rawText}" cannot be placed inside a content control`);
+        }
+        if (officeMarkup.query.containingStructuredTagContentNode(closeTag.xmlTextNode)) {
+            throw new TemplateSyntaxError(`Loop tag "${closeTag.rawText}" cannot be placed inside a content control`);
+        }
 
-        // select the suitable strategy
+        // Select the suitable strategy
         const loopStrategy = this.loopStrategies.find(strategy => strategy.isApplicable(openTag, closeTag, isCondition));
         if (!loopStrategy)
             throw new Error(`No loop strategy found for tag '${openTag.rawText}'.`);
 
-        // prepare to loop
+        // Prepare to loop
         const { firstNode, nodesToRepeat, lastNode } = loopStrategy.splitBefore(openTag, closeTag);
 
-        // repeat (loop) the content
+        // Repeat (loop) the content
         const repeatedNodes = this.repeat(nodesToRepeat, value.length);
 
-        // recursive compilation
+        // Recursive compilation
         // (this step can be optimized in the future if we'll keep track of the
         // path to each token and use that to create new tokens instead of
         // search through the text again)
         const compiledNodes = await this.compile(isCondition, repeatedNodes, data, context);
 
-        // merge back to the document
+        // Merge back to the document
         loopStrategy.mergeBack(compiledNodes, firstNode, lastNode);
     }
 
@@ -88,20 +95,20 @@ export class LoopPlugin extends TemplatePlugin {
     private async compile(isCondition: boolean, nodeGroups: XmlNode[][], data: ScopeData, context: TemplateContext): Promise<XmlNode[][]> {
         const compiledNodeGroups: XmlNode[][] = [];
 
-        // compile each node group with it's relevant data
+        // Compile each node group with it's relevant data
         for (let i = 0; i < nodeGroups.length; i++) {
 
-            // create dummy root node
+            // Create dummy root node
             const curNodes = nodeGroups[i];
             const dummyRootNode = xml.create.generalNode('dummyRootNode');
             curNodes.forEach(node => xml.modify.appendChild(dummyRootNode, node));
 
-            // compile the new root
+            // Compile the new root
             const conditionTag = this.updatePathBefore(isCondition, data, i);
             await this.utilities.compiler.compile(dummyRootNode, data, context);
             this.updatePathAfter(isCondition, data, conditionTag);
 
-            // disconnect from dummy root
+            // Disconnect from dummy root
             const curResult: XmlNode[] = [];
             while (dummyRootNode.childNodes && dummyRootNode.childNodes.length) {
                 const child = xml.modify.removeChild(dummyRootNode, 0);
@@ -115,7 +122,7 @@ export class LoopPlugin extends TemplatePlugin {
 
     private updatePathBefore(isCondition: boolean, data: ScopeData, groupIndex: number): PathPart {
 
-        // if it's a condition - don't go deeper in the path
+        // If it's a condition - don't go deeper in the path
         // (so we need to extract the already pushed condition tag)
         if (isCondition) {
             if (groupIndex > 0) {
@@ -125,14 +132,14 @@ export class LoopPlugin extends TemplatePlugin {
             return data.pathPop();
         }
 
-        // else, it's an array - push the current index
+        // Else, it's an array - push the current index
         data.pathPush(groupIndex);
         return null;
     }
 
     private updatePathAfter(isCondition: boolean, data: ScopeData, conditionTag: PathPart): void {
 
-        // reverse the "before" path operation
+        // Reverse the "before" path operation
         if (isCondition) {
             data.pathPush(conditionTag);
         } else {

package/src/plugins/loop/strategy/loopParagraphStrategy.ts

@@ -11,31 +11,32 @@ export class LoopParagraphStrategy implements ILoopStrategy {
 
     public splitBefore(openTag: TextNodeTag, closeTag: TextNodeTag): SplitBeforeResult {
 
-        // gather some info
+        // Gather some info
         let firstParagraph: XmlNode = officeMarkup.query.containingParagraphNode(openTag.xmlTextNode);
         let lastParagraph: XmlNode = officeMarkup.query.containingParagraphNode(closeTag.xmlTextNode);
         const areSame = (firstParagraph === lastParagraph);
 
-        // split first paragraph
-        let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, true);
+        // Split first paragraph
+        const removeTextNode = true;
+        let splitResult = officeMarkup.modify.splitParagraphByTextNode(firstParagraph, openTag.xmlTextNode, removeTextNode);
         firstParagraph = splitResult[0];
         let afterFirstParagraph = splitResult[1];
         if (areSame)
             lastParagraph = afterFirstParagraph;
 
-        // split last paragraph
-        splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, true);
+        // Split last paragraph
+        splitResult = officeMarkup.modify.splitParagraphByTextNode(lastParagraph, closeTag.xmlTextNode, removeTextNode);
         const beforeLastParagraph = splitResult[0];
         lastParagraph = splitResult[1];
         if (areSame)
             afterFirstParagraph = beforeLastParagraph;
 
-        // disconnect splitted paragraph from their parents
+        // Disconnect splitted paragraph from their parents
         xml.modify.remove(afterFirstParagraph);
         if (!areSame)
             xml.modify.remove(beforeLastParagraph);
 
-        // extract all paragraphs in between
+        // Extract all paragraphs in between
         let middleParagraphs: XmlNode[];
         if (areSame) {
             middleParagraphs = [afterFirstParagraph];
@@ -56,20 +57,20 @@ export class LoopParagraphStrategy implements ILoopStrategy {
         let mergeTo = firstParagraph;
         for (const curParagraphsGroup of middleParagraphs) {
 
-            // merge first paragraphs
+            // Merge first paragraphs
             officeMarkup.modify.joinParagraphs(mergeTo, curParagraphsGroup[0]);
 
-            // add middle and last paragraphs to the original document
+            // Add middle and last paragraphs to the original document
             for (let i = 1; i < curParagraphsGroup.length; i++) {
                 xml.modify.insertBefore(curParagraphsGroup[i], lastParagraph);
                 mergeTo = curParagraphsGroup[i];
             }
         }
 
-        // merge last paragraph
+        // Merge last paragraph
         officeMarkup.modify.joinParagraphs(mergeTo, lastParagraph);
 
-        // remove the old last paragraph (was merged into the new one)
+        // Remove the old last paragraph (was merged into the new one)
         xml.modify.remove(lastParagraph);
     }
 }