Manipulate and generate MSWord documents efficiently.  All changes to a document are recorded and only executed when the document is generated.

The library will generate new documents or open and manipulate existing documents.

Note that the underlying library DocX has become free for non-commercial use only in later versions.  So to keep this library available to commercial users, the underlying DocX library will not be upgraded.  This will restrict what functionality may be available.

Operations include

• insert text, optionally specifying color, font, font size, and style (bold/italic/etc),
• replace text via text markers,
• insert text at a bookmark,
• insert bullet points,
• define and insert a table, or tables, at a bookmark,
• insert a picture at a bookmark,
• and a bunch of helper actions to speed up your coding.

Only works with .NET backend. Uses the DocX library from Xceed underneath. Does not support Right to Left text.

Provides a library that abstracts MSWord manipulations from the underlying extension so another extension can replace it in future without changing the library interface.

Table of Contents

• Scenarios
• Actions
• Structures
• Roadmap
• Team Membership Agreement

Scenarios

Scenario 1: Replace Bookmarks (like Mail Merge)

• Open an existing MSWord document containing bookmarks.
• Replace bookmarks with data to be inserted.
• Save the modified as a new document.

Scenario 2: Create a new document

• Create a new MSWord document.
• Insert text, tables and images.
• Save the new document.

Scenario 3: Highlight search terms

• Open an existing MSWord document.
• Search for matching text and highlight text that matches.
• Save the modified document.

Actions

The plugin exposes the following actions.

MSWord_AddHeadersAndFooters

Add headers and footers to the document.

Parameters
InDocument (MSWord_Document) The document to manipulate.
InDifferentFirstPage (Boolean) The headers and footers are different on the first and subsequent pages.
InDifferentOddAndEvenPages (Boolean) The headers and footers are different on odd and even pages.

MSWord_CloseDocument

Release the document reference.  It may not be used again.

Parameters
InDocument (MSWord_Document) The document to close.

MSWord_CreateDocument

Create a new MSWord docx document for editing providing an optional template.

Parameters
InTemplate (BinaryData) The MSWord document to use as a template. May be null.
OutDocument (MSWord_Document) A reference to the document.  Use in other actions to manipulate the document.

MSWord_GenerateDocument

Generate a new MSWord document containing all the edits and return it as binary content.

Parameters
InDocument (MSWord_Document) The document to manipulate.
InClose (Boolean) If true, closes the document
OutContent (Out, BinaryData) The content of the generated MSWord document.

MSWord_HighlightText

Search for text in a document and highlight matching text in the specified colour.

Parameters
InDocument (MSWord_Document) The document to manipulate.
InSearch (Text) Find text matching InSearch
InHighlight (Text) The highlight colour, defaults to "yellow".

MSWord_InsertBulletHierarchy

Helper action to insert a bullet list with items at different levels.

Parameters
InDocument (MSWord_Document) The document to manipulate.
BulletType (Text) "Bullet" or "Number"
Font (Text) The font family
FontSize (Decimal) The font size
InText1 (Text) A bullet point
InLevel1 (Integer) The hierarchy level of the item. Top level = 0, next item = 1, then 2, 3, ...
InText2 (Text) A bullet point
InLevel3 (Integer) The hierarchy level of the item. Top level = 0, next item = 1, then 2, 3, ...
...
InText10 (Text) A bullet point
InLevel10 (Integer) The hierarchy level of the item. Top level = 0, next item = 1, then 2, 3, ...

MSWord_InsertBulletList

Insert a bullet point list.

Parameters
InDocument (MSWord_Document) The document to manipulate.
InTexts (MSWordListItem List) The bullet points
BulletType (Text) "Bullet" or "Number"
Font (Text) The font family
FontSize (Decimal) The font size

MSWord_InsertBulletText

Helper action to insert a bullet point list with a single item

Parameters
InDocument (MSWord_Document) The document to manipulate.
InText (Text) A single bullet point
BulletType (Text) "Bullet" or "Number"
Font (Text) The font family
FontSize (Decimal) The font size

MSWord_InsertBulletText2 .. 10

Helper actions to insert bullet point lists with different numbers of items

Parameters
InDocument (MSWord_Document) The document to manipulate.
BulletType (Text) "Bullet" or "Number"
Font (Text) The font family
FontSize (Decimal) The font size
InText1 .. 10  (Text) A single bullet point

MSWord_InsertFormattedText
Insert formatted text

Parameters
InDocument (MSWord_Document) The document to manipulate.
InText (MSWordText) The text to insert

MSWord_InsertHeading
Insert text as a heading

Parameters
InDocument (MSWordDocument) The document to manipulate.
InLevel (Integer) The heading level 1-9
InText (Text) Text for the heading

MSWord_InsertImage
Insert an image into the document

Parameters
InDocument (MSWordDocument) The document to manipulate.
InImage (BinaryData) The image content to insert into the document as binary data.
InHeight (Integer) The height of the image Ignored if zero.
InWidth (Integer) The width of the image. Ignored if zero.
Alignment (Text) Left, Right or Center.

MSWord_InsertImageInFooter
Insert an image in the footer.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InFooter (Text) The footer, "Odd", "Even" or "First". If empty defaults to "Odd" which is the footer used when there is no separate even/odd or first header/footer.
InImage (BinaryData) The image content to insert into the document as binary data.
InHeight (Integer) The height of the image Ignored if zero.
InWidth (Integer) The width of the image. Ignored if zero.
Alignment (Text) Left, Right or Center.

MSWord_InsertImageInHeader
Insert an image in the header.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InHeader (Text) The footer, "Odd", "Even" or "First". If empty defaults to "Odd" which is the heading used when there is no separate even/odd or first header/footer.
InImage (BinaryData) The image content to insert into the document as binary data.
InHeight (Integer) The height of the image Ignored if zero.
InWidth (Integer) The width of the image. Ignored if zero.
Alignment (Text) Left, Right or Center.

MSWord_InsertInFooter
Insert a paragraph in the footer.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InFooter (Text) The footer, "Odd", "Even" or "First". If empty defaults to "Odd" which is the footer.
InParagraph (MSWordParagraph) The paragraph to insert.

MSWord_InsertInHeader
Insert a paragraph in the header.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InHeader (Text) The footer, "Odd", "Even" or "First". If empty defaults to "Odd" which is the header.
InParagraph (MSWordParagraph) The paragraph to insert.

MSWord_InsertPageBreak
Insert a page break.

Parameters
InDocument (MSWordDocument) The document to manipulate.

MSWord_InsertParagraph
Insert a paragraph.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InParagraph (MSWordParagraph) The paragraph to insert.

MSWord_InsertTable
Insert a table.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InTable (MSWordTable) The table to insert.

MSWord_InsertTables
Inserts multiple tables.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InTables (MSWordTable List) The tables to insert.
InParagraphs (MSWordParagraph List) The paragraphs to insert after tables. The first paragraph, if specified, is added after the first table, the second paragraph, if specified, is added after the second table and so on.

MSWord_InsertText
Insert a paragraph with the specified text content.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText (Text) The text to insert.

MSWord_InsertText2
Insert 2 paragraphs with the specified text content.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (Text) The text to insert.
InText2 (Text) The text to insert.

MSWord_InsertText3
Insert 3 paragraphs with the specified text content.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (Text) The text to insert.
InText2 (Text) The text to insert.
InText3 (Text) The text to insert.

MSWord_InsertText4..8
Helper action to insert 4 to 8 paragraphs with the specified text content.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (Text) The text to insert.
InText2 (Text) The text to insert.
InText3 (Text) The text to insert.
...
InText8 (Text) The text to insert.


MSWord_InsertTextFormat1
Insert formatted text

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText (MSWordText) Text with format options.
SpacingAfter (Decimal) Space after the paragraph
Alignment (Text) Left, Right, Center or Both. Both aligns the paragraph's text to both the left and right margins, adding extra space between the content as necessary.

MSWord_InsertTextFormat2
Insert formatted text

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (MSWordText) Text with format options.
InText2 (MSWordText) Text with format options.
SpacingAfter (Decimal) Space after the paragraph
Alignment (Text) Left, Right, Center or Both. Both aligns the paragraph's text to both the left and right margins, adding extra space between the content as necessary.

MSWord_InsertTextFormat3
Insert formatted text

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (MSWordText) Text with format options.
InText2 (MSWordText) Text with format options.
InText3 (MSWordText) Text with format options.
SpacingAfter (Decimal) Space after the paragraph
Alignment (Text) Left, Right, Center or Both. Both aligns the paragraph's text to both the left and right margins, adding extra space between the content as necessary.

MSWord_InsertTextFormat4..6
Insert formatted text

Parameters
InDocument (MSWordDocument) The document to manipulate.
InText1 (MSWordText) Text with format options.
InText2 (MSWordText) Text with format options.
InText3 (MSWordText) Text with format options.
...
InText6 (MSWordText) Text with format options.
SpacingAfter (Decimal) Space after the paragraph
Alignment (Text) Left, Right, Center or Both. Both aligns the paragraph's text to both the left and right margins, adding extra space between the content as necessary.

MSWord_MakeDecimalList
Make a list of decimals. Useful for creating a list of column width percentages for a table.

Parameters
Decimal1 (Decimal) A decimal number.
Decimal2 (Decimal) A decimal number.
Decimal3 (Decimal) A decimal number.
...
Decimal10 (Decimal) A decimal number.
Decimals (Out, Decimal List) A list of percentage widths of each column. eg 10%, 20%, 50%, 20%.

MSWord_MakeParagraph
Combine text attributes into a paragraph structure

Parameters
Text1 (Text) Text to insert
Text2 (Text) Text to insert
Text3 (Text) Text to insert
...
Text6 (Text) Text to insert
Paragraph (Out, MSWordParagraph) A paragraph structure containing the provided text

MSWord_MakeText
Create an MSWordText structure

Parameters
Text (Text) The text to insert
Font (Text) The font name
FontSize (Decimal) The font size
Color (Text) The text color
Bold (Boolean) Bold text
Italic (Boolean) Italic text
Underline (Boolean) Underline text
Superscript (Boolean) Superscript text
Subscript (Boolean) Subscript text
Caps (Boolean) UPPERCASE text
Smallcaps (Boolean) Small UPPERCASE text
Highlight (Boolean) Highlight text

MSWord_OpenDocument
Open an MSWord docx document for editing. The binary content will not be changed, to retrieve the edits, a new set of binary content will be generated.

Parameters
InContent (BinaryData) An MSWord docx document as binary content.
OutDocument (Out, MSWordDocument) The reference to the document, to be used with other library actions.

MSWord_ReplaceBookmarksWithText
Replace multiple bookmarks with text.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InReplacements (MSWordReplaceWithText List) The replacements to make to the document.

MSWord_ReplaceBookmarkWithImage
Insert an image into the document at the bookmark.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InBookmark (Text) The bookmark where the image will be inserted.
InImage (BinaryData) The image to insert into the document as binary data.
InHeight (Integer) The height of the image Ignored if zero.
InWidth (Integer) The width of the image. Ignored if zero.

MSWord_ReplaceBookmarkWithTable
Replace the bookmark with the table. Removes the paragraph where the bookmark is found.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InBookmark (Text) The name of the bookmark where the table will be inserted.
InTable (MSWordTable) The table to insert

MSWord_ReplaceBookmarkWithTables
Replace the bookmark with multiple tables. Removes the paragraph where the bookmark is found. Optional paragraphs, if specified are added after each table.

Parameters
InDocument (MSWordDocument) The document to manipulate.
InBookmark (Text) The name of the bookmark where the table will be inserted.
InTables (MSWordTable List) The tables to insert
InParagraphs (MSWordParagraph List) The paragraphs to insert after tables. The first paragraph, if specified, is added after the first table, the second paragraph, if specified, is added after the second table and so on.

MSWord_ReplaceBookmarkWithText
Replace a bookmark with text

Parameters
InDocument (MSWordDocument) The document to manipulate.
InBookmarkName (Text) The name of the bookmark where the text will be inserted.
InReplaceText (Text) The text to insert

MSWord_ReplaceText
Replace text in the document

Parameters
InDocument (MSWordDocument) The document to manipulate.
InSearchText (Text) The text to search for.
InReplaceText (Text) The text to insert.

Structures

The plugin exposes the following structures.

MSWordDocument

A reference to the MSWord document to manipulate.

Attributes
Id (Text): The document identifier

MSWordFormat

Text formatting options.

Attributes
Font (Text) The font name
FontSize (Decimal) The font size
Color (Text) The text color
Bold (Boolean) Bold text
Italic (Boolean) Italic text
Underline (Boolean) Underline text
Superscript (Boolean) Superscript text
Subscript (Boolean) Subscript text
Caps (Boolean) UPPERCASE text
Smallcaps (Boolean) Small UPPERCASE text
Highlight (Boolean) Highlight text

MSWordImage

An image to insert

Attributes
Image (BinaryData) The image content
Height (Integer) The height of the image in the document
Width (Integer) The width of the image in the document
Alignment (Text) Left, Right or Center

MSWordParagraph

A paragraph with a list of text items to insert.

Attributes
Texts (List of MSWordText) Text items to insert
Spacing After (Decimal) Space after the paragraph.
Alignment (Text) Left, Right, Center or Both. Both aligns the paragraph's text to both the left and right margins, adding extra space between the content as necessary.
Break (Text) Page break before or after the paragraph. If empty, no break, if "Before", inserts a page break before the paragraph, if "After" inserts a page break after the paragraph.

MSWordReplaceWithPicture
An identifier and image content.

Attributes
Identifier (Text) Identifier, either text or a bookmark where the picture is inserted.
Picture (BinaryData) Image content

MSWordReplaceWithText
An identifier and text for the replacement.

Attributes
Identifier (Text) Identifier, either text or a bookmark where the picture is inserted.
Text (Text) Text to be inserted.

MSWordTable
A table with rows, cells and formatting.

Attributes
Rows (MSWordTableRow List) Rows of the table
Design (MSWordTableDesign Identifier) The table design.
Alignment (Text) Left, Right, or Center.
PercentWidths (Decimal List) A list of percentage widths of each column. eg 10%, 20%, 50%, 20%.
Autofit (Text) Auto fit the table width. "Window" expands the table to the width of the page and autofits the columns. "Contents" shrinks the width of the table to just enough to hold the table contents.
Width (Decimal) Width of the table

MSWordTableCell
A cell in a table, with optional formatting and image.

Attributes
Text (Text) The text for the cell
HyperlinkUrl (Text) Turns the text into a hyperlink with the specified URL.
Colspan (Integer) If greater than 1, the number of columns this cell spans.
Colskip (Integer) If greater than zero, the number of columns to skip before this cell.
Width (Decimal) Width of the cell.
Format (MSWordFormat) Format of the cell text
ListType (Text) The type of the bullet point list, either "Bullet" or "Number". Only used if there are ListItems
ListItems (MSWordListItem List) A list of bullet points to be displayed in the cell. Inserted after the text.
Image (MSWordImage) An image to insert into the cell. Inserted after the text.

MSWordTableRow
A row in a table.

Attributes
Cells (MSWordTableCell List) the row's content
BreakAcrossPages (Boolean) If False, the row will not break across pages. Default = True.
TableHeader (Boolean) True if this is the table header. Default False.
Height (Integer) Height of the row.
MinHeight (Integer) Minimum height of the row.

MSWordText
Text with formatting to insert

Attributes
Text (Text) The text to insert
HyperlinkUrl (Text) If specified, turns the text into a hyperlink with the specified URL
Font (Text) The font name
FontSize (Decimal) The font size
Color (Text) The text color
Bold (Boolean) Bold text
Italic (Boolean) Italic text
Underline (Boolean) Underline text
Superscript (Boolean) Superscript text
Subscript (Boolean) Subscript text
Caps (Boolean) UPPERCASE text
Smallcaps (Boolean) Small UPPERCASE text
Highlight (Boolean) Highlight text

MSWordListItem

A bullet point

Attributes
Text (Text) The bullet point text
Level (Integer) The hierarchy level of the item. Top level = 0, next item = 1, then 2, 3, ...

Entities

MSWordTableDesign
A static entity enumerating MSWord table designs

Roadmap

Note that the underlying library DocX has become free for non-commercial use only in later versions.  So to keep this library available to commercial users, the underlying DocX library will not be upgraded.  This will restrict what functionality may be available.

Next Release

Extract all text from the document in plain text

Add formatting options to individual list items; bold, italic, underline

Fix MSWord_MakeText, the assignment for Highlight is around the wrong way.  Also Highlight should accept hex codes as well as "yellow" and other colour names eg "#ff0000"

Future Releases

-

Investigations

(x) Right to Left text.  The DocX library appears to have some support for RTL text but when tested it does not work.  I tried inserting RTL characters in inserted text as well as setting the paragraph direction to RightToLeft.  Neither of these options worked, so unfortunately this module will not support RTL text.

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules.  If a team member is not able to follow the ground rules, they must leave the team.