docx-utils

Library that helps to work with .docx files.

Essentially, it is a Clojure wrapper on Apache POI library.

The main idea is to use plain data instead of Apache POI classes to transform a .docx document.

There are 2 types of transformations: append and replace.

It is possible to append and replace the following data types:

• in-line text;
• paragraph text;
• image;
• table;
• bullet list;
• numbered list.

Latest Version

The latest version of docx-utils is hosted on Clojars:

Main concepts

Main entrance function is docx-utils.core/transform. It has 3 versions:

• 1 argument version takes in a list of transformations, it creates an empty .docx document, applies all transformations and returns a file path of the resulting document. Note that Resulting file is created in a temp folder and it will be deleted after the JVM exits. This function could/should be used to create a template docx document.
• 2 argument version takes in a template-file-path and a list of transformations. It loads the template document applies transformations and returns the resulting document. If the template-file-path is nil then new docx is created and used as a template.
• 3 argument version takes in a template-file-path, output-file-path and a list of transformations. It loads a template document, applies the transformations and stores the resulting document in a file under the output-file-path. If output-file-path is nil then error is thrown.

Note that if a placeholder is not found in the template then nothing happens, only a log warning is produced.

Documentation

The complete API documentation is also available (codox generated).

Examples

To replace a placeholder with a paragraph text:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-text:placeholder"%{PLACEHOLDER}":replacement"Standalone paragraph."}])

To replace a placeholder inside a text paragraph:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-text-inline:placeholder"%{PLACEHOLDER}":replacement"in-lined text"}])

To replace a placeholder with a data table:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-table:placeholder"%{PLACEHOLDER}":replacement [["cell 11""cell 12""cell 13"]
["cell 21""cell 22""cell 23"]]}])

To replace a placeholder with a bulleted list:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-bullet-list:placeholder"%{PLACEHOLDER}":replacement ["item 1""item 2""item 3"]}])

To replace a placeholder with a numbered list:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-numbered-list:placeholder"%{PLACEHOLDER}":replacement ["item 1""item 2""item 3"]}])

To replace a placeholder with an image:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-image:placeholder"%{PLACEHOLDER}":replacement"/path/to/image/file.jpg"}])

To append a text paragraph to the end of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:append-text:replacement"Text paragraph."}])

To append a text snippet to the end of the last paragraph of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:append-text-inline:replacement"text snippet"}])

To append a data table to the end of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:append-table:replacement [["cell 11""cell 12""cell 13"]
["cell 21""cell 22""cell 23"]]}])

To append a bullet list to the end of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:append-bullet-list:replacement ["item a""item b""item c"]}])

To append a numbered list to the end of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:append-numbered-list:replacement ["item a""item b""item c"]}])

To append an image to the end of the template document:

(docx-utils.core/transform"/path/to/template/file.docx"
[{:type:replace-image:replacement"/path/to/image/file.jpg"}])

Future work

• :replacement could be either a String or a map. If String then the value is pasted into the document without any additional formating (the formating of the placeholder is preserved), if a map is provided the underlying Run is formated accordingly to the options provided in a map, e.g. {:bold true :text "Bolded text"}.
• :type value should be somehow taken from a list of values. Maybe a namespace with constants? e.g. (def REPLACE_TEXT :replace-text). Or Java enums?
• expose a Java interface to the library.

License

Copyright © 2017-2019 TokenMill UAB.

Distributed under the MIT License.