feat(pres): get info about loaded templates with pres.getInfo()

Author: singerla

README.md

@@ -1,6 +1,6 @@
 # pptx-automizer: A Powerful PPTX Modifier for Node.js
 
-pptx-automizer is a Node.js-based PowerPoint (.pptx) generator that automates the manipulation of existing .pptx files. With pptx-automizer, you can merge templates, customize slide content, and maintain your library of .pptx templates. `pptx-automizer` will not write files from scratch, but edit and merge existing pptx files. You can style template slides within PowerPoint, and these templates will be seamlessly integrated into the output presentation. Most of the content can be modified by using callbacks with [xmldom](https://github.com/xmldom/xmldom).
+`pptx-automizer` is a Node.js-based PowerPoint (.pptx) generator that automates the manipulation of existing .pptx files. With pptx-automizer, you can merge templates, customize slide content, and maintain your library of .pptx templates. `pptx-automizer` will not write files from scratch, but edit and merge existing pptx files. You can style template slides within PowerPoint, and these templates will be seamlessly integrated into the output presentation. Most of the content can be modified by using callbacks with [xmldom](https://github.com/xmldom/xmldom).
 
 `pptx-automizer` will fit best to users who try to maintain their own library of pptx template files. This is perfect to anyone who uses complex and well-styled customized layouts. Any existing slide and even a single element can be a data driven template for output pptx files.
 
@@ -130,23 +130,31 @@ const automizer = new Automizer({
 // any existing slide in RootTemplate.pptx. Otherwise, we are going to start
 // with a truncated root template.
 let pres = automizer
-  .loadRoot(`RootTemplate.pptx`)
+  .loadRoot('RootTemplate.pptx')
   // We want to make some more files available and give them a handy label.
-  .load(`SlideWithShapes.pptx`, 'shapes')
-  .load(`SlideWithGraph.pptx`, 'graph')
+  .load('SlideWithShapes.pptx', 'shapes')
+  .load('SlideWithGraph.pptx', 'graph')
   // Skipping the second argument will not set a label.
-  .load(`SlideWithImages.pptx`);
+  .load('SlideWithImages.pptx');
+
+// Get useful information about loaded templates:
+/*
+const presInfo = await pres.getInfo();
+const mySlides = presInfo.slidesByTemplate('shapes');
+const mySlide = presInfo.slideByNumber('shapes', 2);
+const myShape = presInfo.elementByName('shapes', 2, 'Cloud');
+*/ 
 
 // addSlide takes two arguments: The first will specify the source
 // presentation's label to get the template from, the second will set the
 // slide number to require.
 pres
   .addSlide('graph', 1)
   .addSlide('shapes', 1)
-  .addSlide(`SlideWithImages.pptx`, 2);
+  .addSlide('SlideWithImages.pptx', 2);
 
 // Finally, we want to write the output file.
-pres.write(`myPresentation.pptx`).then((summary) => {
+pres.write('myPresentation.pptx').then((summary) => {
   console.log(summary);
 });
 
@@ -478,12 +486,12 @@ pres.addSlide('charts', 2, (slide) => {
 ```
 
 Find out more about modifying charts:
+
 - [Modify chart axis](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-chart-axis.test.ts)
 - [Dealing with bubble charts](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-chart-bubbles.test.ts)
 - [Vertical line charts](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-chart-vertical-lines.test.ts)
 - [Style chart series and data points](https://github.com/singerla/pptx-automizer/blob/main/__tests__/modify-existing-chart-styled.test.ts)
 
-
 ## Modify extended charts
 
 If you need to modify extended chart types, such like waterfall or map charts, you need to use `modify.setExtendedChartData`.
@@ -526,6 +534,94 @@ pres
   });
 ```
 
+# Examples
+
+## Loop through an existing presentation
+
+If you would like to modify some elements in a single .pptx file, it is important to that `pptx-automizer` is not able to directly "jump" to a shape and modify.
+
+This is how it works internally:
+
+- Load a root template to append slides to
+- (Probably) load root template again to modify slides
+- Load other templates
+- Append a loaded slide to (probably truncated) root template
+- Modify the recently added slide
+- Write root template and appended slides as output presentation.
+
+In case you need to apply modifications to the root template, you need to load it as a normal template:
+
+```ts
+import Automizer, {
+  CmToDxa,
+  ISlide,
+  ModifyColorHelper,
+  ModifyShapeHelper,
+  ModifyTextHelper,
+} from 'pptx-automizer';
+
+const run = async () => {
+  const automizer = new Automizer({
+    templateDir: `path/to/pptx-templates`,
+    outputDir: `path/to/pptx-output`,
+    // this is required to start with no slides:
+    removeExistingSlides: true,
+  });
+
+  let pres = automizer
+    .loadRoot(`SlideWithShapes.pptx`)
+    // We load it twice to make it available for modifying slides.
+    // Defining a "name" as second params makes it a little easier
+    .load(`SlideWithShapes.pptx`, 'myTemplate');
+
+  // This is brandnew: get useful information about loaded templates:
+  const myTemplates = await pres.getInfo();
+  const mySlides = myTemplates.slidesByTemplate(`myTemplate`);
+
+  // Feel free to create some functions to pre-define all modifications
+  // you need to apply to your slides.
+  type CallbackBySlideNumber = {
+    slideNumber: number;
+    callback: (slide: ISlide) => void;
+  };
+  const callbacks: CallbackBySlideNumber[] = [
+    {
+      slideNumber: 2,
+      callback: (slide: ISlide) => {
+        slide.modifyElement('Cloud', [
+          ModifyTextHelper.setText('My content'),
+          ModifyShapeHelper.setPosition({
+            h: CmToDxa(5),
+          }),
+          ModifyColorHelper.solidFill({
+            type: 'srgbClr',
+            value: 'cccccc',
+          }),
+        ]);
+      },
+    },
+  ];
+  const getCallbacks = (slideNumber: number) => {
+    return callbacks.find((callback) => callback.slideNumber === slideNumber)
+      ?.callback;
+  };
+
+  // We can loop all slides an apply the callbacks if defined
+  mySlides.forEach((mySlide) => {
+    pres.addSlide('myTemplate', mySlide.number, getCallbacks(mySlide.number));
+  });
+
+  // This will result to an output presentation containing all slides of "SlideWithShapes.pptx"
+  pres.write(`myOutputPresentation.pptx`).then((summary) => {
+    console.log(summary);
+  });
+};
+
+run().catch((error) => {
+  console.error(error);
+});
+```
+
 ## Sort output slides
 
 There are three ways to arrange slides in an output presentation.
@@ -701,7 +797,6 @@ This project is deeply inspired by:
 - [node-pptx](https://github.com/heavysixer/node-pptx)
 - [docxtemplater](https://github.com/open-xml-templating/docxtemplater)
 
-
 ### Commercial Support
 
 If you need commercial support on complex .pptx automation, please take a look at [ensembl.io](https://ensembl.io).

src/automizer.ts

@@ -3,14 +3,20 @@ import {
   ArchiveParams,
   AutomizerParams,
   AutomizerSummary,
+  PresentationInfo,
   SourceIdentifier,
   StatusTracker,
 } from './types/types';
 import { IPresentationProps } from './interfaces/ipresentation-props';
 import { PresTemplate } from './interfaces/pres-template';
 import { RootPresTemplate } from './interfaces/root-pres-template';
 import { Template } from './classes/template';
-import { ModifyXmlCallback, TemplateInfo, XmlElement } from './types/xml-types';
+import {
+  ModifyXmlCallback,
+  SlideInfo,
+  TemplateInfo,
+  XmlElement,
+} from './types/xml-types';
 import { GeneralHelper, vd } from './helper/general-helper';
 import { Master } from './classes/master';
 import path from 'path';
@@ -242,6 +248,37 @@ export default class Automizer implements IPresentationProps {
     return templateCreationId;
   }
 
+  /**
+   * Get some info about the imported templates
+   * @returns Promise<PresentationInfo>
+   */
+  public async getInfo(): Promise<PresentationInfo> {
+    const creationIds = await this.setCreationIds();
+    const info: PresentationInfo = {
+      templateByName: (tplName: string) => {
+        return creationIds.find((template) => template.name === tplName);
+      },
+      slidesByTemplate: (tplName: string) => {
+        return info.templateByName(tplName)?.slides || [];
+      },
+      slideByNumber: (tplName: string, slideNumber: number) => {
+        return info
+          .slidesByTemplate(tplName)
+          .find((slide) => slide.number === slideNumber);
+      },
+      elementByName: (
+        tplName: string,
+        slideNumber: number,
+        elementName: string,
+      ) => {
+        return info
+          .slideByNumber(tplName, slideNumber)
+          ?.elements.find((element) => elementName === element.name);
+      },
+    };
+    return info;
+  }
+
   /**
    * Determines whether template is root or default template.
    * @param template

src/dev.ts

@@ -1,37 +1,65 @@
-import Automizer, { ModifyImageHelper, ModifyShapeHelper } from './index';
-import { CmToDxa } from './helper/modify-helper';
+import Automizer, {
+  CmToDxa,
+  ISlide,
+  ModifyColorHelper,
+  ModifyShapeHelper,
+  ModifyTextHelper,
+} from './index';
 
 const run = async () => {
   const automizer = new Automizer({
     templateDir: `${__dirname}/../__tests__/pptx-templates`,
     outputDir: `${__dirname}/../__tests__/pptx-output`,
-    mediaDir: `${__dirname}/../__tests__/media`,
+    removeExistingSlides: true,
   });
 
-  const pres = automizer
-    .loadRoot(`RootTemplate.pptx`)
-    .loadMedia(`feather.png`)
-    .load(`SlideWithShapes.pptx`, 'shapes')
-    .load(`SlideWithImages.pptx`, 'images');
+  let pres = automizer
+    .loadRoot(`SlideWithShapes.pptx`)
+    // We load it twice to make it available for modifying slides
+    // Defining a "name" as second params makes it a little easier
+    .load(`SlideWithShapes.pptx`, 'myTemplate');
 
-  await pres
-    .addSlide('images', 2, (slide) => {
-      slide.modifyElement('imagePNG', [
-        ModifyShapeHelper.setPosition({
-          w: CmToDxa(5),
-          h: CmToDxa(5),
-        }),
-        ModifyImageHelper.setRelationTarget('feather.png'),
-        ModifyImageHelper.setDuotoneFill({
-          tint: 100000,
-          color: {
+  // This is brandnew: get useful information about loaded templates:
+  const myTemplates = await pres.getInfo();
+  const mySlides = myTemplates.slidesByTemplate(`myTemplate`);
+
+  // Feel free to create some functions to pre-define all modifications
+  // you need to apply to your slides.
+  type CallbackBySlideNumber = {
+    slideNumber: number;
+    callback: (slide: ISlide) => void;
+  };
+  const callbacks: CallbackBySlideNumber[] = [
+    {
+      slideNumber: 2,
+      callback: (slide: ISlide) => {
+        slide.modifyElement('Cloud', [
+          ModifyTextHelper.setText('My content'),
+          ModifyShapeHelper.setPosition({
+            h: CmToDxa(5),
+          }),
+          ModifyColorHelper.solidFill({
             type: 'srgbClr',
-            value: 'ff850c',
-          },
-        }),
-      ]);
-    })
-    .write(`modify-shapes.test.pptx`);
+            value: 'cccccc',
+          }),
+        ]);
+      },
+    },
+  ];
+  const getCallbacks = (slideNumber: number) => {
+    return callbacks.find((callback) => callback.slideNumber === slideNumber)
+      ?.callback;
+  };
+
+  // We can loop all slides an apply the callbacks if defined
+  mySlides.forEach((mySlide) => {
+    pres.addSlide('myTemplate', mySlide.number, getCallbacks(mySlide.number));
+  });
+
+  // This will result to an output presentation containing all slides of "SlideWithShapes.pptx"
+  pres.write(`myOutputPresentation.pptx`).then((summary) => {
+    console.log(summary);
+  });
 };
 
 run().catch((error) => {

src/types/types.ts

@@ -1,5 +1,12 @@
 import { ElementSubtype, ElementType } from '../enums/element-type';
-import { RelationshipAttribute, XmlDocument, XmlElement } from './xml-types';
+import {
+  ElementInfo,
+  RelationshipAttribute,
+  SlideInfo,
+  TemplateInfo,
+  XmlDocument,
+  XmlElement,
+} from './xml-types';
 import IArchive, { ArchiveMode } from '../interfaces/iarchive';
 import { ContentTypeExtension } from '../enums/content-type-map';
 
@@ -100,6 +107,16 @@ export type AutomizerSummary = {
   images: number;
   masters: number;
 };
+export type PresentationInfo = {
+  templateByName: (tplName: string) => TemplateInfo;
+  slidesByTemplate: (tplName: string) => SlideInfo[];
+  slideByNumber: (tplName: string, slideNumber: number) => SlideInfo;
+  elementByName: (
+    tplName: string,
+    slideNumber: number,
+    elementName: string,
+  ) => ElementInfo;
+};
 export type Target = {
   file: string;
   type: string;