chore(generate): use custom pptxGenJS instance; expose IPptxGenJSSlide;

Author: singerla

src/automizer.ts

@@ -19,12 +19,16 @@ import path from 'path';
 import * as fs from 'fs';
 import { XmlHelper } from './helper/xml-helper';
 import ModifyPresentationHelper from './helper/modify-presentation-helper';
-import { contentTracker as Tracker, ContentTracker } from './helper/content-tracker';
+import {
+  contentTracker as Tracker,
+  ContentTracker,
+} from './helper/content-tracker';
 import JSZip from 'jszip';
 import { ISlide } from './interfaces/islide';
 import { IMaster } from './interfaces/imaster';
 import { ContentTypeExtension } from './enums/content-type-map';
 import slugify from 'slugify';
+import PptxGenJS from 'pptxgenjs';
 
 /**
  * Automizer
@@ -489,11 +493,11 @@ export default class Automizer implements IPresentationProps {
     await this.rootTemplate.countExistingSlides();
     this.status.max = this.rootTemplate.slides.length;
 
-    await this.rootTemplate.runExternalGenerators();
+    await this.rootTemplate.runExternalGenerator();
     for (const slide of this.rootTemplate.slides) {
       await this.rootTemplate.appendSlide(slide);
     }
-    await this.rootTemplate.cleanupExternalGenerators();
+    await this.rootTemplate.cleanupExternalGenerator();
 
     if (this.params.removeExistingSlides) {
       await this.rootTemplate.truncate();

src/classes/has-shapes.ts

@@ -265,9 +265,6 @@ export default class HasShapes {
     return this;
   }
 
-  /**
-   *
-   */
   generate(generate: GenerateOnSlideCallback, objectName?: string): this {
     this.generateElements.push({
       objectName,

src/classes/template.ts

@@ -69,7 +69,7 @@ export class Template implements ITemplate {
   mediaFiles: MediaFile[] = [];
 
   automizer: Automizer;
-  generators: IGenerator[] = [];
+  generator: IGenerator;
 
   constructor(file: AutomizerFile, params: ArchiveParams) {
     this.file = file;
@@ -241,19 +241,12 @@ export class Template implements ITemplate {
     return CountHelper.count(name, this.counter);
   }
 
-  async runExternalGenerators() {
-    this.generators.push(
-      new GeneratePptxGenJs(this.automizer, this.slides).create(),
-    );
-
-    for (const generator of this.generators) {
-      await generator.generateSlides();
-    }
+  async runExternalGenerator() {
+    this.generator = new GeneratePptxGenJs(this.automizer, this.slides);
+    await this.generator.generateSlides();
   }
 
-  async cleanupExternalGenerators() {
-    for (const generator of this.generators) {
-      await generator.cleanup();
-    }
+  async cleanupExternalGenerator() {
+    await this.generator.cleanup();
   }
 }

src/helper/generate/generate-pptxgenjs.ts

@@ -1,11 +1,16 @@
 import { randomUUID } from 'crypto';
 import PptxGenJS from 'pptxgenjs';
-import fs from 'fs';
 import { ISlide } from '../../interfaces/islide';
 import Automizer from '../../automizer';
-import { GenerateElements, SupportedPptxGenJSSlide } from '../../types/types';
+import { GenerateElements } from '../../types/types';
 import { IGenerator } from '../../interfaces/igenerator';
+import { IPptxGenJSSlide } from '../../interfaces/ipptxgenjs-slide';
+import { vd } from '../general-helper';
 
+/**
+ * Using pptxGenJs on an automizer ISlide will create a temporary pptx template
+ * and auto-import the generated shapes to the right place on the output slides.
+ */
 export default class GeneratePptxGenJs implements IGenerator {
   tmpFile: string;
   slides: ISlide[];
@@ -16,11 +21,17 @@ export default class GeneratePptxGenJs implements IGenerator {
   constructor(automizer: Automizer, slides: ISlide[]) {
     this.automizer = automizer;
     this.slides = slides;
+    this.create();
   }
 
-  create(): this {
-    this.generator = new PptxGenJS();
-    return this;
+  create() {
+    if (this.automizer.params.pptxGenJs) {
+      // Use a customized pptxGenJs instance
+      this.generator = this.automizer.params.pptxGenJs;
+    } else {
+      // Or the installed version
+      this.generator = new PptxGenJS();
+    }
   }
 
   async generateSlides(): Promise<void> {
@@ -29,7 +40,8 @@ export default class GeneratePptxGenJs implements IGenerator {
       const generate = slide.getGeneratedElements();
       if (generate.length) {
         this.countSlides++;
-        this.addElements(generate, this.appendPptxGenSlide(), slide);
+        await this.generateElements(generate, this.appendPptxGenSlide());
+        this.addElements(generate, slide);
       }
     }
 
@@ -41,72 +53,79 @@ export default class GeneratePptxGenJs implements IGenerator {
     }
   }
 
-  addElements(
+  async generateElements(
     generate: GenerateElements[],
     pgenSlide: PptxGenJS.Slide,
-    slide: ISlide,
-  ) {
-    generate.forEach((generateElement) => {
+  ): Promise<void> {
+    for (const generateElement of generate) {
       generateElement.tmpSlideNumber = this.countSlides;
-
       const addedObjects = <string[]>[];
-
-      generateElement.callback(
-        this.supportedSlideItems(pgenSlide, generateElement, addedObjects),
+      await generateElement.callback(
+        this.addSlideItems(pgenSlide, generateElement, addedObjects),
         this.generator,
       );
+      generateElement.addedObjects = [...addedObjects];
+    }
+  }
 
-      addedObjects.forEach((addedObjectName) => {
+  addElements(generate: GenerateElements[], slide: ISlide) {
+    generate.forEach((generateElement) => {
+      generateElement.addedObjects.forEach((addedObjectName) => {
         slide.addElement(this.tmpFile, this.countSlides, addedObjectName);
       });
     });
   }
 
-  supportedSlideItems = (
+  /**
+   * This is a wrapper around supported pptxGenJS slide item types.
+   * It is required to create a unique objectName and find the generated
+   * shapes by object name later.
+   *
+   * @param pgenSlide
+   * @param generateElement
+   * @param addedObjects
+   */
+  addSlideItems = (
     pgenSlide: PptxGenJS.Slide,
     generateElement: GenerateElements,
     addedObjects: string[],
-  ): SupportedPptxGenJSSlide => {
+  ): IPptxGenJSSlide => {
+    const getObjectName = () => {
+      return this.generateObjectName(generateElement, addedObjects);
+    };
     return {
       addChart: (type, data, options) => {
-        const objectName = this.generateObjectName(
-          generateElement,
-          addedObjects,
+        pgenSlide.addChart(
+          type,
+          data,
+          this.getOptions(options, getObjectName()),
         );
-        pgenSlide.addChart(type, data, this.getOptions(options, objectName));
       },
       addImage: (options) => {
-        const objectName = this.generateObjectName(
-          generateElement,
-          addedObjects,
-        );
-        pgenSlide.addImage(this.getOptions(options, objectName));
+        pgenSlide.addImage(this.getOptions(options, getObjectName()));
       },
       addShape: (shapeName, options?) => {
-        const objectName = this.generateObjectName(
-          generateElement,
-          addedObjects,
+        pgenSlide.addShape(
+          shapeName,
+          this.getOptions(options, getObjectName()),
         );
-        pgenSlide.addShape(shapeName, this.getOptions(options, objectName));
       },
       addTable: (tableRows, options?) => {
-        const objectName = this.generateObjectName(
-          generateElement,
-          addedObjects,
+        pgenSlide.addTable(
+          tableRows,
+          this.getOptions(options, getObjectName()),
         );
-        pgenSlide.addTable(tableRows, this.getOptions(options, objectName));
       },
       addText: (text, options?) => {
-        const objectName = this.generateObjectName(
-          generateElement,
-          addedObjects,
-        );
-        pgenSlide.addText(text, this.getOptions(options, objectName));
+        pgenSlide.addText(text, this.getOptions(options, getObjectName()));
       },
     };
   };
 
-  generateObjectName(generateElement, addedObjects: string[]): string {
+  generateObjectName(
+    generateElement: GenerateElements,
+    addedObjects: string[],
+  ): string {
     const objectName =
       (generateElement.objectName ? generateElement.objectName + '-' : '') +
       randomUUID();

src/index.ts

@@ -39,6 +39,7 @@ import ModifyColorHelper from './helper/modify-color-helper';
 import { ITemplate } from './interfaces/itemplate';
 import { IMaster } from './interfaces/imaster';
 import { ISlide } from './interfaces/islide';
+import { IPptxGenJSSlide } from './interfaces/ipptxgenjs-slide';
 import ModifyImageHelper from './helper/modify-image-helper';
 import { LabelPosition } from './enums/chart-type';
 
@@ -162,5 +163,5 @@ export type {
   XmlElement,
   XmlDocument,
 };
-export { ITemplate, IMaster, ISlide };
+export { ITemplate, IMaster, ISlide, IPptxGenJSSlide };
 export default Automizer;

src/interfaces/igenerator.ts

@@ -1,5 +1,5 @@
 export interface IGenerator {
-  create(): IGenerator;
   generateSlides(): Promise<void>;
+
   cleanup(): Promise<void>;
 }

src/interfaces/ipptxgenjs-slide.ts

@@ -0,0 +1,61 @@
+import PptxGenJS from 'pptxgenjs';
+
+/**
+ * Usage of pptxGenJs insinde pptx-automizer is restricted to supported
+ * shape types.
+ */
+export interface IPptxGenJSSlide {
+  /**
+   * Add chart to Slide
+   * @param {CHART_NAME|IChartMulti[]} type - chart type
+   * @param {object[]} data - data object
+   * @param {IChartOpts} options - chart options
+   * @return {Slide} this Slide
+   * @type {Function}
+   */
+  addChart(
+    type: PptxGenJS.CHART_NAME | PptxGenJS.IChartMulti[],
+    data: any[],
+    options?: PptxGenJS.IChartOpts,
+  ): void;
+
+  /**
+   * Add image to Slide
+   * @param {ImageProps} options - image options
+   * @return {Slide} this Slide
+   */
+  addImage(options: PptxGenJS.ImageProps): void;
+
+  /**
+   * Add shape to Slide
+   * @param {SHAPE_NAME} shapeName - shape name
+   * @param {ShapeProps} options - shape options
+   * @return {Slide} this Slide
+   */
+  addShape(
+    shapeName: PptxGenJS.SHAPE_NAME,
+    options?: PptxGenJS.ShapeProps,
+  ): void;
+
+  /**
+   * Add table to Slide
+   * @param {TableRow[]} tableRows - table rows
+   * @param {TableProps} options - table options
+   * @return {Slide} this Slide
+   */
+  addTable(
+    tableRows: PptxGenJS.TableRow[],
+    options?: PptxGenJS.TableProps,
+  ): void;
+
+  /**
+   * Add text to Slide
+   * @param {string|TextProps[]} text - text string or complex object
+   * @param {TextPropsOptions} options - text options
+   * @return {Slide} this Slide
+   */
+  addText(
+    text: string | PptxGenJS.TextProps[],
+    options?: PptxGenJS.TextPropsOptions,
+  ): void;
+}

src/interfaces/root-pres-template.ts

@@ -21,15 +21,25 @@ export interface RootPresTemplate extends ITemplate {
   ) => void;
   getMappedContent: (type: string, key: string, sourceId: number) => any;
   getNamedMappedContent: (type: string, name: string) => any;
+
   count(name: string): number;
+
   incrementCounter(name: string): number;
+
   appendSlide(slide: ISlide): Promise<void>;
+
   appendMasterSlide(slideMaster: IMaster): Promise<void>;
+
   appendLayout(slideLayout: ILayout): Promise<void>;
-  runExternalGenerators?(): Promise<void>;
-  cleanupExternalGenerators?(): Promise<void>;
+
+  runExternalGenerator?(): Promise<void>;
+
+  cleanupExternalGenerator?(): Promise<void>;
+
   countExistingSlides(): Promise<void>;
+
   truncate(): Promise<void>;
+
   content?: ContentTracker;
   automizer?: Automizer;
 }