diff --git a/demo/demo28.ts b/demo/demo28.ts index 1f7f56e2fa..ce545b986c 100644 --- a/demo/demo28.ts +++ b/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); diff --git a/docs/usage/table-of-contents.md b/docs/usage/table-of-contents.md index 6899eae5a7..2f43da4c2f 100644 --- a/docs/usage/table-of-contents.md +++ b/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); diff --git a/src/file/table-of-contents/table-of-contents-instruction.ts b/src/file/table-of-contents/table-of-contents-instruction.ts index b4221b022b..c73a439861 100644 --- a/src/file/table-of-contents/table-of-contents-instruction.ts +++ b/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}"`; } diff --git a/src/file/table-of-contents/table-of-contents-properties.ts b/src/file/table-of-contents/table-of-contents-properties.ts index 8b8c26ec98..21b1c5ec40 100644 --- a/src/file/table-of-contents/table-of-contents-properties.ts +++ b/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; } diff --git a/src/file/table-of-contents/table-of-contents.spec.ts b/src/file/table-of-contents/table-of-contents.spec.ts index 81fcab8616..0d5554fe2b 100644 --- a/src/file/table-of-contents/table-of-contents.spec.ts +++ b/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"; diff --git a/src/file/table-of-contents/table-of-contents.ts b/src/file/table-of-contents/table-of-contents.ts index d84aaa3432..a7fa85f85f 100644 --- a/src/file/table-of-contents/table-of-contents.ts +++ 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));