Merge pull request #237 from dolanmiu/feat/image-wrap

Merge 4.6.0 into master

demo/demo38.ts

@@ -0,0 +1,44 @@
+// Example of how to add images to the document - You can use Buffers, UInt8Arrays or Base64 strings
+// Import from 'docx' rather than '../build' if you install from npm
+import * as fs from "fs";
+// import { Document, Packer, Paragraph } from "../build";
+import { Document, Packer, TextWrappingSide, TextWrappingType } from "../build";
+
+const doc = new Document();
+
+doc.createParagraph(
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vehicula nec nulla vitae efficitur. Ut interdum mauris eu ipsum rhoncus, nec pharetra velit placerat. Sed vehicula libero ac urna molestie, id pharetra est pellentesque. Praesent iaculis vehicula fringilla. Duis pretium gravida orci eu vestibulum. Mauris tincidunt ipsum dolor, ut ornare dolor pellentesque id. Integer in nulla gravida, lacinia ante non, commodo ex. Vivamus vulputate nisl id lectus finibus vulputate. Ut et nisl mi. Cras fermentum augue arcu, ac accumsan elit euismod id. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Sed ac posuere nisi. Pellentesque tincidunt vehicula bibendum. Phasellus eleifend viverra nisl.",
+);
+
+doc.createParagraph(
+    "Proin ac purus faucibus, porttitor magna ut, cursus nisl. Vivamus ante purus, porta accumsan nibh eget, eleifend dignissim odio. Integer sed dictum est, aliquam lacinia justo. Donec ultrices auctor venenatis. Etiam interdum et elit nec elementum. Pellentesque nec viverra mauris. Etiam suscipit leo nec velit fringilla mattis. Pellentesque justo lacus, sodales eu condimentum in, dapibus finibus lacus. Morbi vitae nibh sit amet sem molestie feugiat. In non porttitor enim.",
+);
+
+doc.createParagraph(
+    "Ut eget diam cursus quam accumsan interdum at id ante. Ut mollis mollis arcu, eu scelerisque dui tempus in. Quisque aliquam, augue quis ornare aliquam, ex purus ultrices mauris, ut porta dolor dolor nec justo. Nunc a tempus odio, eu viverra arcu. Suspendisse vitae nibh nec mi pharetra tempus. Mauris ut ullamcorper sapien, et sagittis sapien. Vestibulum in urna metus. In scelerisque, massa id bibendum tempus, quam orci rutrum turpis, a feugiat nisi ligula id metus. Praesent id dictum purus. Proin interdum ipsum nulla.",
+);
+
+doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
+    floating: {
+        horizontalPosition: {
+            offset: 2014400,
+        },
+        verticalPosition: {
+            offset: 2014400,
+        },
+        wrap: {
+            type: TextWrappingType.SQUARE,
+            side: TextWrappingSide.BOTH_SIDES,
+        },
+        margins: {
+            top: 201440,
+            bottom: 201440,
+        },
+    },
+});
+
+const packer = new Packer();
+
+packer.toBuffer(doc).then((buffer) => {
+    fs.writeFileSync("My Document.docx", buffer);
+});

docs/usage/images.md

@@ -56,7 +56,6 @@ Adding images can be done in two ways:
 Three types of image positioning is supported:
 
 -   Floating
--   Wrapped around the text
 -   Inline
 
 By default, picture are exported as `Inline` elements.
@@ -65,7 +64,7 @@ By default, picture are exported as `Inline` elements.
 
 Pass `options` into the `[POSITION_OPTIONS]` metioned in the [Intro above](#Intro).
 
-### Floating
+## Floating
 
 To change the position the image to be on top of the text, simply add the `floating` property to the last argument. By default, the offsets are relative to the top left corner of the `page`. Offset units are in [emus](https://startbigthinksmall.wordpress.com/2010/01/04/points-inches-and-emus-measuring-units-in-office-open-xml/):
 
@@ -97,7 +96,7 @@ const imageData = document.createImage(buffer, 903, 1149, {
 });
 ```
 
-#### Options
+### Options
 
 Full options you can pass into `floating` are:
 
@@ -126,32 +125,83 @@ Full options you can pass into `floating` are:
 | align    | `VerticalPositionAlign`        | You can either have `align` or `offset`, not both | `BOTTOM`, `CENTER`, `INSIDE`, `OUTSIDE`, `TOP`                                                          |
 | offset   | `number`                       | You can either have `align` or `offset`, not both | `0` to `Infinity`                                                                                       |
 
-### Wrap text
+## Wrap text
 
-!> **In progress** Documentation may potentially be changing
+Wrapping only works for floating elements. Text will "wrap" around the floating `image`.
 
-for `drawingOptions.textWrapping` we can define various options. `textWrapping` has the following properties:
+Add `wrap` options inside the `floating` options:
 
-```js
+```ts
-interface TextWrapping {
+wrap: {
-    textWrapStyle: TextWrapStyle;
+    type: [TextWrappingType],
-    wrapTextOption?: WrapTextOption;
+    side: [TextWrappingSide],
-    distanceFromText?: Distance;
+},
-}
+```
 
-enum TextWrapStyle {
+For example:
-    NONE,
-    SQUARE,
-    TIGHT,
-    TOP_AND_BOTTOM,
-}
 
-enum WrapTextOption {
+```ts
-    BOTH_SIDES = "bothSides",
+doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
-    LEFT = "left",
+    floating: {
-    RIGHT = "right",
+        horizontalPosition: {
-    LARGEST = "largest",
+            offset: 2014400,
-}
+        },
+        verticalPosition: {
+            offset: 2014400,
+        },
+        wrap: {
+            type: TextWrappingType.SQUARE,
+            side: TextWrappingSide.BOTH_SIDES,
+        },
+    },
+});
+```
+
+Wrap options have the following properties are:
+
+| Property | Type               | Notes    | Possible Values                             |
+| -------- | ------------------ | -------- | ------------------------------------------- |
+| type     | `TextWrappingType` | Optional | `NONE`, `SQUARE`, `TIGHT`, `TOP_AND_BOTTOM` |
+| side     | `TextWrappingSide` | Optional | `BOTH_SIDES`, `LEFT`, `RIGHT`, `LARGEST`    |
+
+## Margins
+
+Margins give some space between the text and the image. Margins [only work for floating elements](http://officeopenxml.com/drwPicInline.php). Additionally, the image must also be in wrap mode (see above).
+
+?> Be sure to also set `wrap` in your options!
+
+To use, add the `margins` options inside the `floating` options:
+
+```ts
+margins: {
+    top: number,
+    bottom: number,
+    left: number,
+    right: number
+},
+```
+
+For example:
+
+```ts
+doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
+    floating: {
+        horizontalPosition: {
+            offset: 2014400,
+        },
+        verticalPosition: {
+            offset: 2014400,
+        },
+        wrap: {
+            type: TextWrappingType.SQUARE,
+            side: TextWrappingSide.BOTH_SIDES,
+        },
+        margins: {
+            top: 201440,
+            bottom: 201440,
+        },
+    },
+});
 ```
 
 ## Examples
@@ -171,3 +221,11 @@ Example showing how to add image to headers and footers
 [Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo9.ts ":include")
 
 _Source: https://github.com/dolanmiu/docx/blob/master/demo/demo9.ts_
+
+### Floating images
+
+Example showing how to float images on top of text and optimally give a `margin`
+
+[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo38.ts ":include")
+
+_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo38.ts_

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docx",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Generate .docx documents with JavaScript (formerly Office-Clippy)",
   "main": "build/index.js",
   "scripts": {

src/file/drawing/anchor/anchor.spec.ts

@@ -3,7 +3,7 @@ import { assert } from "chai";
 import { Utility } from "tests/utility";
 
 import { IDrawingOptions } from "../drawing";
-import { TextWrapStyle } from "../text-wrap";
+import { TextWrappingType } from "../text-wrap";
 import { Anchor } from "./anchor";
 
 function createAnchor(drawingOptions: IDrawingOptions): Anchor {
@@ -136,9 +136,6 @@ describe("Anchor", () => {
 
         it("should create a Drawing with square text wrapping", () => {
             anchor = createAnchor({
-                textWrapping: {
-                    textWrapStyle: TextWrapStyle.SQUARE,
-                },
                 floating: {
                     verticalPosition: {
                         offset: 0,
@@ -146,6 +143,9 @@ describe("Anchor", () => {
                     horizontalPosition: {
                         offset: 0,
                     },
+                    wrap: {
+                        type: TextWrappingType.SQUARE,
+                    },
                 },
             });
             const newJson = Utility.jsonify(anchor);
@@ -158,9 +158,6 @@ describe("Anchor", () => {
 
         it("should create a Drawing with no text wrapping", () => {
             anchor = createAnchor({
-                textWrapping: {
-                    textWrapStyle: TextWrapStyle.NONE,
-                },
                 floating: {
                     verticalPosition: {
                         offset: 0,
@@ -168,6 +165,9 @@ describe("Anchor", () => {
                     horizontalPosition: {
                         offset: 0,
                     },
+                    wrap: {
+                        type: TextWrappingType.NONE,
+                    },
                 },
             });
             const newJson = Utility.jsonify(anchor);
@@ -179,9 +179,6 @@ describe("Anchor", () => {
 
         it("should create a Drawing with tight text wrapping", () => {
             anchor = createAnchor({
-                textWrapping: {
-                    textWrapStyle: TextWrapStyle.TIGHT,
-                },
                 floating: {
                     horizontalPosition: {
                         offset: 0,
@@ -189,6 +186,9 @@ describe("Anchor", () => {
                     verticalPosition: {
                         offset: 0,
                     },
+                    wrap: {
+                        type: TextWrappingType.TIGHT,
+                    },
                 },
             });
             const newJson = Utility.jsonify(anchor);
@@ -200,9 +200,6 @@ describe("Anchor", () => {
 
         it("should create a Drawing with tight text wrapping", () => {
             anchor = createAnchor({
-                textWrapping: {
-                    textWrapStyle: TextWrapStyle.TOP_AND_BOTTOM,
-                },
                 floating: {
                     verticalPosition: {
                         offset: 0,
@@ -210,6 +207,9 @@ describe("Anchor", () => {
                     horizontalPosition: {
                         offset: 0,
                     },
+                    wrap: {
+                        type: TextWrappingType.TOP_AND_BOTTOM,
+                    },
                 },
             });
             const newJson = Utility.jsonify(anchor);

src/file/drawing/anchor/anchor.ts

@@ -4,7 +4,7 @@ import { XmlComponent } from "file/xml-components";
 import { IDrawingOptions } from "../drawing";
 import { HorizontalPosition, IFloating, SimplePos, VerticalPosition } from "../floating";
 import { Graphic } from "../inline/graphic";
-import { TextWrapStyle, WrapNone, WrapSquare, WrapTight, WrapTopAndBottom } from "../text-wrap";
+import { TextWrappingType, WrapNone, WrapSquare, WrapTight, WrapTopAndBottom } from "../text-wrap";
 import { DocProperties } from "./../doc-properties/doc-properties";
 import { EffectExtent } from "./../effect-extent/effect-extent";
 import { Extent } from "./../extent/extent";
@@ -25,15 +25,22 @@ export class Anchor extends XmlComponent {
         super("wp:anchor");
 
         const floating = {
+            margins: {
+                top: 0,
+                bottom: 0,
+                left: 0,
+                right: 0,
+            },
             ...defaultOptions,
             ...drawingOptions.floating,
         };
+
         this.root.push(
             new AnchorAttributes({
-                distT: 0,
+                distT: floating.margins.top || 0,
-                distB: 0,
+                distB: floating.margins.bottom || 0,
-                distL: 0,
+                distL: floating.margins.left || 0,
-                distR: 0,
+                distR: floating.margins.right || 0,
                 simplePos: "0", // note: word doesn't fully support - so we use 0
                 allowOverlap: floating.allowOverlap === true ? "1" : "0",
                 behindDoc: floating.behindDocument === true ? "1" : "0",
@@ -49,18 +56,18 @@ export class Anchor extends XmlComponent {
         this.root.push(new Extent(dimensions.emus.x, dimensions.emus.y));
         this.root.push(new EffectExtent());
 
-        if (drawingOptions.textWrapping !== undefined) {
+        if (drawingOptions.floating !== undefined && drawingOptions.floating.wrap !== undefined) {
-            switch (drawingOptions.textWrapping.textWrapStyle) {
+            switch (drawingOptions.floating.wrap.type) {
-                case TextWrapStyle.SQUARE:
+                case TextWrappingType.SQUARE:
-                    this.root.push(new WrapSquare(drawingOptions.textWrapping));
+                    this.root.push(new WrapSquare(drawingOptions.floating.wrap, drawingOptions.floating.margins));
                     break;
-                case TextWrapStyle.TIGHT:
+                case TextWrappingType.TIGHT:
-                    this.root.push(new WrapTight(drawingOptions.textWrapping.distanceFromText));
+                    this.root.push(new WrapTight(drawingOptions.floating.margins));
                     break;
-                case TextWrapStyle.TOP_AND_BOTTOM:
+                case TextWrappingType.TOP_AND_BOTTOM:
-                    this.root.push(new WrapTopAndBottom(drawingOptions.textWrapping.distanceFromText));
+                    this.root.push(new WrapTopAndBottom(drawingOptions.floating.margins));
                     break;
-                case TextWrapStyle.NONE:
+                case TextWrappingType.NONE:
                 default:
                     this.root.push(new WrapNone());
             }

src/file/drawing/drawing.ts

@@ -3,7 +3,6 @@ import { XmlComponent } from "file/xml-components";
 import { Anchor } from "./anchor";
 import { IFloating } from "./floating";
 import { Inline } from "./inline";
-import { ITextWrapping } from "./text-wrap";
 
 export interface IDistance {
     readonly distT?: number;
@@ -13,7 +12,6 @@ export interface IDistance {
 }
 
 export interface IDrawingOptions {
-    readonly textWrapping?: ITextWrapping;
     readonly floating?: IFloating;
 }
 

src/file/drawing/floating/floating-position.ts

@@ -1,4 +1,5 @@
 // http://officeopenxml.com/drwPicFloating-position.php
+import { ITextWrapping } from "../text-wrap";
 
 export enum HorizontalPositionRelativeFrom {
     CHARACTER = "character",
@@ -50,6 +51,13 @@ export interface IVerticalPositionOptions {
     readonly offset?: number;
 }
 
+export interface IMargins {
+    readonly left?: number;
+    readonly bottom?: number;
+    readonly top?: number;
+    readonly right?: number;
+}
+
 export interface IFloating {
     readonly horizontalPosition: IHorizontalPositionOptions;
     readonly verticalPosition: IVerticalPositionOptions;
@@ -57,4 +65,6 @@ export interface IFloating {
     readonly lockAnchor?: boolean;
     readonly behindDocument?: boolean;
     readonly layoutInCell?: boolean;
+    readonly margins?: IMargins;
+    readonly wrap?: ITextWrapping;
 }

src/file/drawing/inline/inline-attributes.ts

@@ -1,8 +1,13 @@
 import { XmlAttributeComponent } from "file/xml-components";
 import { IDistance } from "../drawing";
 
-// tslint:disable-next-line:no-empty-interface
+// distT, distB etc have no effect on inline images, only floating
-export interface IInlineAttributes extends IDistance {}
+export interface IInlineAttributes extends IDistance {
+    readonly distT?: number;
+    readonly distB?: number;
+    readonly distL?: number;
+    readonly distR?: number;
+}
 
 export class InlineAttributes extends XmlAttributeComponent<IInlineAttributes> {
     protected readonly xmlKeys = {

src/file/drawing/text-wrap/text-wrapping.ts

@@ -1,14 +1,14 @@
 // http://officeopenxml.com/drwPicFloating-textWrap.php
 import { IDistance } from "../drawing";
 
-export enum TextWrapStyle {
+export enum TextWrappingType {
     NONE,
     SQUARE,
     TIGHT,
     TOP_AND_BOTTOM,
 }
 
-export enum WrapTextOption {
+export enum TextWrappingSide {
     BOTH_SIDES = "bothSides",
     LEFT = "left",
     RIGHT = "right",
@@ -16,7 +16,7 @@ export enum WrapTextOption {
 }
 
 export interface ITextWrapping {
-    readonly textWrapStyle: TextWrapStyle;
+    readonly type: TextWrappingType;
-    readonly wrapTextOption?: WrapTextOption;
+    readonly side?: TextWrappingSide;
-    readonly distanceFromText?: IDistance;
+    readonly margins?: IDistance;
 }

src/file/drawing/text-wrap/wrap-square.ts

@@ -1,10 +1,15 @@
 // http://officeopenxml.com/drwPicFloating-textWrap.php
 import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
-import { ITextWrapping, WrapTextOption } from ".";
+import { ITextWrapping, TextWrappingSide } from ".";
 import { IDistance } from "../drawing";
+import { IMargins } from "../floating";
 
 interface IWrapSquareAttributes extends IDistance {
-    readonly wrapText?: WrapTextOption;
+    readonly wrapText?: TextWrappingSide;
+    readonly distT?: number;
+    readonly distB?: number;
+    readonly distL?: number;
+    readonly distR?: number;
 }
 
 class WrapSquareAttributes extends XmlAttributeComponent<IWrapSquareAttributes> {
@@ -18,13 +23,24 @@ class WrapSquareAttributes extends XmlAttributeComponent<IWrapSquareAttributes>
 }
 
 export class WrapSquare extends XmlComponent {
-    constructor(textWrapping: ITextWrapping) {
+    constructor(
+        textWrapping: ITextWrapping,
+        margins: IMargins = {
+            top: 0,
+            bottom: 0,
+            left: 0,
+            right: 0,
+        },
+    ) {
         super("wp:wrapSquare");
 
         this.root.push(
             new WrapSquareAttributes({
-                wrapText: textWrapping.wrapTextOption || WrapTextOption.BOTH_SIDES,
+                wrapText: textWrapping.side || TextWrappingSide.BOTH_SIDES,
-                ...textWrapping.distanceFromText,
+                distT: margins.top,
+                distB: margins.bottom,
+                distL: margins.left,
+                distR: margins.right,
             }),
         );
     }

src/file/drawing/text-wrap/wrap-tight.ts

@@ -1,6 +1,7 @@
 // http://officeopenxml.com/drwPicFloating-textWrap.php
 import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
-import { IDistance } from "../drawing";
+
+import { IMargins } from "../floating";
 
 interface IWrapTightAttributes {
     readonly distT?: number;
@@ -16,17 +17,17 @@ class WrapTightAttributes extends XmlAttributeComponent<IWrapTightAttributes> {
 
 export class WrapTight extends XmlComponent {
     constructor(
-        distanceFromText: IDistance = {
+        margins: IMargins = {
-            distT: 0,
+            top: 0,
-            distB: 0,
+            bottom: 0,
         },
     ) {
         super("wp:wrapTight");
 
         this.root.push(
             new WrapTightAttributes({
-                distT: distanceFromText.distT,
+                distT: margins.top,
-                distB: distanceFromText.distB,
+                distB: margins.bottom,
             }),
         );
     }

src/file/drawing/text-wrap/wrap-top-and-bottom.ts

@@ -1,6 +1,7 @@
 // http://officeopenxml.com/drwPicFloating-textWrap.php
 import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
-import { IDistance } from "../drawing";
+
+import { IMargins } from "../floating";
 
 interface IWrapTopAndBottomAttributes {
     readonly distT?: number;
@@ -16,17 +17,17 @@ class WrapTopAndBottomAttributes extends XmlAttributeComponent<IWrapTopAndBottom
 
 export class WrapTopAndBottom extends XmlComponent {
     constructor(
-        distanceFromText: IDistance = {
+        margins: IMargins = {
-            distT: 0,
+            top: 0,
-            distB: 0,
+            bottom: 0,
         },
     ) {
         super("wp:wrapTopAndBottom");
 
         this.root.push(
             new WrapTopAndBottomAttributes({
-                distT: distanceFromText.distT,
+                distT: margins.top,
-                distB: distanceFromText.distB,
+                distB: margins.bottom,
             }),
         );
     }

src/file/file.ts

@@ -3,6 +3,7 @@ import { ContentTypes } from "./content-types/content-types";
 import { CoreProperties, IPropertiesOptions } from "./core-properties";
 import { Document } from "./document";
 import {
+    FooterReference,
     FooterReferenceType,
     HeaderReference,
     HeaderReferenceType,
@@ -219,6 +220,32 @@ export class File {
         return headerWrapper;
     }
 
+    public createFirstPageFooter(): FooterWrapper {
+        const footerWrapper = this.createFooter();
+
+        this.document.Body.DefaultSection.addChildElement(
+            new FooterReference({
+                footerType: FooterReferenceType.FIRST,
+                footerId: footerWrapper.Footer.ReferenceId,
+            }),
+        );
+
+        return footerWrapper;
+    }
+
+    public createEvenPageFooter(): FooterWrapper {
+        const footerWrapper = this.createFooter();
+
+        this.document.Body.DefaultSection.addChildElement(
+            new FooterReference({
+                footerType: FooterReferenceType.EVEN,
+                footerId: footerWrapper.Footer.ReferenceId,
+            }),
+        );
+
+        return footerWrapper;
+    }
+
     public getFooterByReferenceNumber(refId: number): FooterWrapper {
         const entry = this.footers.map((item) => item.footer).find((h) => h.Footer.ReferenceId === refId);
         if (entry) {