Make API simplier with interfaces

demo/demo28.ts

@@ -1,7 +1,7 @@
 // Creates two paragraphs, one with a border and one without
 // Import from 'docx' rather than '../build' if you install from npm
 import * as fs from "fs";
-import { File, Packer, Paragraph, StyleLevel, TableOfContents, TableOfContentsProperties } from "../build";
+import { File, Packer, Paragraph, StyleLevel, TableOfContents } from "../build";
 
 const doc = new File();
 
@@ -18,11 +18,11 @@ doc.Styles.createParagraphStyle("MySpectacularStyle", "My Spectacular Style")
 
 // Let's define the properties for generate a TOC for heading 1-5 and MySpectacularStyle,
 // making the entries be hyperlinks for the paragraph
-const props = new TableOfContentsProperties();
-props.hyperlink = true;
-props.headingStyleRange = "1-5";
-props.stylesWithLevels = [new StyleLevel("MySpectacularStyle", 1)];
-const toc = new TableOfContents("Summary", props);
+const toc = new TableOfContents("Summary", {
+    hyperlink: true,
+    headingStyleRange: "1-5",
+    stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)]
+});
 
 doc.addTableOfContents(toc);
 

docs/usage/table-of-contents.md

@@ -1,6 +1,6 @@
 # Table of Contents
 
-You can generate table of contents with `docx`.
+You can generate table of contents with `docx`. More information can be found [here](http://officeopenxml.com/WPtableOfContents.php).
 
 >Tables of Contents are fields and, by design, it's content is only generated or updated by Word. We can't do it programatically.
 >This is why, when you open a the file, Word you will prompt the message "This document contains fields that may refer to other files. Do you want to update the fields in this document?".
@@ -8,7 +8,19 @@ You can generate table of contents with `docx`.
 
 The complete documentation can be found [here](https://www.ecma-international.org/publications/standards/Ecma-376.htm) (at Part 1, Page 1251).
 
-A short guide can be found [here](http://officeopenxml.com/WPtableOfContents.php).
+## How to
+
+All you need to do is create a `TableOfContents` object and assign it to the document.
+
+```js
+const toc = new TableOfContents("Summary", {
+    hyperlink: true,
+    headingStyleRange: "1-5",
+    stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)]
+});
+
+doc.addTableOfContents(toc);
+```
 
 ## Table of Contents Properties
 
@@ -38,11 +50,11 @@ Here is the list of all properties that you can use to generate your tables of c
 ```js
 // Let's define the properties for generate a TOC for heading 1-5 and MySpectacularStyle,
 // making the entries be hyperlinks for the paragraph
-const props = new TableOfContentsProperties();
-props.hyperlink = true;
-props.headingStyleRange = "1-5";
-props.stylesWithLevels = [new StyleLevel("MySpectacularStyle",1)]
-const toc = new TableOfContents("Summary", props);
+const toc = new TableOfContents("Summary", {
+    hyperlink: true,
+    headingStyleRange: "1-5",
+    stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)]
+});
 
 doc.addTableOfContents(toc);
 

src/file/table-of-contents/table-of-contents-instruction.ts

@@ -1,19 +1,21 @@
 import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
-import { TableOfContentsProperties } from "./table-of-contents-properties";
+import { ITableOfContentsProperties } from "./table-of-contents-properties";
 
 class TextAttributes extends XmlAttributeComponent<{ space: "default" | "preserve" }> {
     protected xmlKeys = { space: "xml:space" };
 }
 
 export class TableOfContentsInstruction extends XmlComponent {
-    private readonly properties: TableOfContentsProperties;
+    private readonly properties: ITableOfContentsProperties;
 
-    constructor(properties?: TableOfContentsProperties) {
+    constructor(properties: ITableOfContentsProperties = {}) {
         super("w:instrText");
-        this.properties = properties || new TableOfContentsProperties();
+
+        this.properties = properties;
 
         this.root.push(new TextAttributes({ space: "preserve" }));
         let instruction = "TOC";
+
         if (this.properties.captionLabel) {
             instruction = `${instruction} \\a "${this.properties.captionLabel}"`;
         }

src/file/table-of-contents/table-of-contents-properties.ts

@@ -16,19 +16,19 @@ export class StyleLevel {
  * Short Guide:
  * http://officeopenxml.com/WPtableOfContents.php
  */
-export class TableOfContentsProperties {
+export interface ITableOfContentsProperties {
     /**
      * \a option - Includes captioned items, but omits caption labels and numbers.
      * The identifier designated by text in this switch's field-argument corresponds to the caption label.
      * Use captionLabelIncludingNumbers (\c) to build a table of captions with labels and numbers.
      */
-    public captionLabel: string;
+    captionLabel?: string;
 
     /**
      * \b option - Includes entries only from the portion of the document marked by
      * the bookmark named by text in this switch's field-argument.
      */
-    public entriesFromBookmark: string;
+    entriesFromBookmark?: string;
 
     /**
      * \c option -  Includes figures, tables, charts, and other items that are numbered
@@ -36,24 +36,24 @@ export class TableOfContentsProperties {
      * field-argument, which corresponds to the caption label, shall match the identifier in the
      * corresponding SEQ field.
      */
-    public captionLabelIncludingNumbers: string;
+    captionLabelIncludingNumbers?: string;
 
     /**
      * \d option - When used with \s, the text in this switch's field-argument defines
      * the separator between sequence and page numbers. The default separator is a hyphen (-).
      */
-    public sequenceAndPageNumbersSeparator: string;
+    sequenceAndPageNumbersSeparator?: string;
 
     /**
      * \f option - Includes only those TC fields whose identifier exactly matches the
      * text in this switch's field-argument (which is typically a letter).
      */
-    public tcFieldIdentifier: string;
+    tcFieldIdentifier?: string;
 
     /**
      * \h option - Makes the table of contents entries hyperlinks.
      */
-    public hyperlink: boolean;
+    hyperlink?: boolean;
 
     /**
      * \l option - Includes TC fields that assign entries to one of the levels specified
@@ -61,14 +61,14 @@ export class TableOfContentsProperties {
      * where startLevel and endLevel are integers, and startLevel has a value equal-to or less-than endLevel.
      * TC fields that assign entries to lower levels are skipped.
      */
-    public tcFieldLevelRange: string;
+    tcFieldLevelRange?: string;
 
     /**
      * \n option - Without field-argument, omits page numbers from the table of contents.
      * Page numbers are omitted from all levels unless a range of entry levels is specified by
      * text in this switch's field-argument. A range is specified as for \l.
      */
-    public pageNumbersEntryLevelsRange: string;
+    pageNumbersEntryLevelsRange?: string;
 
     /**
      * \o option -  Uses paragraphs formatted with all or the specified range of builtin
@@ -77,20 +77,20 @@ export class TableOfContentsProperties {
      * to the style with a style ID of HeadingX (e.g. 1 corresponds to Heading1).
      * If no heading range is specified, all heading levels used in the document are listed.
      */
-    public headingStyleRange: string;
+    headingStyleRange?: string;
 
     /**
      * \p option - Text in this switch's field-argument specifies a sequence of characters
      * that separate an entry and its page number. The default is a tab with leader dots.
      */
-    public entryAndPageNumberSeparator: string;
+    entryAndPageNumberSeparator?: string;
 
     /**
      * \s option - For entries numbered with a SEQ field (§17.16.5.56), adds a prefix to the page number.
      * The prefix depends on the type of entry. text in this switch's field-argument shall match the
      * identifier in the SEQ field.
      */
-    public seqFieldIdentifierForPrefix: string;
+    seqFieldIdentifierForPrefix?: string;
 
     /**
      * \t field-argument Uses paragraphs formatted with styles other than the built-in heading styles.
@@ -98,25 +98,25 @@ export class TableOfContentsProperties {
      * with each doublet being a comma-separated set of style name and table of content level.
      * \t can be combined with \o.
      */
-    public stylesWithLevels: StyleLevel[];
+    stylesWithLevels?: StyleLevel[];
 
     /**
      * \u Uses the applied paragraph outline level.
      */
-    public useAppliedParagraphOutlineLevel = false;
+    useAppliedParagraphOutlineLevel?: boolean;
 
     /**
      * \w Preserves tab entries within table entries.
      */
-    public preserveTabInEntries = false;
+    preserveTabInEntries?: boolean;
 
     /**
      * \x Preserves newline characters within table entries.
      */
-    public preserveNewLineInEntries = false;
+    preserveNewLineInEntries?: boolean;
 
     /**
      * \z Hides tab leader and page numbers in web page view (§17.18.102).
      */
-    public hideTabAndPageNumbersInWebView = false;
+    hideTabAndPageNumbersInWebView?: boolean;
 }

src/file/table-of-contents/table-of-contents.spec.ts

@@ -1,7 +1,7 @@
 import { expect } from "chai";
 
 import { Formatter } from "../../export/formatter";
-import { StyleLevel, TableOfContents, TableOfContentsProperties } from "./";
+import { ITableOfContentsProperties, StyleLevel, TableOfContents } from "./";
 
 describe("Table of Contents", () => {
     describe("#constructor", () => {
@@ -12,7 +12,7 @@ describe("Table of Contents", () => {
         });
 
         it("should construct a TOC with all the options and alias", () => {
-            const props = new TableOfContentsProperties();
+            const props: ITableOfContentsProperties = {};
 
             props.captionLabel = "A";
             props.entriesFromBookmark = "B";

src/file/table-of-contents/table-of-contents.ts

@@ -5,10 +5,10 @@ import { XmlComponent } from "file/xml-components";
 import { SdtContent } from "./sdt-content";
 import { SdtProperties } from "./sdt-properties";
 import { TableOfContentsInstruction } from "./table-of-contents-instruction";
-import { TableOfContentsProperties } from "./table-of-contents-properties";
+import { ITableOfContentsProperties } from "./table-of-contents-properties";
 
 export class TableOfContents extends XmlComponent {
-    constructor(alias: string = "Table of Contents", properties?: TableOfContentsProperties) {
+    constructor(alias: string = "Table of Contents", properties?: ITableOfContentsProperties) {
         super("w:sdt");
         this.root.push(new SdtProperties(alias));