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.
The latest version of docx-utils
is hosted on Clojars:
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 templatedocx
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.
The complete API documentation is also available (codox generated).
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"}])
:replacement
could be either aString
or a map. IfString
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 underlyingRun
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.
Copyright © 2017-2019 TokenMill UAB.
Distributed under the MIT License.