mergeDOCX

Brings the content of a DOCX document at the end of another DOCX document's content. The result of this merging process will be the document defined with the base attribute, with the content of the document defined with the appendix attribute placed after the existing content. Styles, headers and footers used in the appendix document's content are part of the merging process as well, but how exactly they are handled is configured with the attributes renameConflictingStyles and inheritHeadersFooters.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the combined document File as its value.

base
Required	Value type	EL-evaluated
Yes	File	Yes
Defines the document that will be used as the base of the merging process. The resolved File value is expected to be a DOCX document.

appendix
Required	Value type	EL-evaluated
Yes	File	Yes
Defines the document whose content will be added to the end of the base document. The resolved File value is expected to be a DOCX document.

name

Required

Value type

EL-evaluated

No

String

Yes

Defines the name given to the merged document File.

If undefined, the merged document will inherit the name of the base document.

renameConflictingStyles

Required

Value type

EL-evaluated

No

Boolean

No

Defines how the styles of the contents of the DOCX document defined with appendix are handled during the merging process. Any styles used in the appendix's content are brought into the document defined with base alongside the content, but two styles with the same name cannot co-exist in one document. Therefore something needs to be done when the appendix content uses a style that has the same name as a style already in the base document, such as the common built-in style "Normal". This attribute defines what will happen if a style conflict like this occurs.

If the resolved value is true, the conflict is resolved by renaming the conflicting style of the appendix document and then bringing it into the base document. The appendix content using this style is then altered to use the renamed style. This allows the appendix content to retain its original appearance as it is in the appendix document.
If the resolved value is false, the conflict is resolved by discarding the conflicting style. The appendix content will then use the style of that name already existing in the base document.

Regardless of the value of this attribute, any styles used in the appendix content with non-conflicting names are brought in as is.

If undefined, the value of false is used, so no style renaming will occur.

inheritHeadersFooters

Required

Value type

EL-evaluated

No

Boolean

Yes

Defines whether the appendix content will use the headers and footers of the base document, or its own from the appendix document.

If the resolved value is true, the appendix content's section will inherit the header and footer settings of the previous section, that is, the original last section of the base document.
If the resolved value is false, the headers and footers of the appendix document are brought along with the content and the appendix content's section will then use these headers and footers.

If the sectionBreak attribute resolves into "none", the appendix content will not start in its own section and therefore cannot have its own header or footers - in this case the merging process will always behave as if the resolved value of this attribute was true.

If undefined and the resolved value of sectionBreak is not "none", the value of false is used, making the appendix content have its original headers and footers.

sectionBreak

Required

Value type

EL-evaluated

No

String

Yes

Defines what kind of a section break, if any, is inserted between the base document's content and the appendix content. The resolved value should be one of the following Strings:

"nextPage" - The appendix section starts on a new page.
"evenPage" - The appendix section starts on the next even-numbered page.
"oddPage" - The appendix section starts on the next odd-numbered page.
"continuous" - The appendix section starts on the same page as the end of the base document's content.
"none" - No section break is inserted. As the appendix content doesn't get its own section, it cannot have its own headers and footers, and so inheritHeadersFooters will have no effect.

If undefined or if the resolved value is not one of those specified, the value of "nextPage" is used.

Examples

In its simplest form, mergeDOCX only requires the documents to be specified. The appendix content will start on a new page, follow the styles of base document, but have its original headers and footers.

CODE

<mergeDOCX var="merged" base="${baseDocx}" appendix="${otherDocx}">

If you'd like the appendix content to follow the existing content without any kind of page break, set sectionBreak to either "continuous" or "none".

CODE

<mergeDOCX var="merged" base="${composed}" appendix="${someMoreText}" sectionBreak="continuous">

The renameConflictingStyles attribute has a long description, but what it does is actually relatively simple. Let's say that the appendix content contains a paragraph using the style "Normal" that in that document specifies the font as Times New Roman. The base document has the "Normal" style as well, but here the font is set to Calibri. If renameConflictingStyles is undefined or false, the appendix content will continue to use the "Normal" style - now that of the base document's - and so the appendix paragraph will appear in the merged document with its font as Calibri. If renameConflictingStyles is true, the appendix content will instead use the appendix document's "Normal" - renamed into something like "Normalxe57e7821-a42f-41b3-81d7-f09eb5811ca9" - and the paragraph's font will remain as Times New Roman. Leaving the attribute undefined is therefore a good choice if you'd prefer the appendix content to blend with the base content.