Tutorials

Task-driven tutorials and recipes for PageSeeder

How to configure an export publish task for Word / docx

Skills requiredXML, Word
Time required (minutes)15
Intended audienceDeveloper
DifficultyEasy
CategoryDocument

Objectives

This tutorial explains how to set up the Ant file of a Publish task so it uses the Word export configuration to map PSML block labels and inline labels to the Word styles in the target export template. 

To configure the export requires a Word file to use as a template. This document must be formatted using "styles", not direct formatting codes. Any docx file created by Word 2007 or later is fine, dotx will work also. 

Note

The PageSeeder docx export process uses only the formatting, not the content, of the template document. However, it is good practice to consider the template as a public document and ensure that no sensitive information is stored in the document properties, content or headers or footers. 

Tutorial

Configure a publish action

In the document-config.xml, add the following:

<publishing override="false">
  <action type="export">
    <target name="export-review">
      <description>Publish Review to docx file</description>
    </target>
  </action>
</publishing>

Then add a build.xml file to correct path:

/WEB-INF/template/[Project Name]/psml/
review/build.xml

This will add a button to the user interface of the Export page. This button will be labelled 'Publish Review to docx file' and it will be associated with a document type of 'review'.

The Ant target will be export-review.

Options for the target Ant script:

In the build.xml file, it will first load the default PageSeeder configuration parameters

<ps:config />

It will then export the document

<ps:export src="${ps.config.default.uri.path}"             
               dest="${download}" xrefdepth="4">
      <xrefs types="replace,embed,transclude"/>
</ps:export>

The script will then Process the document

<ps:process src="${download}" dest="${process}" stripmetadata="false">
      <xrefs includes="${ps.config.default.uri.filename.no.ext}.psml"
             types="embed,transclude"/>
      <images includes="${ps.config.default.uri.filename.no.ext}.psml"
             src="uriid"
             location="${ps.config.default.working}/docx/prepacked/word/media"/>
    </ps:process>

The Word export template and Word export configuration are then set from a external source:

<property name="override-template"
          value="${xslt.common.folder}/word-export-template-review.docx"/>
<property name="override-configuration"
          value="${xslt.common.folder}/word-export-config-review.xml"/>

The PSML document is then exported to Word / docx format:

<psd:export-docx
   src="${process}/${ps.config.default.uri.filename.no.ext}.psml"
   dest="${ps.config.default.working}/${ps.config.default.uri.filename.no.ext}.docx"
   working="${ps.config.default.working}/docx"
   config="${override-configuration}"
   wordTemplate="${override-template}">   
      <param name="ps.param.manual-core"
          value="Template"/>
</psd:export-docx>

In full, the script should look like this:

<project name="review-docx"
    xmlns:ps="antlib:com.pageseeder.publishapi.ant"
    xmlns:psd="antlib:org.pageseeder.docx.ant"
    xmlns:psp="antlib:org.pageseeder.docx.ant">  
  <import file="../../../../default/ant-library/ant-init.xml" />
  <property name="xslt.common.folder" value="common" />
  <target name="export-review" depends="psinit.clean-working-folder">
    <ps:config />
    <property name="download"     value="${ps.config.default.working}/download" />
    <property name="process"      value="${ps.config.default.working}/process" />
   
    <mkdir dir="${ps.config.default.working}/download"/>
    <mkdir dir="${ps.config.default.working}/process"/>
    <echoxml><progress percent="1" /></echoxml>      
    <echo>Exporting documents from ${ps.config.default.uri.path}</echo>
    <ps:export src="${ps.config.default.uri.path}"             
               dest="${download}" xrefdepth="4">
      <xrefs types="replace,embed,transclude"/>
    </ps:export>
    
    <echoxml><progress percent="50" /></echoxml>
    <ps:process src="${download}"
                dest="${process}"
                stripmetadata="false">
      <xrefs includes="${ps.config.default.uri.filename.no.ext}.psml"
             types="embed,transclude"/>
      <images includes="${ps.config.default.uri.filename.no.ext}.psml"
              src="uriid"
              location="${ps.config.default.working}/docx/prepacked/word/media"/>
    </ps:process>
    
    <property name="override-template"
              value="${xslt.common.folder}/word-export-template-review.docx"/>
    <echo>Using template: ${override-template}</echo>
    <property name="override-configuration"
              value="${xslt.common.folder}/word-export-config-review.xml"/>
    <echo>Using configuration: ${override-configuration}</echo>    
  
    <psd:export-docx src="${process}/${ps.config.default.uri.filename.no.ext}.psml"
             dest="${ps.config.default.working}/${ps.config.default.uri.filename.no.ext}.docx"
                     working="${ps.config.default.working}/docx"
                     config="${override-configuration}"
                     wordTemplate="${override-template}">   
          <param name="ps.param.manual-core"
                      value="Template"/>
    </psd:export-docx>  
    
    <echo>Copy results to session folder</echo>
    <copy todir="${ps-webRoot}/session/${ps-sessionfolder}
                                   ${ps-groupFolderNoPrefix}/export"
    file="${ps.config.default.working}/
                          ${ps.config.default.uri.filename.no.ext}.docx" />  
    <echoxml>   
      <displayUriPath>${ps-engineUrl}/session/${ps-sessionfolder}
                                      ${ps-groupFolderNoPrefix}/export/
           ${ps.config.default.uri.filename.no.ext}.docx</displayUriPath>
    </echoxml>
  </target>
</project>

This Ant script will execute the necessary steps to convert a PSML file into a docx file, using the defined docx template and configuration files.

Created on , last edited on