Here’s a single A4 page reference/overview of docx4j aka a cheat sheet, in PDF or PNG format.

This one is focused on docx files (WordprocessingML).

I’ll create something similar for pptx and xlsx over coming days.

Just launched is http://webapp.docx4java.org

You should be able to see it in the menu at the top right of this website (if not, reload the web page…).

There are three things you can do with it right now:

• Explore your docx/pptx/xlsx and its representation in docx4j

• Convert  docx to PDF or XSL FO

• Merge docx files (eg cover letter plus contract) into a single docx, using Plutext’s MergeDocx. Or the same thing for pptx files, using MergePptx.

Here I want to focus on the first of these.

After you’ve uploaded your docx/pptx/xlsx, the first thing you see is like docx4j’s PartsList sample:

Here, I’ll click in the left hand column to look at the main document part, document.xml

When I do that, I see the XML:

No surprises there.

But notice the hyperlinks.  Here I’ll just click on the first w:p.

What you get back, is Java source code to create that complete structure:-

As you can see from the image above, both styles of code (as described in docx4j’s Getting Started document) are produced for you.  With a bit of luck, you can cut/paste either into your IDE (Eclipse or whatever), and just run with it!

To actually see the created object in an Office document, you’ll still need to add the created object to a part.  See Getting Started, or the cheat sheet for how to do that.

I hope this helps you to create/modify your Office documents more efficiently,with docx4j!

Do let us know what you think in the comments, or in docx4j’s forums.

I’m pleased to say that docx4j 2.8.0 is now released.

What is docx4j?

docx4j is an open source (Apache v2) library for working with docx, pptx, and xslx files, based around  JAXB.

What’s new?

The headline feature is XHTML import.  docx4j can convert XHTML to Word document content, formatting it based on the CSS.  Images and tables are supported. See the ConvertInXHTMLDocument and ConvertInXHTMLFragment samples.

Where do you get it?

See our downloads page or:

Binaries: You can download a jar alone or a zip with all deps or pick and choose.  If you’re upgrading from 2.7.1, you need the  docx4j jar and:

• for XHTML importing, xhtmlrenderer-1.0.0.jar and itext-2.1.7.jar
• for PDF output, jaxb-xslfo-1.0.1.jar (now a separate project)
• for pptx conversion to SVG: jaxb-svg11-1.0.2.jar (now a separate project)
• for digitally signed documents, jaxb-xmldsig-core-1.0.0.jar (new)

Source: the source code is on GitHub at https://github.com/plutext/docx4j; here’s how to setup docx4j source code

Maven: docx4j 2.8.0 is in Maven Central.  Here is a guide to getting started (where it says 2.7.1, just use 2.8.0).

Getting Started

See the “Getting Started” guide, in html docx or pdf flavours.

There is lots of sample code here (freshly reviewed for 2.8.0).

Support

If you are looking for help (and have read the Getting Started Guide ), you can post in our forums, or on Stack Overflow (where there is a docx4j tag).

Thanks to our contributors

A number of contributions have made this release what it is; thanks very much to those who contributed.

Contributors to this release and a more complete list of changes may be found in README.txt

Thanks also to those who have +1′d pages on this website, or tweeted or blogged about docx4j, which is critical to expanding the docx4j community!

docx4j is now on GitHub!  https://github.com/plutext/docx4j

This should make it easier for users to maintain their own branches (public or private), and contribute improvements back.

As of now, GitHub is the project’s authoritative version control.  We’re no longer updating the existing svn repository.

Its pretty easy to work with docx4j sources in Eclipse. This post shows you how.

First, make sure you have eGit installed in Eclipse.  Install it from here.  On Windows, it is also useful to have msysgit.  Refer elsewhere for how to set these up. Update: there is a GitHub Windows client now (I haven’t tried it) which apparently includes msysgit.

You also need m2eclipse

Assuming you’ve done all that, setting up the docx4j source code is just a few steps.

But first, be aware there is a difference between cloning and forking.  Cloning gives you a copy of the source code you can work on, but without more, no easy way to contribute changes back.  Forking sets you up with the source code, and makes it easy to contribute changes back.

If you think you might be making changes to the docx4j source code, you’re probably best to create a fork on GitHub right from the start.

Step 1 (optional, but recommended): To create a fork, log in to GitHub, visit https://github.com/plutext/docx4j then press the “Fork” button.

Step 2: Create your local repository (git clone)

This can be done from within Eclipse, or using Git Gui (easiest), or Git Bash Shell.

To do it from within Eclipse, File > Import .. > Repositories from GitHub:

If you forked docx4j, find your fork (it might not appear immediately, which is why Git Gui or Git Bash Shell are better for this step), select it, and click next.

If you didn’t fork docx4j, type ‘docx4j’ then press ‘search’, the plutext/docxj repository should come up:

Select plutext/docx4j, then click next.

This creates a local git repository on your computer.

Step 3: Now you need to import that repository into Eclipse as a project:

File > Import .. > Projects from Git

Eclipse should find the existing project settings:

(If it didn’t and you had to use the new projects wizard; be sure to set the file location to wherever your git repository is, rather than letting Eclipse create a new empty project in the workspace)

Now you should have a docx4j project in Eclipse, and it should be properly configured (since the project settings come with the project).

You should be done. But if something isn’t right, you can configure it manually (see further below).

Next steps?  Improve the docx4j source code in Eclipse , then Team > Commit, to commit those changes to your local repository.

Made a change which would be useful to others?  If you forked docx4j as per step 1 above, you can push your changes to your repository on GitHub, then send a pull request.

If you didn’t fork docx4j, do that now on GitHub, then configure things locally to push your changes to your repository on GitHub, then you’ll be right to push your changes to your repository on GitHub, then send a pull request.  Other docx4j users will thank you for this

Manual configuration:

Configure > Convert to Maven Project

Properties > Java Compiler > Compiler compliance level: change to 1.6

Java Build Path > Libraries: remove 1.5 system library; Add Library … JRE System Library .. 1.6

Java Build Path > Source: check none of the entries say “Excluded: **” (remove the exclusion)

A customer asked me to prepare a sample Android project which converts docx to HTML.

The result is AndroidDocxToHtml

Since docx4j relies heavily on JAXB, the key to getting it working was getting JAXB – the reference implementation – to run on Android.

Android presents us with a number of challenges:

1. it won’t let you add a jar which includes classes in the javax.xml namespace (which is where the JAXB API lives)
2. JAXB uses JAXP 1.3 DatatypeFactory, but Android doesn’t provide it
3. JAXB uses javax.activation.DataHandler
4. Dalvik has a limit of 65536 method references per dex file
5. it doesn’t support package level annotations (which JAXB uses, and which in docx4j supply namespaces)

Ill-advised or mistaken usage of a core class (java.* or javax.*)

You’ll get this message if you try to add a jar containing classes in java.* or the following javax packages:

Android doesn’t provide javax.xml.bind, and it won’t let you add it yourself.  It forces you to re-package it.  Just like on Google AppEngine, until Google eventually added it.

OK, done that; see https://github.com/plutext/jaxb-2_2_5_1/tree/android2 (the 2 in android2 is meaningless)

Repackaging is easy enough; the problem with it is that any library which uses the repackaged code, must also be changed.  In the case of docx4j, this means a new branch, and ongoing maintenance.

JAXB uses JAXP 1.3 DatatypeFactory, but Android doesn’t provide it

com.sun.xml.bind invokes javax.xml.datatype.DatatypeFactory.newInstance, whereupon Android  throws  javax.xml.datatype.DatatypeConfigurationException: Provider org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl not found.

Easy solution: jar it up and provide it.

JAXB uses javax.activation.DataHandler

Easy solution: use the activation and additionnal jars from http://code.google.com/p/javamail-android/downloads/list

Dalvik  limit of 65536 method references per dex file

This is more an issue running docx4j on Android than one related to JAXB, but it is worth noting.  We’re running very close to this limit.  Vote for the issue at http://code.google.com/p/android/issues/detail?id=7147

Also, you may need to give Eclipse more heap space  (symptom is ‘you get Unable to execute dex: Java heap space’).   In eclipse.ini, I used:

-Xms256m

-Xmx4096m

In Eclipse, Windows > Preferences > General > Show Heap Status gives you an entry on the bottom row which is useful.

Just when I thought it would all work…

I found that my XML was not unmarshalling, because it contains namespaces, and for some reason the objects in my JAXB were being read as not having any.

The problem is that Android doesn’t support package annotations: http://code.google.com/p/android/issues/detail?id=16149 (vote), but JAXB needs to read them.  For example:

I ended up devising a simple minded way to tell JAXB about these programmatically.  See Context.java.   Hmmm, I probably should have created my own RuntimeInlineAnnotationReader implementation (Google ‘JAXBIntroductions’).

That done, it more or less works (if you need support for other package level annotations, you’ve got a bit more to do).   The re-packaged JAXB is here.  You can build it using ant -f build-repackaged.xml dist

It should work on Android 3 or 4.

To use it, where your code would otherwise import javax.xml.bind, use ae.java.xml.bind.

There have been a couple of posts on the forum lately regarding adding hyperlinks to other parts of a docx.

This blog post walks you through the generic process for investigating an issue like this.

First, create a sample docx in Word which exhibits the issue of interest.

Here I’m interested in hyperlinks to a heading, and to a bookmark. So see this docx. Second, look inside it (its a zip file). For the link to the heading, document.xml contains a w:p containing:

      <w:hyperlink w:anchor="_My_heading" w:history="1">
        <w:r>
          <w:rPr>
            <w:rStyle w:val="Hyperlink"/>
          </w:rPr>
          <w:t>My heading</w:t>
        </w:r>
      </w:hyperlink>

The heading itself is automatically given a bookmark:

    <w:p>
      <w:pPr>
        <w:pStyle w:val="Heading1"/>
      </w:pPr>
      <w:bookmarkStart w:id="0" w:name="_My_heading"/>
      <w:bookmarkEnd w:id="0"/>
      <w:r>
        <w:t>My heading</w:t>
      </w:r>
    </w:p> 

For the link to my bookmark, Word 2010 used the legacy field formulation:

    <w:p>
      <w:r>
        <w:fldChar w:fldCharType="begin"/>
      </w:r>
      <w:r>
        <w:instrText xml:space="preserve"> HYPERLINK  \l "bm1" </w:instrText>
      </w:r>
      <w:r>
        <w:fldChar w:fldCharType="separate"/>
      </w:r>
      <w:r w:rsidRPr="00D16ABA">
        <w:rPr>
          <w:rStyle w:val="Hyperlink"/>
        </w:rPr>
        <w:t>bm1</w:t>
      </w:r>
      <w:r>
        <w:fldChar w:fldCharType="end"/>
      </w:r>
    </w:p> 

Third, what rels are involved? To answer this, I run the docx through docx4j’s PartsList sample. It shows me that these hyperlinks don’t create any rels. Alternatively, to see this, you could have looked at the rels part when you unzipped the docx.

So we can see that adding an internal hyperlink to a heading requires that it be bookmarked first. Once you have a bookmark, you use a w:hyperlink to refer to the bookmark by name (not id). Doesn’t look like there is any reason to use fields for this.

Here’s a suitable method:

	/**
	 * Create a Hyperlink object, which is suitable for adding to a w:p
	 * @param bookmarkName
	 * @param linkText
	 * @return
	 */
	public static Hyperlink hyperlinkToBookmark(String bookmarkName, String linkText) {

		try {

			String hpl = "<w:hyperlink w:anchor=\"" + bookmarkName + "\" xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" " +
            "w:history=\"1\" >" +
            "<w:r>" +
            "<w:rPr>" +
            "<w:rStyle w:val=\"Hyperlink\" />" +  // TODO: enable this style in the document!
            "</w:rPr>" +
            "<w:t>" + linkText + "</w:t>" +
            "</w:r>" +
            "</w:hyperlink>";

			return (Hyperlink)XmlUtils.unmarshalString(hpl);

		} catch (Exception e) {
			// Shouldn't happen
			e.printStackTrace();
			return null;
		}

	}  

We can test it by altering the BookmarkAdd sample to add a link:

Hyperlink h = MainDocumentPart.hyperlinkToBookmark(bookmarkName, "link to bookmark");
wordMLPackage.getMainDocumentPart().addParagraphOfText("some text").getContent().add(h);

then checking the result opens in Word ok.

That’s all. Added to docx4j in revision 1777.

I’m pleased to announce the release of docx4j 2.7.1.  It was actually released 2 weeks ago, but this announcement has been delayed until I was able to publish the accompanying post on docx4j now being in Maven Central.

What is docx4j?

docx4j is an open source (Apache v2) library for creating, editing, and saving OpenXML “packages”, including docx, pptx, and xslx.  It is similar to Microsoft’s OpenXML SDK, but for Java rather than .NET.   It uses JAXB to create the Java objects out of the OpenXML parts.

Notable features for docx include export as HTML or PDF, and CustomXML databinding for document generation (including our OpenDoPE convention support for processing repeats and conditions).

The docx4j project started in October 2007.

What’s new?

This is mainly a maintenance release; things of note include:

• Preparation for including docx4j in Maven Central
• mc:AlternateContent preprocessor, allowing graceful degradation of Word 2010 specific content
• docx4j.properties, supports configuration of default page size, margins, orientation; also ability to set some of the doc props metadata (Application & AppVersion; dc.creator & dc.lastModifiedBy).
• HtmlExporterNG2,(Pdf)Conversion, SvgExporter: storing any images is delegated to a
  ConversionImageHandler that may be passed as a conversion parameter. Default implementation: DefaultConversionImageHandler
• OpenDoPE changes – see summary post in the sub-forum

Where do you get it?

Binaries: You can download a jar alone or a tar.gz with all deps or pick and choose.

Source: Checkout the source from SVN (use the pom.xml file to satisfy the dependencies eg with m2eclipse as explain in the Maven blog post, or download them from one of the links above)

Maven: From Maven Central; please see the blog post referenced above.

Getting Started

See the “Getting Started” guide.

Thanks to our contributors

A number of contributions have made this release what it is; thanks very much to those who contributed.

Contributors to this release and a more complete list of changes may be found in README.txt

With version 2.7.1, docx4j – a library for manipulating Word docx, Powerpoint pptx, and Excel xlsx xml files in Java – and all its dependencies, are available from Maven Central.

This makes it really easy to get going with docx4j.  With Eclipse and m2eclipse installed, you just add docx4j, and you’re done.  No need to mess around with manually installing jars, setting class paths etc.

This post demonstrates that, starting with a fresh OS (Win 7 is used, but these steps would work equally well on OSX or Linux).

Step 1 – Install the JDK

For the purposes of this article, I used JDK 7, but docx4j works with Java 6 and 1.5.

Step 2 – Install Eclipse Indigo (3.7.1)

I normally download the version for J2EE developers. Unzip it and run eclipse

Step 3 – Install m2eclipse.

In Eclipse, click Help > Install New Software.

Type “http://download.eclipse.org/technology/m2e/releases” in the “Work with” field as shown:

then follow the prompts.

Step 4 – Create your Maven project

In Eclipse, File > New > Project.., then choose Maven project

You should see:

Check “Create a simple project (skip archetype selection)” then press next.

Allocate group and artifact id (what you choose as your artifact id will become the name of your new project in Eclipse):

Press finish

This will create a project with directories using Maven conventions:

(Note: If your starting point is a new or existing Java project in Eclipse, you can right click on the project, then choose Configure > Convert to Maven project)

Step 5 – Add docx4j to your POM

Double Click on pom.xml

Next click on the dependencies tab, then click the “add dependency” button, and enter the docx4j coordinates as shown in the image below:

The result is this pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>mygroup</groupId>
  <artifactId>myartifact</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <dependencies>
  	<dependency>
  		<groupId>org.docx4j</groupId>
  		<artifactId>docx4j</artifactId>
  		<version>2.7.1</version>
  	</dependency>
  </dependencies>
</project>

Ctrl-S to save it.

m2eclipse may take some time to download the dependencies.

When it has finished, you should be able to see them:

Step 6 – Create HelloMavenCentral.java

If you made a Maven project as per step 4 above, you should already have src/main/java on your build path.

If not, create the folder and add it.

Now add a new class:

import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

public class HelloMavenCentral {

	public static void main(String[] args) throws Exception {

		WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.createPackage();

		wordMLPackage.getMainDocumentPart()
			.addStyledParagraphOfText("Title", "Hello Maven Central");

		wordMLPackage.getMainDocumentPart().addParagraphOfText("from docx4j!");

		// Now save it
		wordMLPackage.save(new java.io.File(System.getProperty("user.dir") + "/helloMavenCentral.docx") );

	}
}

Step 7 – Click Run

When you click run, all being well, a new docx called helloMavenCentral.docx will be saved.

You can open it in Word (or anything else which can read docx), or unzip it to inspect its contents.

Step 8 – Adding docx4j.properties

One final thing. If you plan on creating documents from scratch using docx4j, it is useful to set paper size etc, via docx4j.properties. Put something like the following on your path:

# Page size: use a value from org.docx4j.model.structure.PageSizePaper enum
# eg A4, LETTER
docx4j.PageSize=LETTER
# Page size: use a value from org.docx4j.model.structure.MarginsWellKnown enum
docx4j.PageMargins=NORMAL
docx4j.PageOrientationLandscape=false

# Page size: use a value from org.pptx4j.model.SlideSizesWellKnown enum
# eg A4, LETTER
pptx4j.PageSize=LETTER
pptx4j.PageOrientationLandscape=false

# These will be injected into docProps/app.xml
# if App.Write=true
docx4j.App.write=true
docx4j.Application=docx4j
docx4j.AppVersion=2.7.1
# of the form XX.YYYY where X and Y represent numerical values

# These will be injected into docProps/core.xml
docx4j.dc.write=true
docx4j.dc.creator.value=docx4j
docx4j.dc.lastModifiedBy.value=docx4j

#
#docx4j.McPreprocessor=true

# If you haven't configured log4j yourself
# docx4j will autoconfigure it.  Set this to true to disable that
docx4j.Log4j.Configurator.disabled=false

And that’s it. For more information on docx4j, see our Getting Started document.

Please click the +1 button if you found this article helpful.

The source code for the OpenDoPE Word Add-In developer edition is available at last at http://opendope.codeplex.com/

(A binary download has been available for 10 months or so now)

OpenDoPE stands for Open Document Processing Ecosystem; its a standards based approach to document automation / document assembly.

Fundamentally, it is a set of conventions for doing document assembly using Open XML (the ISO-standard Microsoft Word docx file format), specifically, its content control databinding architecture.

Its real attraction is that it enables users to do document production without getting locked in to some vendors’ proprietary file format:- in adopting OpenDoPE, you aren’t making any commitment above and beyond continued use of the docx file format, and a conventional approach to use of its content controls.

For further details, see the OpenDoPE website.

docx4j can combine an XML data file with an OpenDoPE docx template for you; the point of the OpenDoPE Word Add-In is to help your authors with the initial step of creating OpenDoPE docx templates.

The Word Add-In is relatively straightforward; it uses VSTO (Visual Studio Tools for Office).  You’ll need Visual Studio (2010) and basic C# skills to modify it.

The point of releasing the source code is to make it easy for developers to contribute back fixes and enhancements (which has worked really well for docx4j), or extend the Addin to create their own specialised authoring tool.  The source code is in Mercurial, which – because of its distributed nature – should facilitate the latter especially.

The source code for the OpenDoPE Word Add-In (developer edition) is dual licensed, the primary license being GPL v2.

The Add-In is made possible because of the availability of the SharpDevelop “Avalon” and XML editor components.  Thanks guys!

For reasons best known (or only known) to Google, dev.plutext.org has never been on the first page of results when you search for “docx java”, despite all the relevant posts in our forums over more than 3 years.

I can only think Google doesn’t at all like a hostname other than “www”.

So I’ve moved everything to www.docx4java.org

This shouldn’t impact you (other than having to find this new site, and update any bookmarks) unless you are using svn and have docx4j checked out.

If you have the docx4j repository checked out, you’ll want to do something like:

 svn switch --relocate http://dev.plutext.org/svn/docx4j/trunk/docx4j http://www.docx4java.org/svn/docx4j/trunk/docx4j

If you are on Windows and using TortoiseSVN, use Tortoise’s “relocate” command (not its “switch” command).

That should make your SVN checkout work again.

There may be various broken or outdated links on the website.  I guess I’ll fix these over time.

If you encounter any other issues, then please post to http://www.docx4java.org/forums/announces/docx4j-has-a-new-home-t815.html