Inserting MS Word files

Rationale

While Clause9 nudges you into writing clauses that are as reusable as possible, there exist situations where you merely want to insert some static text — e.g., some boilerplate terms & conditions or product descriptions that never get changed.

Similarly, while Clause9 offers you advanced styling controls and real-time updates, Clause9 is not a design tool. As a traditional desktop-based application, MS Word offers a smoother editing experience for layout-heavy documents.

For both scenarios, it can be useful to directly insert one or more pages, or even mere paragraphs or tables, from Microsoft Word into a Clause9 document.

See the separate pages on Copying headers and footers from an MS Word file if you instead want to copy styling or headers/footers from an MS Word file.

How?

First you need to upload an MS Word file to the Clause9 platform. You can do so by going to browse files and creating a new image / pdf / msword file, then uploading a .DOCX file and hitting the save button.

Secondly, within the Clause9 document/binder in which you want to insert the MS Word file, you have to create a clause at the position where the MS Word file needs to be inserted.

Third, within that clause you created, you have to use either the @msword-pages or the @msword-fragment special function. The difference between the two special functions is that the @msword-pages special function always inserts the content on a separate page (using section breaks in MS Word, and including any header/footer of the source document), while the @msword-fragment function inserts the contents without any such separations.

There is also a third version — @msword-pages-own-nrs. This function is identical to @msword-pages, with the single exception that the software will ensure that the inserted MS Word file will have its own numbering style, by ensuring that the names of the list numberings are unique.

By way of background: MS Word internally uses different lists of numberings. If two documents have the same list numbering — usually because they were based on the same template, or otherwise have a shared “ancestor” — then the numbering will continue smoothly when one document is inserted into another. Usually this is what you want, but sometimes not.

The only practical use case within Clause9, is when you would insert a separate Clause9 document (using @insert-document, with the last parameter regarding the separate numbering set to true) into the inserted MS Word file, and you do not want the numbering of the other Clause9 document to follow the numbering of the host document. (After all, two Clause9 documents will almost always share their numbering lists, as the names will be identical.)

Finally, you have to invoke the special function @msword-pages or @msword-fragment, using as a first parameter a #hashtag that refers to the file, and with optional subsequent parameters that refer to replacements using internal snippets. Clause9 will then ask you where this #hashtag should refer to (whereby you have to select the MS Word file you uploaded earlier).

For example, @msword-fragment(#testfile, @ALPHA) would insert the contents of a certain file into the current position of the Clause9 document, replacing the text “@ALPHA” within the MS Word file with whatever contents is assigned to the internal snippet @ALPHA. In addition, as described below, all datafield references inserted into the DOCX-file will get automatically replaced.

Replacements

Datafields

Clause9 will automatically search for text in the MS Word file that follows the #concept^datafield structure. When it finds such text, it will replace that text with the current contents of that datafield (or with an error message, if the specified concept or datafield cannot be found).

For example, in the screenshot below, datafield amount of concept salary will be automatically replaced by the current value of that datafield (presumably a currency-based value).

It is not necessary to highlight the field (as is the case in the screenshot above), but this may help when you — or a colleague — would later on modify the DOCX file.

Any highlight on the datafield will be automatically removed. If you would need to apply highlighting, you will have to use a formatted internal snippet, as described below.

When encountering a concept & datafield within the MS Word file, Clause9 will check all concepts that are currently loaded in the Document/Binder, to see whether it can find a match between the filename (in any language) of the DOCX file and the concept’s name. Next, it will try to match the fieldname with all of the datafields (including their aliases in the relevant language) of the concept that was found.

So if you encounter an error stating that the concept or fieldname was not found, you probably made a typo.

Internal snippets

While simple replacements of datafield values can get you quite far, there will also be situations where you want to modify that datafield value (e.g., convert it to uppercase, or perform a calculation with a number), format in a specific way (e.g., make it bold or italic), insert entire snippets of text instead of mere datafield values, or even insert entire paragraphs or tables.

You therefore also have to the option to replace one or more parts of the MS Word file with Clause9 contents. You do so by simply listing the snippets as the second, third, fourth, … arguments to the special function call. For example:

@msword-fragment(#testfile, @ALPHA, @BETA, @GAMMA)

ALPHA = 
|| some || table || with || four cells ||

BETA = just two words

GAMMA = 
1. A complete paragraph.
* even with a bullet

2. And a second complete paragraph.

In the code above, Clause9 will replace @ALPHA in the MS Word file with a table, @BETA with two words, and @GAMMA with two paragraphs. (The font, location, etc. of those pieces of texts within the MS Word file is irrelevant.)

With this combination of MS Word’s static content and Clause9’s highly dynamic content, you can create quite powerful hybrid documents.

Caveats

• Be aware of extraneous section breaks, page breaks, etc. within your MS Word file. Particularly when you use @msword-pages (which will insert those breaks automatically) you will want to avoid double or triple breaks, as these would lead to blank pages.

• You should be aware that when you replace contents with internal snippets in Clause9 that consist of tables or multiple paragraphs, Clause9’s own styling will get inserted into the document. You probably want to use this feature sparingly, or ensure that the styles of your MS Word file and the styles you use in your Clause9 document, roughly match.

• When you have styles with the same names but different formatting in the inserted document and the surrounding Clause9 Document/Binder — as is quite likely the case for styles Normal, Heading 1, Heading 2, etc. — then the paragraphs that have those styles applied in the inserted document will get “local” formatting applied (because there can obviously not be two differently formatted styles with the same name).

• The @msword-fragment and @msword-pages functions cannot be previewed within the browser. While Clause9 will list the replacements within the preview screen of the browser, you will have to create a PDF-preview of the document (Ctrl-P shortcut, or Shift-clicking the “PDF” button) to see the integrated result.