easy-template-x 6.2.2 → 7.0.0

package/README.md

@@ -32,6 +32,8 @@ Generate docx documents from templates, in Node or in the browser.
     - [Nested Conditions](#nested-conditions)
     - [Controlling loop behavior](#controlling-loop-behavior)
   - [Image plugin](#image-plugin)
+    - [Text tag replacement](#text-tag-replacement)
+    - [Image placeholder replacement](#image-placeholder-replacement)
   - [Link plugin](#link-plugin)
   - [Chart plugin](#chart-plugin)
   - [Raw xml plugin](#raw-xml-plugin)
@@ -331,11 +333,38 @@ And the third will produce this document:
 
 ### Image plugin
 
-Embed images into the document.
+Embed images into the document.  
+The image plugin supports two modes:
 
-Input template:
+1. Text tag replacement
+2. Image placeholder replacement
+
+#### Text tag replacement
+
+Insert inline images by placing tags in the document body.
+
+Input template example:
+
+![input template](./docs/assets/image-plugin-text-in.png?raw=true)
+
+#### Image placeholder replacement
+
+Replace existing placeholder images while preserving their size, position, and styling.
+
+**Note:** You can use any image you want as the placeholder.
+
+Input template example:
+
+![input template](./docs/assets/image-plugin-placeholder-in.png?raw=true)
+
+To let `easy-template-x` know you want to replace the placeholder image, insert a tag in it's alt text:
+
+![alt text context menu](./docs/assets/alt-text-context-menu.png?raw=true)
+![alt text panel](./docs/assets/alt-text-panel.png?raw=true)
+
+#### Data and output
 
-![input template](./docs/assets/image-plugin-in.png?raw=true)
+The data and resulting output are the same for both modes.
 
 Input data:
 
@@ -345,8 +374,8 @@ Input data:
         _type: "image",
         source: fs.readFileSync("hero.png"),
         format: MimeType.Png,
-        width: 200,
-        height: 200,
+        width: 200, // Required for text tags, optional for placeholders
+        height: 200, // Required for text tags, optional for placeholders
         altText: "Kung Fu Hero", // Optional
         transparencyPercent: 80 // Optional
     }
@@ -635,7 +664,7 @@ export class RawXmlPlugin extends TemplatePlugin {
         }
 
         // Remove the placeholder tag.
-        officeMarkup.modify.removeTag(tag.xmlTextNode);
+        officeMarkup.modify.removeTag(tag);
     }
 }
 ```
@@ -651,7 +680,7 @@ export interface RawXmlContent extends PluginContent {
 
 ## Listing tags
 
-You can get the list of [tags](https://github.com/alonrbar/easy-template-x/blob/8a88535ef090fc357cf3523411bef0d0729d10c8/src/compilation/tag.ts) in a template by calling the `parseTags` method as follows:
+You can get the list of [tags](https://github.com/alonrbar/easy-template-x/blob/master/src/compilation/tag.ts) in a template by calling the `parseTags` method as follows:
 
 ```typescript
 import { TemplateHandler } from 'easy-template-x';