feature(master): add autoImportSlideMasters; add tests & readme

Author: singerla

README.md

@@ -0,0 +1,31 @@
+import Automizer from '../src/automizer';
+import { ModifyTextHelper } from '../src';
+
+test('Auto-import source slideLayout and -master', async () => {
+  const automizer = new Automizer({
+    templateDir: `${__dirname}/pptx-templates`,
+    outputDir: `${__dirname}/pptx-output`,
+    autoImportSlideMasters: true,
+  });
+
+  const pres = await automizer
+    .loadRoot(`EmptyTemplate.pptx`)
+    .load('SlidesWithAdditionalMaster.pptx')
+    .load('SlideMasters.pptx')
+
+    // We can disable .addMaster according to "autoImportSlideMasters: true"
+    // .addMaster('SlidesWithAdditionalMaster.pptx', 1)
+
+    .addSlide('SlidesWithAdditionalMaster.pptx', 3, (slide) => {
+      // We can also disable "slide.useSlideLayout()"
+      // with "autoImportSlideMasters: true"
+      // slide.useSlideLayout();
+    })
+    .addSlide('SlideMasters.pptx', 1)
+    .addSlide('SlidesWithAdditionalMaster.pptx', 1)
+    .addSlide('SlideMasters.pptx', 3)
+    .addSlide('SlideMasters.pptx', 2)
+    .write(`add-slide-master-auto-import.test.pptx`);
+
+  expect(pres.masters).toBe(5);
+});

__tests__/add-slide-master-auto-import.test.ts

@@ -0,0 +1,55 @@
+import Automizer from '../src/automizer';
+import { ModifyTextHelper } from '../src';
+
+test('Append and modify slideMastes and use slideLayouts', async () => {
+  const automizer = new Automizer({
+    templateDir: `${__dirname}/pptx-templates`,
+    outputDir: `${__dirname}/pptx-output`,
+  });
+
+  const pres = await automizer
+    .loadRoot(`EmptyTemplate.pptx`)
+    .load(`SlideWithNotes.pptx`, 'notes')
+    .load('SlidesWithAdditionalMaster.pptx')
+    .load('SlideWithShapes.pptx')
+    .load('SlideWithCharts.pptx')
+
+    // Import another slide master and all its slide layouts:
+    .addMaster('SlidesWithAdditionalMaster.pptx', 1, (master) => {
+      master.modifyElement(
+        `MasterRectangle`,
+        ModifyTextHelper.setText('my text on master'),
+      );
+      master.addElement(`SlideWithCharts.pptx`, 1, 'StackedBars');
+    })
+    .addMaster('SlidesWithAdditionalMaster.pptx', 2, (master) => {
+      master.addElement('SlideWithShapes.pptx', 1, 'Cloud 1');
+    })
+
+    // Add a slide (which might require an imported master):
+    .addSlide('SlidesWithAdditionalMaster.pptx', 3, (slide) => {
+      // To use the original master from 'SlidesWithAdditionalMaster.pptx',
+      // we can skip the argument. The required slideMaster & layout will be
+      // auto imported.
+      slide.useSlideLayout();
+    })
+
+    // Add a slide and use the source slideLayout:
+    .addSlide('SlidesWithAdditionalMaster.pptx', 3, (slide) => {
+      // To use the original master from 'SlidesWithAdditionalMaster.pptx',
+      // we can skip the argument.
+      slide.useSlideLayout();
+    })
+
+    // Add a slide (which might require an imported master):
+    .addSlide('notes', 1, (slide) => {
+      // use another master, e.g. the imported one from 'SlidesWithAdditionalMaster.pptx'
+      // You need to pass the index of the desired layout after all
+      // related layouts of all imported masters have been added to rootTemplate.
+      slide.useSlideLayout(26);
+    })
+
+    .write(`add-slide-master.test.pptx`);
+
+  expect(pres.masters).toBe(3);
+});

__tests__/add-slide-master.test.ts

@@ -180,7 +180,7 @@ export default class Automizer implements IPresentationProps {
       name,
     };
 
-    const newTemplate = Template.import(location, importParams);
+    const newTemplate = Template.import(location, importParams, this);
 
     if (!this.isPresTemplate(newTemplate)) {
       this.rootTemplate = newTemplate;
@@ -251,21 +251,26 @@ export default class Automizer implements IPresentationProps {
       callback(newSlide);
     }
 
+    if (this.params.autoImportSlideMasters) {
+      newSlide.useSlideLayout();
+    }
+
     this.rootTemplate.slides.push(newSlide);
 
     return this;
   }
 
   /**
-   * WIP: Copy and modify a master and the associated layouts from template
-   * to output.
+   * Copy and modify a master and the associated layouts from template to output.
+   *
    * @param name
    * @param sourceIdentifier
    * @param callback
    */
   public addMaster(
     name: string,
-    sourceIdentifier: SourceIdentifier,
+    // sourceIdentifier: SourceIdentifier,
+    sourceIdentifier: number,
     callback?: (slide: Master) => void,
   ): this {
     const template = this.getTemplate(name);

__tests__/pptx-templates/SlideMasters.pptx

@@ -123,6 +123,8 @@ export class Master implements IMaster {
     sourceIdentifier: SourceIdentifier;
   }) {
     this.sourceTemplate = params.template;
+
+    // ToDo analogue for slideMasters
     // this.sourceNumber = this.getSlideNumber(
     //   params.template,
     //   params.sourceIdentifier,
@@ -141,6 +143,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: Implement creationIds as well for slideMasters
+   *
    * Try to convert a given slide's creationId to corresponding slide number.
    * Used if automizer is run with useCreationIds: true
    * @internal
@@ -195,7 +199,7 @@ export class Master implements IMaster {
     await this.copySlideFiles();
     await this.copyRelatedLayouts();
     await this.copyRelatedContent();
-    await this.addSlideToPresentation();
+    await this.addSlideMasterToPresentation();
     await this.copyThemeFiles();
 
     if (this.importElements.length) {
@@ -306,17 +310,22 @@ export class Master implements IMaster {
    * @internal
    * @returns slide to presentation
    */
-  async addSlideToPresentation(): Promise<void> {
+  async addSlideMasterToPresentation(): Promise<void> {
     const relId = await XmlHelper.getNextRelId(
       this.targetArchive,
       'ppt/_rels/presentation.xml.rels',
     );
     await this.appendToSlideRel(this.targetArchive, relId, this.targetNumber);
     await this.appendToSlideList(this.targetArchive, relId);
-    await this.appendSlideToContentType(this.targetArchive, this.targetNumber);
+    await this.appendSlideMasterToContentType(
+      this.targetArchive,
+      this.targetNumber,
+    );
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Select and modify a single element on an added slide.
    * @param {string} selector - Element's name on the slide.
    * Should be a unique string defined on the "Selection"-pane within ppt.
@@ -340,6 +349,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Select, insert and (optionally) modify a single element to a slide.
    * @param {string} presName - Filename or alias name of the template presentation.
    * Must have been importet with Automizer.load().
@@ -363,6 +374,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Remove a single element from slide.
    * @param {string} selector - Element's name on the slide.
    */
@@ -380,6 +393,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Adds element to modifications list
    * @internal
    * @param presName
@@ -408,6 +423,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Imported selected elements
    * @internal
    * @returns selected elements
@@ -445,6 +462,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This *ALMOST* equals the corresponding method in slide.ts
+   *
    * Gets element info
    * @internal
    * @param importElement
@@ -506,6 +525,14 @@ export class Master implements IMaster {
     };
   }
 
+  /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
+   * @param selector
+   * @param sourceArchive
+   * @param sourcePath
+   * @param useCreationIds
+   */
   async findElementOnSlide(
     selector: FindElementSelector,
     sourceArchive: IArchive,
@@ -556,6 +583,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Analyzes element
    * @internal
    * @param sourceElement
@@ -617,6 +646,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Applys modifications
    * @internal
    * @returns modifications
@@ -633,6 +664,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Removes all unsupported tags from slide xml.
    * E.g. added relations & tags by Thinkcell cannot
    * be processed by pptx-automizer at the moment.
@@ -733,7 +766,7 @@ export class Master implements IMaster {
    * @param slideCount
    * @returns slide to content type
    */
-  appendSlideToContentType(
+  appendSlideMasterToContentType(
     rootArchive: IArchive,
     slideCount: number,
   ): Promise<HelperElement> {
@@ -770,6 +803,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Appends notes to content type
    * @internal
    * @param rootArchive
@@ -789,6 +824,8 @@ export class Master implements IMaster {
   }
 
   /**
+   * ToDo: This equals the corresponding method in slide.ts
+   *
    * Copys related content
    * @internal
    * @returns related content

src/automizer.ts

@@ -46,8 +46,8 @@ export class Template implements ITemplate {
   slides: ISlide[];
 
   /**
-   * Array containing all slides coming from Automizer.addSlide()
-   * @type: ISlide[]
+   * Array containing all slideMasters coming from Automizer.addMaster()
+   * @type: IMaster[]
    */
   masters: IMaster[];