Add support for groups

Author: Luke Vella

package-lock.json

@@ -720,6 +720,7 @@ export enum MASTER_OBJECTS {
 
 export enum SLIDE_OBJECT_TYPES {
 	'chart' = 'chart',
+	'group' = 'group',
 	'hyperlink' = 'hyperlink',
 	'image' = 'image',
 	'media' = 'media',

src/core-enums.ts

@@ -2,6 +2,7 @@
  * PptxGenJS Interfaces
  */
 
+import { Group } from './group'
 import { CHART_NAME, PLACEHOLDER_TYPES, SHAPE_NAME, SLIDE_OBJECT_TYPES, TEXT_HALIGN, TEXT_VALIGN, WRITE_OUTPUT_TYPE } from './core-enums'
 
 // Core Types
@@ -1316,6 +1317,7 @@ export interface ISlideObject {
 	mtype?: MediaType
 	mediaRid?: number
 	shape?: SHAPE_NAME
+	group?: Group
 }
 // PRIVATE ^^^
 
@@ -1396,7 +1398,12 @@ export interface ObjectOptions extends ImageProps, PositionProps, ShapeProps, Ta
 	colW?: number | number[] // table
 	rowH?: number | number[] // table
 }
-export interface SlideBaseProps {
+
+// A Container is an object that holds slide objects. i.e. a Slide or Group
+export interface Container {
+	_slideObjects?: ISlideObject[]
+}
+export interface SlideBaseProps extends Container {
 	_bkgdImgRid?: number
 	_margin?: Margin
 	_name?: string
@@ -1406,7 +1413,6 @@ export interface SlideBaseProps {
 	_relsMedia: ISlideRelMedia[] // needed as we use args:"PresSlide|SlideLayout" often
 	_slideNum: number
 	_slideNumberProps?: SlideNumberProps
-	_slideObjects?: ISlideObject[]
 
 	background?: BackgroundProps
 	/**
@@ -1434,6 +1440,7 @@ export interface PresSlide extends SlideBaseProps {
 	addShape: Function
 	addTable: Function
 	addText: Function
+	addGroup: Function
 
 	/**
 	 * Background color or image (`fill` | `path` | `data`)

src/core-interfaces.ts

@@ -78,44 +78,19 @@ let imageSizingXml = {
 }
 
 /**
- * Transforms a slide or slideLayout to resulting XML string - Creates `ppt/slide*.xml`
- * @param {PresSlide|SlideLayout} slideObject - slide object created within createSlideObject
- * @return {string} XML string with <p:cSld> as the root
+ * Transforms a list of slide objects to an XML string and returns the position and size values for their container.
+ * @param {ISlideObject[]} slideItemObjs
+ * @param {PresSlide|SlideLayout} slide
+ * @returns 
  */
-function slideObjectToXml(slide: PresSlide | SlideLayout): string {
-	let strSlideXml: string = slide._name ? '<p:cSld name="' + slide._name + '">' : '<p:cSld>'
-	let intTableNum: number = 1
-
-	// STEP 1: Add background
-	if (slide.bkgd) {
-		strSlideXml += genXmlColorSelection(null, slide.bkgd)
-	} else if (!slide.bkgd && slide._name && slide._name === DEF_PRES_LAYOUT_NAME) {
-		// NOTE: Default [white] background is needed on slideMaster1.xml to avoid gray background in Keynote (and Finder previews)
-		strSlideXml += '<p:bg><p:bgRef idx="1001"><a:schemeClr val="bg1"/></p:bgRef></p:bg>'
-	}
-
-	// STEP 2: Add background image (using Strech) (if any)
-	if (slide._bkgdImgRid) {
-		// FIXME: We should be doing this in the slideLayout...
-		strSlideXml +=
-			'<p:bg>' +
-			'<p:bgPr><a:blipFill dpi="0" rotWithShape="1">' +
-			'<a:blip r:embed="rId' +
-			slide._bkgdImgRid +
-			'"><a:lum/></a:blip>' +
-			'<a:srcRect/><a:stretch><a:fillRect/></a:stretch></a:blipFill>' +
-			'<a:effectLst/></p:bgPr>' +
-			'</p:bg>'
-	}
-
-	// STEP 3: Continue slide by starting spTree node
-	strSlideXml += '<p:spTree>'
-	strSlideXml += '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
-	strSlideXml += '<p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/>'
-	strSlideXml += '<a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>'
-
-	// STEP 4: Loop over all Slide.data objects and add them to this slide
-	slide._slideObjects.forEach((slideItemObj: ISlideObject, idx: number) => {
+function slideItemObjsToXml(slideItemObjs: ISlideObject[], slide: PresSlide | SlideLayout): { str: string, containerX: number, containerY: number, containerCx: number, containerCy: number } {
+	let strSlideXml = ''
+	let intTableNum = 1
+	let containerX = Infinity
+	let containerY = Infinity
+	let containerCx = 0
+	let containerCy = 0
+	slideItemObjs.forEach((slideItemObj: ISlideObject, idx: number) => {
 		let x = 0,
 			y = 0,
 			cx = getSmartParseNumber('75%', 'X', slide._presLayout),
@@ -142,6 +117,11 @@ function slideObjectToXml(slide: PresSlide | SlideLayout): string {
 		if (typeof slideItemObj.options.w !== 'undefined') cx = getSmartParseNumber(slideItemObj.options.w, 'X', slide._presLayout)
 		if (typeof slideItemObj.options.h !== 'undefined') cy = getSmartParseNumber(slideItemObj.options.h, 'Y', slide._presLayout)
 
+		containerX = Math.min(containerX, x)
+		containerY = Math.min(containerY, y)
+		containerCx = Math.max(containerCx, cx)
+		containerCy = Math.max(containerCy, cy)
+
 		// If using a placeholder then inherit it's position
 		if (placeholderObj) {
 			if (placeholderObj.options.x || placeholderObj.options.x === 0) x = getSmartParseNumber(placeholderObj.options.x, 'X', slide._presLayout)
@@ -660,12 +640,77 @@ function slideObjectToXml(slide: PresSlide | SlideLayout): string {
 				strSlideXml += '</p:graphicFrame>'
 				break
 
+			case SLIDE_OBJECT_TYPES.group:
+				if (slideItemObj.group._slideObjects.length > 0) {
+					const {
+						str: slideItemsXml,
+						containerX: x,
+						containerY: y,
+						containerCx: cx,
+						containerCy: cy
+					} = slideItemObjsToXml(slideItemObj.group._slideObjects, slide)
+					strSlideXml += '<p:grpSp>'
+					strSlideXml += `<p:nvGrpSpPr><p:cNvPr id="${idx + 1}" name="Group"/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>`
+					strSlideXml += `<p:grpSpPr><a:xfrm><a:off x="${x}" y="${y}"/><a:ext cx="${cx}" cy="${cy}"/>`
+					strSlideXml += `<a:chOff x="${x}" y="${y}"/><a:chExt cx="${cx}" cy="${cy}"/></a:xfrm></p:grpSpPr>`
+					strSlideXml += slideItemsXml
+					strSlideXml += "</p:grpSp>"			
+				}
+				break
+
 			default:
 				strSlideXml += ''
 				break
 		}
 	})
+	return {
+		str: strSlideXml,
+		containerX,
+		containerY,
+		containerCx,
+		containerCy,
+	}
+}
+
+/**
+ * Transforms a slide or slideLayout to resulting XML string - Creates `ppt/slide*.xml`
+ * @param {PresSlide|SlideLayout} slideObject - slide object created within createSlideObject
+ * @return {string} XML string with <p:cSld> as the root
+ */
+function slideObjectToXml(slide: PresSlide | SlideLayout): string {
+	let strSlideXml: string = slide._name ? '<p:cSld name="' + slide._name + '">' : '<p:cSld>'
 
+	// STEP 1: Add background
+	if (slide.bkgd) {
+		strSlideXml += genXmlColorSelection(null, slide.bkgd)
+	} else if (!slide.bkgd && slide._name && slide._name === DEF_PRES_LAYOUT_NAME) {
+		// NOTE: Default [white] background is needed on slideMaster1.xml to avoid gray background in Keynote (and Finder previews)
+		strSlideXml += '<p:bg><p:bgRef idx="1001"><a:schemeClr val="bg1"/></p:bgRef></p:bg>'
+	}
+
+	// STEP 2: Add background image (using Strech) (if any)
+	if (slide._bkgdImgRid) {
+		// FIXME: We should be doing this in the slideLayout...
+		strSlideXml +=
+			'<p:bg>' +
+			'<p:bgPr><a:blipFill dpi="0" rotWithShape="1">' +
+			'<a:blip r:embed="rId' +
+			slide._bkgdImgRid +
+			'"><a:lum/></a:blip>' +
+			'<a:srcRect/><a:stretch><a:fillRect/></a:stretch></a:blipFill>' +
+			'<a:effectLst/></p:bgPr>' +
+			'</p:bg>'
+	}
+
+	// STEP 3: Continue slide by starting spTree node
+	strSlideXml += '<p:spTree>'
+	strSlideXml += '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
+	strSlideXml += '<p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/>'
+	strSlideXml += '<a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>'
+
+	// STEP 4: Loop over all Slide.data objects and add them to this slide
+	const { str } = slideItemObjsToXml(slide._slideObjects, slide)
+	strSlideXml += str
 	// STEP 5: Add slide numbers (if any) last
 	if (slide._slideNumberProps) {
 		strSlideXml +=

src/gen-objects.ts

@@ -0,0 +1,110 @@
+import { CHART_NAME, SHAPE_NAME, SLIDE_OBJECT_TYPES } from "./core-enums";
+import { IChartMulti, IChartOpts, IChartOptsLib, ImageProps, ISlideObject, MediaProps, PresSlide, ShapeProps, TableProps, TableRow, TextProps, TextPropsOptions } from "./core-interfaces";
+import * as genObj from './gen-objects'
+
+export class Group {
+    public _slideObjects: ISlideObject[]
+    public _slide: PresSlide
+    public addSlide: Function
+    public getSlide: Function
+
+    constructor(params: {
+        slide: PresSlide
+        addSlide: Function
+        getSlide
+    }) {
+        this._slideObjects = []
+        this._slide = params.slide
+        this.addSlide = params.addSlide
+        this.getSlide = params.getSlide
+    }
+
+    /**
+	 * 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
+	 */
+	addChart(type: CHART_NAME | IChartMulti[], data: any[], options?: IChartOpts): Group {
+		// FUTURE: TODO-VERSION-4: Remove first arg - only take data and opts, with "type" required on opts
+		// Set `_type` on IChartOptsLib as its what is used as object is passed around
+		let optionsWithType: IChartOptsLib = options || {}
+		optionsWithType._type = type
+		genObj.addChartDefinition(this, this._slide, type, data, options)
+		return this
+	}
+
+	/**
+	 * Add image to Slide
+	 * @param {ImageProps} options - image options
+	 * @return {Slide} this Slide
+	 */
+	addImage(options: ImageProps): Group {
+		genObj.addImageDefinition(this, this._slide, options)
+		return this
+	}
+
+	/**
+	 * Add media (audio/video) to Slide
+	 * @param {MediaProps} options - media options
+	 * @return {Slide} this Slide
+	 */
+	addMedia(options: MediaProps): Group {
+		genObj.addMediaDefinition(this, this._slide, options)
+		return this
+	}
+
+	/**
+	 * Add shape to Slide
+	 * @param {SHAPE_NAME} shapeName - shape name
+	 * @param {ShapeProps} options - shape options
+	 * @return {Slide} this Slide
+	 */
+	addShape(shapeName: SHAPE_NAME, options?: ShapeProps): Group {
+		// NOTE: As of v3.1.0, <script> users are passing the old shape object from the shapes file (orig to the project)
+		// But React/TypeScript users are passing the shapeName from an enum, which is a simple string, so lets cast
+		// <script./> => `pptx.shapes.RECTANGLE` [string] "rect" ... shapeName['name'] = 'rect'
+		// TypeScript => `pptxgen.shapes.RECTANGLE` [string] "rect" ... shapeName = 'rect'
+		//let shapeNameDecode = typeof shapeName === 'object' && shapeName['name'] ? shapeName['name'] : shapeName
+		genObj.addShapeDefinition(this, this._slide, shapeName, options)
+		return this
+	}
+
+	/**
+	 * Add table to Slide
+	 * @param {TableRow[]} tableRows - table rows
+	 * @param {TableProps} options - table options
+	 * @return {Slide} this Slide
+	 */
+	addTable(tableRows: TableRow[], options?: TableProps): Group {
+		// FUTURE: we pass `this` - we dont need to pass layouts - they can be read from this!
+		genObj.addTableDefinition(this, this._slide, tableRows, options, this._slide._slideLayout, this._slide._presLayout, this.addSlide, this.getSlide)
+		return this
+	}
+
+	/**
+	 * 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 | TextProps[], options?: TextPropsOptions): Group {
+		let textParam = typeof text === 'string' || typeof text === 'number' ? [{ text: text, options: options } as TextProps] : text
+		genObj.addTextDefinition(this, this._slide, textParam, options, false)
+		return this
+	}
+
+	addGroup(): Group {
+		const group = new Group({
+            slide: this._slide,
+            addSlide: this.addSlide,
+            getSlide: this.getSlide
+        })
+		this._slideObjects.push({
+			_type: SLIDE_OBJECT_TYPES.group,
+			group
+		})
+		return group
+	}
+}

src/gen-xml.ts

@@ -333,6 +333,7 @@ export default class PptxGenJS implements IPresentationProps {
 			addShape: null,
 			addTable: null,
 			addText: null,
+			addGroup: null,
 			//
 			_name: null,
 			_presLayout: this._presLayout,