Merge remote-tracking branch 'origin/main'

Author: singerla

README.md

@@ -38,6 +38,11 @@ If you require commercial support for complex .pptx automation, you can explore
   - [Modify Charts](#modify-charts)
   - [Modify Extended Charts](#modify-extended-charts)
   - [Remove elements from a slide](#remove-elements-from-a-slide)
+  - [🔗 Hyperlink Management](#🔗-hyperlink-management)
+  - [Hyperlink Helper Functions](#hyperlink-helper-functions)
+  - [Adding Hyperlinks](#adding-hyperlinks)
+
+
 - [Tipps and Tricks](#tipps-and-tricks)
   - [Loop through the slides of a presentation](#loop-through-the-slides-of-a-presentation)
   - [Quickly get all slide numbers of a template](#quickly-get-all-slide-numbers-of-a-template)
@@ -49,6 +54,7 @@ If you require commercial support for complex .pptx automation, you can explore
   - [Troubleshooting](#troubleshooting)
   - [Testing](#testing)
 - [Special Thanks](#special-thanks)
+
 <!-- TOC -->
 
 # Requirements and Limitations
@@ -590,6 +596,36 @@ pres
   });
 ```
 
+## 🔗 Hyperlink Management
+
+PowerPoint presentations often use hyperlinks to connect to external websites or internal slides. The PPTX Automizer provides simple and powerful functions to manage hyperlinks in your presentations.
+
+### Hyperlink Helper Functions
+
+Three core functions are available for all your hyperlink needs:
+
+| Function | Description |
+|----------|-------------|
+| `addHyperlink` | Add a new hyperlink to an element |
+
+
+### Adding Hyperlinks
+
+You can add hyperlinks to text elements using the `addHyperlink` helper function. The function accepts either a URL string for external links or a slide number for internal slide links:
+
+```ts
+// Add an external hyperlink
+slide.modifyElement('TextShape', modify.addHyperlink('https://example.com'));
+
+
+// Add an internal slide link (to slide 3)
+slide.modifyElement('TextShape', (element, relation) => {
+  modify.addHyperlink(3)(element, relation);
+});
+```
+
+The `addHyperlink` function will automatically detect whether the target is an external URL or an internal slide number and set up the appropriate relationship type and attributes.
+
 # Tipps and Tricks
 
 ## Loop through the slides of a presentation

__tests__/copy-hyperlink.test.ts

@@ -0,0 +1,161 @@
+import Automizer from '../src/index';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as JSZip from 'jszip';
+import { DOMParser } from '@xmldom/xmldom';
+
+test('Add and modify hyperlinks', async () => {
+  const automizer = new Automizer({
+    templateDir: `${__dirname}/pptx-templates`,
+    outputDir: `${__dirname}/pptx-output`,
+  });
+
+  const pres = automizer
+    .loadRoot(`RootTemplate.pptx`)
+    .load(`EmptySlide.pptx`, 'empty')
+    .load(`SlideWithLink.pptx`, 'link');
+
+  // Track if the hyperlink was added
+  const outputFile = `modify-hyperlink.test.pptx`;
+  const outputPath = path.join(`${__dirname}/pptx-output`, outputFile);
+
+  const result = await pres
+    // Add the slide with the existing hyperlink
+    .addSlide('empty', 1, (slide) => {
+      // Add the element with the hyperlink from the source slide
+      slide.addElement('link', 1, 'ExternalLink');
+    })
+    .write(outputFile);
+
+  // Verify the number of slides
+  expect(result.slides).toBe(2);
+  
+  // Now verify that the hyperlink was actually copied by checking the PPTX file
+  // Read the generated PPTX file
+  const fileData = fs.readFileSync(outputPath);
+  const zip = await JSZip.loadAsync(fileData);
+  
+  // The second slide should be slide2.xml (index starts at 1 in PPTX)
+  // Check its relationships file for hyperlink entries
+  const slideRelsPath = 'ppt/slides/_rels/slide2.xml.rels';
+  const slideRelsFile = zip.file(slideRelsPath);
+  
+  // Make sure the file exists
+  expect(slideRelsFile).not.toBeNull();
+  
+  // Get the file content
+  const slideRelsXml = await slideRelsFile!.async('text');
+  
+  // Parse the XML
+  const parser = new DOMParser();
+  const xmlDoc = parser.parseFromString(slideRelsXml, 'application/xml');
+  
+  // Look for hyperlink relationships
+  const relationships = xmlDoc.getElementsByTagName('Relationship');
+  let hasHyperlink = false;
+  let hyperlinkId = '';
+  
+  for (let i = 0; i < relationships.length; i++) {
+    const relationship = relationships[i];
+    const type = relationship.getAttribute('Type');
+    if (type === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink') {
+      hasHyperlink = true;
+      const id = relationship.getAttribute('Id');
+      hyperlinkId = id || '';
+      break;
+    }
+  }
+  
+  // Verify that a hyperlink relationship exists
+  expect(hasHyperlink).toBe(true);
+  expect(hyperlinkId).not.toBe('');
+  
+  // Now check if the slide XML contains the hyperlink reference
+  const slidePath = 'ppt/slides/slide2.xml';
+  const slideFile = zip.file(slidePath);
+  
+  // Make sure the file exists
+  expect(slideFile).not.toBeNull();
+  
+  // Get the file content
+  const slideXml = await slideFile!.async('text');
+  
+  // Verify that the hyperlink ID is referenced in the slide content
+  expect(slideXml.includes(`r:id="${hyperlinkId}"`)).toBe(true);
+});
+
+test('Copy full slide with hyperlinks', async () => {
+  const automizer = new Automizer({
+    templateDir: `${__dirname}/pptx-templates`,
+    outputDir: `${__dirname}/pptx-output`,
+  });
+
+  const pres = automizer
+    .loadRoot(`RootTemplate.pptx`)
+    .load(`SlideWithLink.pptx`, 'link');
+
+  const outputFile = `copy-slide-with-hyperlink.test.pptx`;
+  const outputPath = path.join(`${__dirname}/pptx-output`, outputFile);
+
+  const result = await pres
+    .addSlide('link', 1)
+    .write(outputFile);
+
+  // Verify the number of slides
+  expect(result.slides).toBe(2);
+
+  // Read the generated PPTX file
+  const fileData = fs.readFileSync(outputPath);
+  const zip = await JSZip.loadAsync(fileData);
+  
+  // Check relationships file for slide 2
+  const slideRelsPath = 'ppt/slides/_rels/slide2.xml.rels';
+  const slideRelsFile = zip.file(slideRelsPath);
+  expect(slideRelsFile).not.toBeNull();
+  
+  const slideRelsXml = await slideRelsFile!.async('text');
+  const parser = new DOMParser();
+  const xmlDoc = parser.parseFromString(slideRelsXml, 'application/xml');
+  
+  // Look for hyperlink relationships
+  const relationships = xmlDoc.getElementsByTagName('Relationship');
+  let hasExternalHyperlink = false;
+  let hasInternalHyperlink = false;
+  let externalHyperlinkId = '';
+  let internalHyperlinkId = '';
+  
+  for (let i = 0; i < relationships.length; i++) {
+    const relationship = relationships[i];
+    const type = relationship.getAttribute('Type');
+    if (type === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink') {
+      const targetMode = relationship.getAttribute('TargetMode');
+      const id = relationship.getAttribute('Id') || '';
+      
+      if (targetMode === 'External') {
+        hasExternalHyperlink = true;
+        externalHyperlinkId = id;
+      } else if (!targetMode) {
+        hasInternalHyperlink = true;
+        internalHyperlinkId = id;
+      }
+    }
+  }
+  
+  // Verify that hyperlink relationships exist
+  expect(hasExternalHyperlink).toBe(true);
+  expect(externalHyperlinkId).not.toBe('');
+  
+  // Check the slide XML content
+  const slidePath = 'ppt/slides/slide2.xml';
+  const slideFile = zip.file(slidePath);
+  expect(slideFile).not.toBeNull();
+  
+  const slideXml = await slideFile!.async('text');
+  
+  // Verify hyperlink references in slide content
+  expect(slideXml.includes(`r:id="${externalHyperlinkId}"`)).toBe(true);
+  
+  if (hasInternalHyperlink) {
+    expect(slideXml.includes(`r:id="${internalHyperlinkId}"`)).toBe(true);
+  }
+});

__tests__/generate-pptxgenjs-hyperlinks.test.ts

@@ -0,0 +1,68 @@
+import { Automizer } from '../src';
+import fs from 'fs';
+import path from 'path';
+
+describe('Hyperlink works with generate', () => {
+  it('Hyperlink works with generate', async () => {
+    const automizer = new Automizer({
+      templateDir: path.join(__dirname, 'pptx-templates'),
+      outputDir: path.join(__dirname, 'pptx-output')
+    });
+
+    // Load root and template files
+    await automizer.loadRoot('EmptyTemplate.pptx');
+    await automizer.load('EmptySlide.pptx', 'template');
+
+    // Create slide 1 with hyperlinks
+    await automizer.addSlide('template', 1, async (slide) => {
+      // Test external links
+      const externalUrls = [
+        'https://google.com/1',
+        'https://google.com/2',
+        'https://google.com/3',
+      ];
+
+      for (let i = 0; i < externalUrls.length; i++) {
+        slide.generate(async pptxGenJSSlide => {
+          // External link
+          pptxGenJSSlide.addText(`External Link ${i + 1}`, {
+            hyperlink: { url: externalUrls[i] },
+            x: 1,
+            y: 1 + i,
+            fontFace: 'Kanit',
+          });
+        });
+      }
+
+      // Test internal links
+      const targetSlides = [2, 3, 4];
+      for (let i = 0; i < targetSlides.length; i++) {
+        slide.generate(async pptxGenJSSlide => {
+          // Internal link
+          pptxGenJSSlide.addText(`Go to Slide ${targetSlides[i]}`, {
+            hyperlink: { slide: targetSlides[i] },
+            x: 3,
+            y: 1 + i,
+            fontFace: 'Kanit',
+          });
+        });
+      }
+    });
+    
+    // Create target slides that we'll link to
+    for (let i = 2; i <= 4; i++) {
+      await automizer.addSlide('template', 1, async (slide) => {
+        slide.generate(async pptxGenJSSlide => {
+          pptxGenJSSlide.addText(`This is Slide ${i}`, {
+            x: 1,
+            y: 1,
+            fontFace: 'Kanit',
+          });
+        });
+      });
+    }
+
+    // Write the presentation
+    await automizer.write('hyperlink-test.pptx');
+  });
+});