Introduction

The DocxToolBx DLL functions library is used to manipulate Word documents in Office 2007 and later format (OpenXML WordprocessingML).

It is used to fully create a basic document and manage mailshots by automatically completing merger field and report generation values, etc.

This library is available for Visual Adelia, Adelia Web and Adelia Cloud.

Limitations

DocxToolBx can statically manipulate a document but is not able to render or run script code.

For example, it is not possible to evaluate the result of a function call in an array or know the current page number for a given position in the document. To do this, you need to explicitly open the document in Word and select the "Update fields" option.

This means that if you export a document in PDF format, it is possible that the dynamic fields are not up to date.

Configuration

DocxToolBx is available for Visual Adelia, Adelia Web and Adelia Cloud. It is based on a Java OpenXML DOCX4J document manipulation library (http://www.docx4java.org/trac/docx4j).

The Windows version of the library is in fact implemented in the form of a proxy using the Adelia client/server to directly call the Java version via Middleware services.

Caution: if you create a blank document without specifying a model, the toolbox tries to find the template file "Normal.dotm" in the application's CLASSPATH and if it is not there, in the user's installation if the application is running on Windows and Office is installed. If the file is not found, a blank document is created with minimal settings and styles in English.

You can get round this problem by deploying your version of the "Normal.dotm" file in your application's CLASSPATH (either in the JAVARUN directory of the documentation server or in the WEB-INF\lib directory of a Web application).

Configuration for the Java version

Concerns Adelia Web, Adelia Cloud, Event Adelia and Visual Adelia versions generated in Java. DocxToolBx is natively supported in this configuration. No action is required to put it in place.

However, the library used takes up a relatively large amount of memory and is best to increase the available memory space to manipulate large documents (parameters -Xms and -Xmx, recommended values -Xms256m -Xmx1024m for JVM 32bits).

Configuration for the Windows version

Concerns Visual Adelia programs generated in C. In this configuration, the program uses a Middleware service using the logical server *DOC_SERVER.

You need to configure this logical server in your client configuration. The physical server must point to a Java daemon.

Caution: if processing is moved, the file names (open and save functions) will be relative to the server.

Use

This section describes how the DocxToolBx library works as well as the notions of handles (object references) and document parts (DocumentPart).

Object handle

A handle is a reference to an object which can be manipulated by the toolbox. It is represented in an Adelia program by a NUM_BIN_4-type numerical value.

A handle can represent the document itself, a document part, a paragraph, etc.

All the DocxToolBx manipulation functions take as a parameter the handle of the object to which they apply.

Once you have finished manipulating an object, you need to explicitly close the associated handle to release the resources via the UtiCloseHandle function (or DocClose function for a document handle).

Special case: when you close an object handle, any handles corresponding to its child objects are automatically closed. If there is a handle on a table as well as handles on its cells, the cell handles will be implicitly released if I release the table handle.

Closing a document releases all the associated resources.

Caution: the numerical value of a handle is likely to be re-used after closing it.

For example, opening and closing a document:

CALL_DLL 'DocxToolBx' 'DocOpen' fileName documentHandle rc

CALL_DLL 'DocxToolBx' 'DocClose' documentHandle rc

Document part

An OpenXML document is in fact made up of a tree of directories containing files, particularly XML files describing the different components of the Word document (document text, style definition, parameters, etc.). A document part is a file which is part of this tree.

DocToolBx only makes it possible to directly manipulate document parts which can contain text (paragraphs, tables) such as the main part of the document and the sub-parts which are accessible from it (page headers and footers, etc.). Others can be manipulated indirectly (styles, parameters, etc.).

DocxToolBx incorrectly references any container which may contain paragraphs of text as a "document part". For example, even if in the terminology a table cell is not really a "document part", it may contain paragraphs and therefore be analyzed by management functions such as PartCountParagraphs.

A program's first operation is to get the handle of the main part of the document, from which we can start to manipulate the document.

CALL_DLL 'DocxToolBx' 'DocGetMainDocumentPart' handleDocument handleMainPart rc

...

Document manipulation

Once you have the handle of the main part of the document, it is possible to manipulate it.

The following code inserts two paragraphs at the top of a blank document. The first is created at the top of the main part of the document and the second after the first:

CALL_DLL 'DocxToolBx' 'DocCreate' *BLANK handleDocument rc

CALL_DLL 'DocxToolBx' 'DocGetMainDocumentPart' handleDocument handleMainPart rc

CALL_DLL 'DocxToolBx' 'ParagraphInsert' handleMainPart _DOCX_POS_FIRST 0 'Normal' 'Hello everybody' handlePara1 rc

CALL_DLL 'DocxToolBx' 'ParagraphInsert' handleMainPart _DOCX_POS_AFTER handlePara1 'Normal' 'Goodbye' handlePara2 rc

CALL_DLL 'DocxToolBx' 'UtiCloseHandle' handlePara2 rc

CALL_DLL 'DocxToolBx' 'UtiCloseHandle' handlePara1 rc

CALL_DLL 'DocxToolBx' 'UtiCloseHandle' handleMainPart rc

CALL_DLL 'DocxToolBx' 'DocClose' handleDocument rc

Classes

The DocxToolBx functions are grouped into classes defined by the function's scope of application.

The different classes are listed in the table below:

Classe	Description
Doc	This class provides document management functions.
Part	This class provides document part management functions.
Paragraph	This class provides management functions for paragraphs of text and text sub-elements of these paragraphs.
Table	This class provides table management functions.
Row	This class provides row management functions.
Cell	This class provides table cell management functions.
Bookmark	This class provides bookmark management functions.
Field	This class provides merge field management utility functions.
Image	This class provides image management functions.
Section	This class provides section management functions.
Style	This class provides text style and properties management functions.
Break	This class provides management functions for page and section breaks.
Uti	This class provides general utility functions and debugging tools.