Merge pull request #38 from singerla/feature-cache-1

sync main branch

Author: singerla

README.md

@@ -9,10 +9,19 @@ This project comes along with [automizer-data](https://github.com/singerla/autom
 This generator can only be used on the server-side and requires a [Node.js](https://nodejs.org/en/download/package-manager/) environment.
 
 ## Limitations
+### Shape types
 Please note that this project is *work in progress*. At the moment, you might encounter difficulties for special shape types that require further relations (e.g. links will not work properly). Although, most shape types are already supported, such as connection shapes, tables or charts. You are welcome to [report any issue](https://github.com/singerla/pptx-automizer/issues/new).
 
+### Chart types
+Extended chart types, like waterfall or map charts, are not supported right now. 
+
+### PowerPoint Version
 All testing focuses on PowerPoint 2019 pptx file format.
 
+### Slide Masters and -Layouts
+It is currently not supported to import slide masters or slide layouts into the root presentation. You can append any slide in any order, but you need to assure all pptx files to have the same set of master slides. Imported slide masters will be matched by number, e.g. if your imported slide uses master #3, your root presentation also needs to have at least three master slides.
+
+
 ## Install
 There are basically two ways to use *pptx-automizer*.
 
@@ -40,15 +49,9 @@ $ npm install pptx-automizer
 ```
 in the root folder of your project. This will download and install the most recent version into your existing project.
 
-## Example
-```js
-import Automizer, { modify } from "pptx-automizer"
-
-// If you want to track the steps of creation process,
-// you can use a custom callback:
-const myStatusTracker = (status: StatusTracker) => {
-  console.log(status.info + ' (' + status.share + '%)');
-};
+## General Example
+```ts
+import Automizer from "pptx-automizer"
 
 // First, let's set some preferences!
 const automizer = new Automizer({
@@ -69,12 +72,14 @@ const automizer = new Automizer({
   // truncate root presentation and start with zero slides
   removeExistingSlides: true,
 
-  // use a callback function to track pptx generation process
-  statusTracker: myStatusTracker,
+  // use a callback function to track pptx generation process.
+  // statusTracker: myStatusTracker,
 })
 
 // Now we can start and load a pptx template.
-// Each addSlide will append to any existing slide in RootTemplate.pptx.
+// With removeExistingSlides set to 'false', each addSlide will append to 
+// any existing slide in RootTemplate.pptx. Otherwise, we are going to start
+// with a truncated root template.
 let pres = automizer.loadRoot(`RootTemplate.pptx`)
   // We want to make some more files available and give them a handy label.
   .load(`SlideWithShapes.pptx`, 'shapes')
@@ -89,9 +94,33 @@ pres.addSlide('graph', 1)
   .addSlide('shapes', 1)
   .addSlide(`SlideWithImages.pptx`, 2)
 
-// You can also select and import a single element from a template slide. 
-// The desired shape will be identified by its name from slide-xml's 
-// 'p:cNvPr'-element.
+// Finally, we want to write the output file.
+pres.write(`myPresentation.pptx`).then(summary => {
+  console.log(summary)
+})
+```
+
+
+## Modify shapes with built-in functions
+It is possible to modify an existing element on a newly added slide.
+
+```ts
+import { modify } from "pptx-automizer"
+
+pres.addSlide('shapes', 2, (slide) => {
+  slide.modifyElement('Drum', [
+    // You can use some of the builtin modifiers to edit a shape's xml:
+    modify.setPosition({x: 1000000, h:5000000, w:5000000}),
+    // Log your target xml into the console:
+    modify.dump
+  ])
+})
+```
+
+## Add and modify shapes
+You can also select and import a single element from a template slide. The desired shape will be identified by its name from slide-xml's `p:cNvPr`-element.
+
+```ts
 pres.addSlide('SlideWithImages.pptx', 1, (slide) => {
   // Pass the template name, the slide number, the element's name and 
   // (optionally) a callback function to directly modify the child nodes 
@@ -102,17 +131,14 @@ pres.addSlide('SlideWithImages.pptx', 1, (slide) => {
       .data = 'Custom content'
   })
 })
+```
 
-// It is possible to modify an existing element on a newly added slide.
-pres.addSlide('shapes', 2, (slide) => {
-  slide.modifyElement('Drum', [
-    // You can use some of the builtin modifiers to edit a shape's xml:
-    modify.setPosition({x: 1000000, h:5000000, w:5000000}),
-    // Log your target xml into the console:
-    modify.dump
-  ])
-})
 
+## Modify charts
+
+All data and styles can be modified. Please notice: If your template has more data than your data object, automizer will remove these nodes. The other way round, new nodes will be created from the existing ones in case you provide more data. 
+
+```ts
 // Modify an existing chart on an added slide.
 pres.addSlide('charts', 2, (slide) => {
   slide.modifyElement('ColumnChart', [
@@ -132,11 +158,15 @@ pres.addSlide('charts', 2, (slide) => {
         { label: 'cat 2-4', values: [ 26, 50, 20 ] }
       ]
     })
-    // Please notice: If your template has more data than your data
-    // object, automizer will remove these nodes.
   ])
 })
 
+```
+## Remove elements from a slide
+
+You can as well remove elements from slides.
+
+```ts
 // Remove existing charts, images or shapes from added slide.
 pres
   .addSlide('charts', 2, (slide) => {
@@ -147,13 +177,99 @@ pres
     slide.removeElement('Textfeld 5');
     slide.addElement('images', 2, 'imageJPG');
 })
+```
 
-// Finally, we want to write the output file.
-pres.write(`myPresentation.pptx`).then(summary => {
+
+## Sort output slides
+
+There are three ways to arrange slides in an output presentation. 
+
+1. By default, all slides will be appended to the existing slides in your root template. The order of `addSlide`-calls will define slide sortation in output presentation.
+
+2. You can alternatively remove all existing slides by setting the `removeExistingSlides` flag to true. The first slide added with `addSlide` will be first slide in the output presentation. If you want to insert slides from root template, you need to load it a second time.
+
+```ts
+import Automizer from "pptx-automizer"
+
+const automizer = new Automizer({
+  templateDir: `my/pptx/templates`,
+  outputDir: `my/pptx/output`,
+
+  // truncate root presentation and start with zero slides
+  removeExistingSlides: true,
+})
+
+
+let pres = automizer.loadRoot(`RootTemplate.pptx`)
+  // We load this twice to make it slide reordeing available 
+  .load(`RootTemplate.pptx`, 'root')  
+  .load(`SlideWithShapes.pptx`, 'shapes')
+  .load(`SlideWithGraph.pptx`, 'graph')
+
+pres.addSlide('root', 1)  // First slide will be taken from root
+  .addSlide('graph', 1)
+  .addSlide('shapes', 1)
+  .addSlide('root', 3)    // Third slide from root we be appended
+  .addSlide('root', 2)    // Second and third slide will switch position
+})
+
+pres.write(`mySortedPresentation.pptx`).then(summary => {
   console.log(summary)
 })
 ```
 
+
+3. Use `sortSlides`-callback
+You can pass an array of numbers and create a callback and apply it to `presentation.xml`.
+This will also work without adding slides.
+
+Slides will be appended to the existing slides by slide number (starting from 1). You may find irritating results in case you skip a slide number.
+
+```ts
+import ModifyPresentationHelper from './helper/modify-presentation-helper';
+
+// 
+// You may truncate root template or you may not
+// ...
+
+// It is possible to skip adding slides, try sorting an unmodified presentation
+pres.addSlide('charts', 1);
+  .addSlide('charts', 2);
+  .addSlide('images', 1);
+  .addSlide('images', 2);
+  
+const order = [3, 2, 4, 1];
+pres.modify(ModifyPresentationHelper.sortSlides(order));
+```
+
+
+## Track status of automation process
+
+When creating large presentations, you might want to have some information about the current status. Use a custom status tracker:
+
+```ts
+import Automizer, { StatusTracker } from "pptx-automizer"
+
+// If you want to track the steps of creation process,
+// you can use a custom callback:
+const myStatusTracker = (status: StatusTracker) => {
+  console.log(status.info + ' (' + status.share + '%)');
+};
+
+const automizer = new Automizer({
+  // ...
+  statusTracker: myStatusTracker,
+})
+```
+
+## More examples
+Take a look into [__tests__-directory](https://github.com/singerla/pptx-automizer/blob/main/__tests__) to see a lot of examples for several use cases, e.g.:
+* [Style chart series or datapoints](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-existing-chart-styled.test.ts)
+* [Use tags inside text to replace contents](https://github.com/singerla/pptx-automizer/blob/main/__tests__/replace-tagged-text.test.ts)
+* [Modify vertical line charts](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-chart-vertical-lines.test.ts)
+* [Set table cell and border styles](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-existing-table.test.ts)
+
+
 ### Testing
 You can run all unit tests using these commands:
 ```

__tests__/pptx-templates/ChartWaterfall.pptx

@@ -0,0 +1,30 @@
+import Automizer from '../src/automizer';
+import ModifyPresentationHelper from '../src/helper/modify-presentation-helper';
+
+test('read root presentation and sort slides', async () => {
+  const automizer = new Automizer({
+    templateDir: `${__dirname}/pptx-templates`,
+    outputDir: `${__dirname}/pptx-output`,
+  });
+  const pres = automizer
+    .loadRoot(`RootTemplate.pptx`)
+    .load(`SlideWithShapes.pptx`, 'shapes')
+    .load(`SlideWithCharts.pptx`, 'charts')
+    .load(`SlideWithImages.pptx`, 'images');
+
+  for (let i = 0; i <= 2; i++) {
+    pres.addSlide('shapes', 1);
+  }
+
+  pres.addSlide('charts', 1);
+  pres.addSlide('charts', 2);
+  pres.addSlide('images', 1);
+  pres.addSlide('images', 2);
+
+  const order = [2, 1, 8, 7, 5, 6, 3, 4];
+  pres.modify(ModifyPresentationHelper.sortSlides(order));
+
+  await pres.write(`sort-slides.test.pptx`);
+
+  expect(pres).toBeInstanceOf(Automizer);
+});

__tests__/sort-slides.test.ts

@@ -16,6 +16,7 @@ import { Master } from './classes/master';
 import path from 'path';
 import * as fs from 'fs';
 import { XmlHelper } from './helper/xml-helper';
+import ModifyPresentationHelper from './helper/modify-presentation-helper';
 
 /**
  * Automizer
@@ -161,7 +162,7 @@ export default class Automizer implements IPresentationProps {
   /**
    * Parses all loaded templates and collects creationIds for slides and
    * elements. This will make finding templates and elements independent
-   * from slide number and element name.
+   * of slide number and element name.
    * @returns Promise<TemplateInfo[]>
    */
   public async setCreationIds(): Promise<TemplateInfo[]> {
@@ -272,6 +273,7 @@ export default class Automizer implements IPresentationProps {
    */
   public async write(location: string): Promise<AutomizerSummary> {
     await this.writeSlides();
+    await this.normalizePresentation();
     await this.applyModifyPresentationCallbacks();
 
     const rootArchive = await this.rootTemplate.archive;
@@ -312,6 +314,18 @@ export default class Automizer implements IPresentationProps {
     );
   }
 
+  /**
+   * Apply some callbacks to restore archive/xml structure
+   * and prevent corrupted pptx files.
+   *
+   * TODO: Remove unused parts (slides, related items) from archive.
+   * TODO: Use every imported image only once
+   * TODO: Check for lost relations
+   */
+  normalizePresentation(): void {
+    this.modify(ModifyPresentationHelper.normalizeSlideIds);
+  }
+
   /**
    * Applies path prefix to given location string.
    * @param location path and/or filename
@@ -325,6 +339,10 @@ export default class Automizer implements IPresentationProps {
           return this.templateDir + location;
         } else if (fs.existsSync(this.templateFallbackDir + location)) {
           return this.templateFallbackDir + location;
+        } else {
+          vd('No file matches "' + location + '"');
+          vd('@templateDir: ' + this.templateDir);
+          vd('@templateFallbackDir: ' + this.templateFallbackDir);
         }
         break;
       case 'output':

src/automizer.ts

@@ -1,7 +1,7 @@
 import JSZip from 'jszip';
 
 import { XmlHelper } from '../helper/xml-helper';
-import { GeneralHelper } from '../helper/general-helper';
+import { GeneralHelper, vd } from '../helper/general-helper';
 import {
   ImportedElement,
   ShapeModificationCallback,
@@ -10,6 +10,7 @@ import {
 import { RootPresTemplate } from '../interfaces/root-pres-template';
 import { HelperElement } from '../types/xml-types';
 import { ImageTypeMap } from '../enums/image-type-map';
+import { ElementSubtype } from '../enums/element-type';
 
 export class Shape {
   mode: string;
@@ -42,6 +43,7 @@ export class Shape {
   callbacks: ShapeModificationCallback[];
   hasCreationId: boolean;
   contentTypeMap: typeof ImageTypeMap;
+  subtype: ElementSubtype;
 
   constructor(shape: ImportedElement) {
     this.mode = shape.mode;
@@ -55,9 +57,11 @@ export class Shape {
 
     this.callbacks = GeneralHelper.arrayify(shape.callback);
     this.contentTypeMap = ImageTypeMap;
+
     if (shape.target) {
       this.sourceNumber = shape.target.number;
       this.sourceRid = shape.target.rId;
+      this.subtype = shape.target.subtype;
     }
   }