easy-template-x 5.1.0 → 6.0.0

package/README.md

@@ -33,6 +33,7 @@ Generate docx documents from templates, in Node or in the browser.
     - [Controlling loop behavior](#controlling-loop-behavior)
   - [Image plugin](#image-plugin)
   - [Link plugin](#link-plugin)
+  - [Chart plugin](#chart-plugin)
   - [Raw xml plugin](#raw-xml-plugin)
   - [Writing custom plugins](#writing-your-own-plugins)
 - [Listing tags](#listing-tags)
@@ -145,11 +146,12 @@ Checkout this [live demo](https://codesandbox.io/p/sandbox/easy-template-x-demo-
 
 These are the plugins that comes bundled with `easy-template-x`:
 
-- [Simple text replacement plugin.](#text-plugin)
-- [Loop plugin for iterating text, table rows and list rows and for simple conditions.](#loop-plugin)
-- [Image plugin for embedding images.](#image-plugin)
-- [Link plugin for hyperlinks creation.](#link-plugin)
-- [Raw xml plugin for custom xml insertion.](#raw-xml-plugin)
+- [Text plugin](#text-plugin) - For simple text replacement.
+- [Loop plugin](#loop-plugin) - For iterating text, table rows, table columns and list rows and for simple conditions.
+- [Image plugin](#image-plugin) - For embedding images.
+- [Link plugin](#link-plugin) - For hyperlinks creation.
+- [Chart plugin](#chart-plugin) - For handling charts.
+- [Raw xml plugin](#raw-xml-plugin) - For custom xml insertion.
 
 ### Text plugin
 
@@ -282,7 +284,7 @@ The default heuristics are as follows:
 1. If both loop tags are inside the same table cell - the plugin assumes you want to repeat the **cell content**, not the row or column.
 2. If both loop tags are in the same column - the plugin will repeat the **column**.
 3. If both loop tags are inside a table - the plugin will repeat the relevant table **rows**.
-4. If both loop tags are in list - the plugin will repeat the relevant **list items**.
+4. If both loop tags are in a list - the plugin will repeat the relevant **list items**.
 5. Otherwise - the plugin will use a naive approach for repeating the **content** in between the loop tags.
 
 ##### Changing the default
@@ -380,6 +382,192 @@ Output document:
 
 ![output document](./docs/assets/link-plugin-out.png?raw=true)
 
+### Chart plugin
+
+To use charts in templates, put a placeholder chart and place a tag in its title, like so:
+
+![chart placeholder](./docs/assets/chart-placeholder.png?raw=true)
+
+Generally speaking, the charts preserve their original settings and style with
+some configurations also available through the input json data.
+
+`easy-template-x` try to keep the same terminology used by MS Word. Therefore,
+while the exact input data schema depends on the chart type, the main terms
+are common to most:
+
+- **Categories** are the values of the X axis.
+- **Series** are the values of the Y axis.
+
+Take a look at the examples below to get a better understanding of how chart
+tags behave.
+
+#### Line, bar & column charts
+
+Line, bar & column charts all uses the same input data format.
+
+The example below shows 4 charts in the same template: Line chart, Column chart, Bar chart and Stacked Column chart. In this example all of the charts use the same input data (the `MyChart` tag data) but you can of course use a different tag for each chart.
+
+Notice how the end result ignores the placeholder data and matches our input data instead.
+
+Note that you are not limited to use the same number of categories or series as the placeholder chart. This specific example uses less series than the placeholder (2 instead of 3) but you can just as easily add more series or change the number of categories.
+
+Input template:
+
+![input template](./docs/assets/chart-plugin-line-in.png?raw=true)
+
+Input data:
+
+```javascript
+{
+    MyChart: {
+        _type: "chart",
+        title: "Easy Chart", // Optional
+        categories: {
+            names: ["Q1", "Q2", "Q3", "Q4"]
+        },
+        series: [
+            { 
+                name: "Earnings",  // Optional
+                color: "#34d399", // Optional
+                values: [100, 210, 150, 170] 
+            },
+            { 
+                name: "Expenses",
+                color: "#f87171",
+                values: [170, 165, 169, 155] 
+            },
+        ],
+    }
+}
+```
+
+Output document:
+
+![output document](./docs/assets/chart-plugin-line-out.png?raw=true)
+
+#### Pie & doughnut charts
+
+Pie & doughnut uses the same input data format as line, bar and column chart,
+except they expect a single series.
+
+The example below shows 4 charts in the same template: 2 pie charts and 2 doughnut charts, each with a different style.
+
+Input template:
+
+![input template](./docs/assets/chart-plugin-pie-in.png?raw=true)
+
+Input data:
+
+```javascript
+{
+    Chart1: {
+        _type: "chart",
+        title: "Easy Chart", // Optional
+        categories: {
+            names: ["Q1", "Q2", "Q3", "Q4"]
+        },
+        series: [
+            { values: [100, 210, 150, 170] },
+        ],
+    }
+}
+```
+
+Output document:
+
+![output document](./docs/assets/chart-plugin-pie-out.png?raw=true)
+
+#### Scatter chart
+
+Scatter chart do not have a `categories` property. Instead, each of their values requires an `x` and a `y` properties.
+
+Input template:
+
+![input template](./docs/assets/chart-plugin-scatter-in.png?raw=true)
+
+Input data:
+
+```javascript
+{
+    scatter: {
+        _type: "chart",
+        title: "Easy Scatter Chart", // Optional
+        series: [
+            { 
+                name: "Earnings", // Optional
+                color: "#34d399", // Optional
+                values: [
+                    { x: 1, y: 310 },
+                    { x: 3, y: 450 },
+                    { x: 4, y: 200 },
+                    { x: 6, y: 200 },
+                ],
+            },
+            { 
+                name: "Expenses",
+                color: "#f87171",
+                values: [
+                    { x: 1, y: 410 },
+                    { x: 2, y: 450 },
+                    { x: 3, y: 200 },
+                    { x: 5, y: 350 },
+                ],
+            },
+        ],
+    }
+}
+```
+
+Output document:
+
+![output document](./docs/assets/chart-plugin-scatter-out.png?raw=true)
+
+#### Bubble chart
+
+Bubble charts are very similar to scatter charts but they have an additional
+`size` property (notice the placeholder chart should be a bubble chart, not a
+scatter chart).
+
+Input template:
+
+![input template](./docs/assets/chart-plugin-bubble-in.png?raw=true)
+
+Input data:
+
+```javascript
+{
+    bubble: {
+        _type: "chart",
+        title: "Bubble Chart", // Optional
+        series: [
+            { 
+                name: "Earnings", // Optional
+                color: "#34d399", // Optional
+                values: [
+                    { x: 1, y: 10, size: 10 },
+                    { x: 2, y: 10, size: 20 },
+                    { x: 3, y: 8, size: 40 },
+                    { x: 4, y: 8, size: 30 },
+                ],
+            },
+            { 
+                name: "Expenses",
+                color: "#f87171",
+                values: [
+                    { x: 1, y: 4, size: 40 },
+                    { x: 2, y: 4, size: 20 },
+                    { x: 3, y: 3, size: 30 },
+                ],
+            },
+        ],
+    }
+}
+```
+
+Output document:
+
+![output document](./docs/assets/chart-plugin-bubble-out.png?raw=true)
+
 ### Raw xml plugin
 
 Add custom xml into the document to be interpreted by Word.
@@ -419,6 +607,8 @@ _To better understand the internal structure of Word documents check out [this e
 Example plugin implementation ([source](./src/plugins/rawXml/rawXmlPlugin.ts)):
 
 ```typescript
+import { officeMarkup, xml } from "easy-template-x";
+
 /**
  * A plugin that inserts raw xml to the document.
  */
@@ -429,24 +619,23 @@ export class RawXmlPlugin extends TemplatePlugin {
 
     // Plugin logic goes here:
     public simpleTagReplacements(tag: Tag, data: ScopeData): void {
-
-        // Tag.xmlTextNode always reference the actual xml text node.
-        // In MS Word each text node is wrapped by a <w:t> node so we retrieve that.
-        const wordTextNode = this.utilities.docxParser.containingTextNode(tag.xmlTextNode);
-
+        
         // Get the value to use from the input data.
-        const value = data.getScopeData() as RawXmlContent;
+        const value = data.getScopeData<RawXmlContent>();
         if (value && typeof value.xml === 'string') {
 
-            // If it contains a "xml" string property parse it and insert.
-            const newNode = this.utilities.xmlParser.parse(value.xml);
-            XmlNode.insertBefore(newNode, wordTextNode);
+            // Tag.xmlTextNode always reference the actual xml text node.
+            // In MS Word each text node is wrapped by a <w:t> node so we retrieve that.
+            const wordTextNode = officeMarkup.query.containingTextNode(tag.xmlTextNode);
+
+            // If the input data contains an "xml" string property, parse it and insert 
+            // the content next to the placeholder tag.
+            const newNode = xml.parser.parse(value.xml);
+            xml.modify.insertBefore(newNode, wordTextNode);
         }
 
-        // Remove the placeholder node.
-        // We can be sure that only the placeholder is removed since easy-template-x
-        // makes sure that each tag is isolated into it's own separate <w:t> node.
-        XmlNode.remove(wordTextNode);
+        // Remove the placeholder tag.
+        officeMarkup.modify.removeTag(tag.xmlTextNode);
     }
 }
 ```