docx4j Documentation

docx4j is an open source (Apache v2) library for creating, editing, and saving OpenXML "packages", including docx, pptx, and xlsx. It uses JAXB to create the Java representation of these files.

Key Capabilities:

• Open, create, and programmatically manipulate docx, pptx, and xlsx files.
• Document generation via variables, content control data binding, or MERGEFIELD.
• CustomXML binding (supporting pictures, rich text, checkboxes, OpenDoPE extensions for repeats & conditionals, and XHTML importing).
• Export to HTML.
• Export to PDF (using one of three available strategies).
• Produce/consume Word 2007's xmlPackage (pkg) format.
• Apply transforms and common filters.
• Font support including font substitution and use of embedded fonts.

Depending on your requirements, you may choose an alternative to XSL FO for PDF conversion:

• documents4j: Since version 8.2.0, you can use Microsoft Word to perform the conversion.
• via-Microsoft-Graph: Since version 8.2.3, you can use java-docx-to-pdf-using-Microsoft-Graph to perform the conversion via the Microsoft Graph API.

docx4j includes VML (Vector Markup Language) schemas primarily to handle embedded images when saving files as .docx from older Word formats (like Word 2003). The VML implementation in docx4j follows the ECMA 376 1st edition standard.

The VML schema (vml.xsd) integrates with several other namespaces to support different Office applications, including:

• WordprocessingML (wml.xsd)
• Office Relationships (shared-relationshipReference.xsd)
• Excel Spreadsheet Drawing (vml-spreadsheetDrawing.xsd)
• PowerPoint Presentation Drawing (vml-presentationDrawing.xsd)

The Arimo font package provides two ways to use the font depending on your application's support for variable fonts:

1. Variable Fonts: If your application supports variable fonts, use the files containing the wght axis. These files allow you to select intermediate styles between standard weights.

   • Arimo/Arimo-VariableFont_wght.ttf
   • Arimo/Arimo-Italic-VariableFont_wght.ttf

2. Static Fonts: If your application does not support variable fonts, use the individual static files located in the static/ directory:

   • Arimo/static/Arimo-Regular.ttf
   • Arimo/static/Arimo-Medium.ttf
   • Arimo/static/Arimo-SemiBold.ttf
   • Arimo/static/Arimo-Bold.ttf
   • Arimo/static/Arimo-Italic.ttf
   • Arimo/static/Arimo-MediumItalic.ttf
   • Arimo/static/Arimo-SemiBoldItalic.ttf
   • Arimo/static/Arimo-BoldItalic.ttf

To build docx4j from the GitHub repository, use Maven:

mvn clean
mvn install

Note for Windows users: Some tests may fail on Windows. You can skip tests using:

mvn install -DskipTests

Liberation Fonts provide document layout compatibility for fonts like Times New Roman, Arial, and Courier New. To install them, you must first build them from source using fontforge and python fonttools.

1. Get the source

$ git clone https://github.com/liberationfonts/liberation-fonts.git

Or download the tar.gz file from the releases page and extract it:

$ tar zxvf liberation-fonts-[VERSION].tar.gz

2. Build from source

Navigate to the directory and run make. The resulting binary font files will be located in the liberation-fonts-ttf-[VERSION] directory.

$ cd liberation-fonts
$ make

3. System Installation (Fedora example)

• User-wide: Copy the TTF files to ~/.fonts.
• System-wide: Copy the TTF files to /usr/share/fonts/liberation.
• Refresh cache: Run fc-cache to register the new fonts.

docx4j v11.4.5 uses Jakarta XML Binding API 3.0.

Migration Note: Because this version uses jakarta.xml.bind instead of the older javax.xml.bind, you must perform a search-and-replace in your codebase to update all javax.xml.bind imports to jakarta.xml.bind. Maven will automatically handle the replacement of JAXB jars.

To run the samples without Maven, you must manually ensure the following dependencies are in your classpath:

1. The Documents4j local JAR files and the docx4j-documents4j-local JAR (included in the provided zip).
2. docx4j and its dependencies (provided in the separate community zip).
3. A JAXB implementation, such as docx4j-JAXB-ReferenceImpl or MOXy, unless your Java runtime already ships with JAXB.

To use Arimo fonts in your project:

1. Install the specific font files you intend to use (either the variable .ttf files or the static .ttf files from the static/ folder).
2. Use your application's font picker to access the Arimo font family and its available styles.

By default, docx4j requires a JAXB implementation to function. If you want docx4j to use the official JAXB Reference Implementation (RI), you must add the docx4j-JAXB-ReferenceImpl JAR to your project's classpath.

This implementation is automatically detected because the jaxb-runtime-4.0.5.jar (or similar versions) contains the service provider configuration in META-INF/services/jakarta.xml.bind.JAXBContextFactory pointing to org.glassfish.jaxb.runtime.v2.JAXBContextFactory.