Skip to main content

 Publishing

Publishing PageSeeder data to print, the Web or both

Microsoft Word DOCX – Export Config

This document explains how to configure PageSeeder to create a .docx-format file from PSML source documents. It is companion technology to the Import Microsoft Word DOCX config usage.

A copy of the default Word export config is available for reference, see the default config example.

Other useful information regarding the docx integration with PageSeeder is available:

Overview

The Microsoft Word Export Config (word-export-config.xml) together with the Word Export Template (word-export-template.dotx) allow PSML data to be converted into the docx format for use with common tools such as Microsoft Word, Google Docs and publishing tools such as Adobe InDesign.

Many features of the Export Config requires administrator rights on the server.

Usage

There are two ways to customize the default config, users can modify it for their own use:

  1. Sign in to PageSeeder and select a project or group.
  2. Select Enable developer mode under Account menu > Preferences.
  3. To change the config for yourself ONLY (This is available to group managers only), go to a document, click the rocket icon in the right sidebar (or from Documents page, under the ellipsis to the right of a document), then Create DocX, +Show more options, then Edit config,
    1. The Member publish configurations page only has one row and applies to all types.

Alternately, the configuration can be changed for every member of the group:

  1. This is available to project managers and administrators only, click Administration menu > Template > Types, note the options under the Publication type table in the Word export column,
  2. To change the configuration for all documents, select override under the default option in the default row.
    1. To revert to the default config, delete your customized default folder on the Administration menu > [Project]Template > Template files. Only available on Types page.
  3. To change the configuration for a specific publication type, click create under Word export column in the row for that type. 

When editing this config file in PageSeeder, pressing ctrl-space displays autocomplete options to make editing easier.

Word export template file

By design, the content of PageSeeder documents has no formatting information attached. As a commonly available, widely-understood tool for formatting documents, Word is an ideal complement to PageSeeder. 

Used in this way, the formatting instructions are stored in a Word template, which is essentially nothing more than a Word document with a slightly different file extension. Because the template is a standard Word document, people familiar with Word can set up the formatting using an application they are comfortable with, instead of having to learn something new.

The only challenge with this model is telling PageSeeder how to map the PSML into the Word styles. Understanding the options for this is the subject of this document. It starts by knowing that “styles” can be applied to:

  • Characters – equivalent to an inline label.
  • Paragraphs – equivalent to a block label.
  • Tables – can be categorized in PageSeeder by the use of the @role attribute.
  • Lists – typically a list style in Word corresponds to headings or block labels in PageSeeder.

The location of the default docx template for a project is:

WEB-INF/config/template/[project-name]/document/psml/
   word-export-template.docx

To customize the Word template, first download the default template from your project on PageSeeder—click the wrench icon in the header bar, then in the main section, click Project template > Types, then in Publication type table, Template column and in the default row, click default.

Modify the styles in Word and save the changes. Then, as outlined above, in the Template column, click upload in the default row (or publication type row).

The Word Export process must have bullet and numbered list styles properly configured. The default template can act as a reference, but users that are not familiar with multi-level list styles in Word will find it easier to modify the already-configured default template than to configure their existing Word template.

Word export config file

The location of the default export config for a project is:

WEB-INF/config/template/[project-name]/
    document/psml/word-export-config.xml

The information below describes different ways that the export config file transforms PSML into DOCX format.

Word allows styles to have multiple names, separated by commas. When configuring the export, use only the name before the first comma. For example, reference this style My heading,Special as follows:

    <level value="1"
       wordstyle="My heading" >

<core>

The element defines how to populate the properties of a Word file from PageSeeder. To see the properties of a docx file, click the Info option under the File menu in Word.

<core>
  <creator select="[ps-current-user]" />
  <description select="[ps-document-description]" />
  <title select="[ps-document-title]" />
  <!-- <modified select="[ps-document-modified]" /> -->
  <created select="[ps-current-date]" />
  <keywordsselect="[ps-document-labels]" />
  <subject select="" />
  <category select="" />
  <version select="1.0" />
  <revision select="1" />
</core>

The export will resolve PageSeeder content into the Word property fields according to the use of the following token values for the @select attributes above.

TokenPageSeeder content
[ps-current-user]The full name of the current user (requires current-user parameter on export task)
[ps-document-description]The PSML document description
[ps-document-title]The PSML document title
[ps-document-created]The PSML document created date
[ps-document-modified]The PSML document modified date
[ps-current-date]The current date
[ps-document-labels]The PSML document labels

The export only uses these values when ‘Config’ is selected in the Document publish panel, in the Choose Word core attributes field, or the manual-core parameter is set to Config:

export-word.png

Two other options are available:

  • The manual editing interface (default option) – manual-core value="Manual".
  • The core values of the template used – manual-core value="Template".

Each of the elements below maps to a Word core attribute as follows:

<creator select="Pageseeder" />
  • <creator>maps to the Author property in Word.
<description select="Pageseeder" />
  • <description>maps to the Comment property in Word.
<subject select="Pageseeder Document" />
  • <subject>maps to the Subject property in Word.
<title select="Default Title" />
  • <title>maps to the Title property in Word.
<category select="No Category" />
  • <category>maps to the Category property in Word.
<version select="1.0" />
  • <version>maps to the Version property in Word.
<revision select="1" />
  • <revision>maps to the Revision property in Word.

<toc> (Table of Contents)

<toc generate="true" style="TOC2" >
  <headings generate="true" select="1-9" />

  <!-- 1|1-2|5-9|etc from 1 up to 9-->
  <outline generate="true" select="1-9" />

  <!-- 1|1-2|5-9|etc from 1 up to 9-->
  <paragraph generate="false">
    <style value="[word style]" indent="[indent level]" />

    <!-- any paragraph style defined in the document
         with the corresponding TOC indent level 
    -->
  </paragraph>
</toc>

Element <toc> is not transformed. It acts as a placeholder for where to insert the Table of Contents field in the exported docx file.

Word can generate a Table of Contents (ToC) using any of the following types of objects. These value cannot be mixed. For example, the export will not support the creation of a single ToC that combines headings and outline values:

  • <headings> – these are the native Word styles numbered 1 to 9 and can be used by setting the value of the @generate to true. The value of the  @select attribute can be an integer from 1 to 9, including groupings separated by a pipe character (regular expression syntax).
<headings generate="true" select="1-9" />
  • <outline> – can be invoked by setting the @generate attribute of <outline>to true. The value of the @select attribute can be an integer from 1 to 9, including groupings separated by a pipe character (regular expression syntax).
<outline generate="true" select="1|3-6|8" />
  • <paragraph> – paragraph styles can be used inside the ToC by setting the @generate attribute of <paragraph> to true. Any other value won’t generate a ToC. The <paragraph>element contains <style>elements, each with a unique @value attribute that declares which paragraph styles generate the ToC. An @indent attribute sets the level for the paragraph style in the ToC hierarchy.
<paragraph generate="false">
  <style value="Heading 1" indent="1" />    
  <style value="Heading 2" indent="2" />
  <!-- any paragraph style defined in the document
       with the corresponding ToC indent level 
   -->
</paragraph>
  • Default behavior – by default, all heading levels and outline levels are added to the ToC and the value of the @generateattribute on the<paragraph>element is set to false.

<default>

This element is where the default conversion options are set.

<default>
  <defaultparagraphstyle wordstyle="Body Text" />
  <defaultcharacterstyle wordstyle="Default Paragraph Font" />
  <comments generate="false" />
  <mathml generate="false" />
  <citations documenttype="bibliography" pageslabel="pages" />
  <endnotes documenttype="endnotes" />
  <footnotes documenttype="footnotes" />
  <xrefs hyperlinkstyle="PS Hyperlink"
         referencestyle="PS Reference" />
  <placeholders resolvedstyle="PS Placeholder"
                unresolvedstyle="PS Unresolved" />
  <indexdoc documentlabel="indexdoc" columns="2" />
</default>

Following elements are all optional:

  • <defaultparagraphstyle> – where a<block>is not specifically mapped to a style name in the DOCX file, it is transformed to a default style, usually Body Text, but it can be the name of any style that exists in the Word Export Template. Where the DOCX file doesn’t have a style that matches, the default style is set to Normal. This has no effect if block/@default described below is set.
<defaultparagraphstyle style="Body Text"/>
  • <defaultcharacterstyle> – defines which style is applied to all inline elements that don’t have specific mapping to a style. The default value is Default Paragraph Font<defaultcharacterstyle>can be any Word Character Style Name that exists in the Word Export Template. If a style is used that doesn’t exist in this template, Word, by default, resets the value. This has no effect if inline/@default described below is set.
<defaultcharacterstyle style="Default Paragraph Font"/>
  • <comments> – the <comments> element is used to add comments for each section, with a link to add a comment to PageSeeder section by the users’ default mail engine. By default, this value is set to false.
<comments generate="false"/>
  • <mathml> – converts any Math ML object that is referenced by the exported psml document. These are converted back to Open Office math ml objects in Word. By default, this value is set to false.
<mathml generate="false"/>
  • <citations> – xrefs to properties fragments in a document with type @documenttype become DOCX citations and a DOCX bibliography is inserted after this document’s <section id="title"> content. If there is an inline label @pageslabel directly after the xref, its content becomes the citation page or page range (e.g. <xref documenttype="bibliography" ... >...</xref><inline label="pages">10 - 20</inline>). Requires additional post-processing and pso-docx version 0.7.4 or higher.
<citations documenttype="bibliography" pageslabel="pages" />
  • <endnotes> – xrefs to fragments under <section id="content"> in a document with type @documenttype become DOCX endnotes. The xrefs must have @type="alternate" and the document must be generated using ps:process ANT task where xrefs/@types includes alternate. Requires pso-docx version 0.8.1 or higher.
<endnotes documenttype="endnotes"/>
  • <footnotes> – xrefs to fragments under <section id="content"> in a document with type @documenttype become DOCX footnotes. The xrefs must have @type="alternate" and the document must be generated using ps:process ANT task where xrefs/@types includes alternate. Requires pso-docx version 0.8.1 or higher.
<footnotes documenttype="footnotes"/>
  • <xrefs> – if type="cross-reference" then xrefs become DOCX REF instead of HYPERLINK. REF has an ‘Update field’ option in Word that means pointers to numbered paragraphs or headings can be updated to reflect any numbering changes. This isn’t possible with the HYPERLINK option.

    As of version 0.7.0, xrefs with @display="template" and @title containing {parentnumber} or {prefix} become DOCX REF even without setting @type above. Also <xrefs> can have the following attributes:
    • @hyperlinkstyle: The Word style for xrefs pointing outside the document (default PS Hyperlink).
    • @referencestyle: The Word style for xrefs pointing within the document (default PS Reference).
<xrefs type="cross-reference"
       hyperlinkstyle="My Hyperlink"
       referencestyle="My Reference" />

For further information on configuring xrefs for DOCX, see <xref>.

  • <placeholders> – defines the word styles for PSML <placeholder> elements. Requires pso-docx version 0.8.8 or higher. It can have the following attributes:
    • @resolvedstyle: The Word style for resolved placeholders (default DefaultParagraphFont).
    • @unresolvedstyle: The Word style for unresolved placeholders - no corresponding metadata property (default DefaultParagraphFont).
<placeholders resolvedstyle="My Placeholder"
              unresolvedstyle="My Unresolved" />
  • <indexdoc> – defines an index document where a DOCX index is inserted after the document’s <section id="title"> content. See <inline> for how to insert index entries. Requires pso-docx version 0.8.20 or higher. It can have the following attributes:
    • @documentlabel: The label that identifies the index document.
    • @columns: The number of columns in the index - from 1 to 4 (default 2).
<indexdoc documentlabel="myindex" columns="1" />

In the word-export-template.docx, only character styles can be used to format hyperlinks, references or placeholders.

<elements>

Groups the options available to PSML elements when transforming from PSML to DOCX. These include:

  • <block>
  • <image>
  • <inline>
  • <table>
  • <heading>
  • <para>
  • <title>
  • <nlist>
  • <list>
  • <preformat>
  • <xref>

They can be transformed specifically for a document with a certain label. This can be defined by setting the @label attribute inside a separate <elements> element.

<elements label="warranty">

If this is set, the options defined under this element only apply to documents with this label. In the example above, the options defined under <elements> would only apply to elements under a document with label ‘warranty’.

An <elements> can also have a @blocklabel which means that the options underneath will only apply to PSML elements with that block label as their closest ancestor. Requires pso-docx version 0.8.20 or higher.

<elements blocklabel="info">

The only options supported under <elements> that have @blocklabel are <heading>, <para>, <list> and <nlist>.

<block>
<block  default="generate-ps-style">
  <label value="Abstract"          wordstyle="Instructions" />
  <label value="Prompt"            wordstyle="Prompt" />
  <label value="generate-ps-style" wordstyle="Notes" >
    <keep-paragraph-with-next />
  </label>
  <ignore label="Notes" />
</block>

<block> element contains the handling of all <block> elements. The @default attribute is used to define what Paragraph Style is applied to any <block> elements that have no transformation. It accepts two values:

  • generate-ps-style – is used to generate a word style for each of the labels found. It generates a Word Paragraph Style named ps_blk_[name-of-label].
  • para – is used to generate the default paragraphs set inside the configuration file.

Under <block>, two elements are valid:

  • <ignore> – means the content inside this block won’t be transformed on export.
  • <label> – then the contents inside this block are transformed into the Word Style declared as the value of the attribute @wordstyle.

    The attribute @wordstyle under <label> can also contain generate-ps-style forcing the process to generate a unique style for that block label. The <keep-paragraph-with-next/> element can be used to keep this with the next content.

<image>

Contains style for <image> elements. Since images are inline objects in PageSeeder the @wordstyle must correspond to a character style in DOCX (not a paragraph style). Requires pso-docx version 0.8.19 or higher.

An <image> can also have a @maxwidth which is the width in pixels that a larger image will be re-sized to (default 620). A @widelabel can define an image label that allows an image to ignore the max width (can be used for A3 size images for example). Requires pso-docx version 0.8.20 or higher.

<image wordstyle="Image" maxwidth="400" widelabel="big" />
<inline>
<inline default="generate-ps-style" >
  <label value="Optional" wordstyle="OptionalNormal" />
  <ignore label="Notes" />
  <tab label="TabLabel" />
  <fieldcode label="n" value="LISTNUM  LegalDefault \\l 1 \\s 2 " />
  <index label="ind" />
</inline>

<inline> element contains the handling of all <inline> elements. @default attribute is used to define what Paragraph Style is applied to any block elements that have no transformation. It accepts two options: generate-ps-style and any other value. generate-ps-style is used to generate a word style for each of the labels found. It generates a Word Character Style named ps_inl_[name-of-label]. All other values generate only text.

Under <inline> , four elements are accepted: <ignore>, <tab>, <fieldcode> and <label>. <ignore> is used to define ignored labels on transformation.

If a label name is defined under the attribute @label under <ignore>, then the contents inside this inline won’t be transformed on transformation.

If a label name is defined under the attribute @value under <label>, then the contents inside this inline are transformed into the Word Style selected under the attribute @wordstyle. The attribute @wordstyle under <label> can also contain generate-ps-style forcing the process to generate a unique style for that inline label.

If a label name is defined under the attribute @label under <tab>, then the contents inside this inline is transformed to a word tab on output.

If a label name is defined under the attribute @label under <fieldcode>, then the contents inside this inline are transformed to a word fieldcode on output. The fieldcode generated is the one set in the @value attribute.

If a label name is defined under the attribute @label under <index>, then the contents inside this inline are transformed to a word index entry where a : indicates a sub-entry, for example <inline label="ind">speed</inline> or <inline label="ind">speed:fast</inline>. The inline label should be directly after the term being indexed with no space in between. Requires pso-docx version 0.8.20 or higher.

<tables>
<tables>
  <table default="PS Table"
         headstyle="PS Table Header"
         bodystyle="PS Table Body" >
    <width type="pct" value="5000"/>
  </table>

  <table role="pstablerole"
         tablestyle="Table Grid"
         headstyle="My Table Header"
         bodystyle="My Table Body"/>

  <table role="pstablerole2" tablestyle="Table Grid 2" >
    <width type="dxa" value="5000"/>
  </table>
</tables>

<tables> element is used to define table styles for each PageSeeder table.

In the above example:

  • PS Table – is set as the default table style.
  • PS Table Header – is the paragraph style for header cells.
  • PS Table Body – is the paragraph style for other cells.

The @role attribute can also guide the <table> element transformation with the value determining the value iof the @tablestyle@headstyle and @bodystyle attributes.

The <width> element under each <table> has a @type attribute that can be set by either: dxa (a unit of measure) or pct (percent).

In Word, 100% is 5000 dxa (1 dxa = 1 twentieth-of-a point, 20 dxa = 1 point).

<heading>
<heading>
  <level value="1" numbered="true" wordstyle="heading 1" >
    <numbered select="true">
      <fieldcode regexp="%arabic%" type="SEQ" />
    </numbered>
  </level>
  <level value="2" wordstyle="heading 2" >
    <prefix select="true" separator="space">
      <fieldcode regexp="\d+\.%arabic%" type="SEQ" />
    </prefix>
  </level>
  <level value="3" wordstyle="heading 3" >
  </level>
  <level value="4" wordstyle="heading 4" >
    <numbered select="true">
    </numbered>
  </level>
  <level value="5" wordstyle="heading 5" >
    <numbered select="true" >
      <fieldcode
         regexp="^heading-1^.^heading-2^.^heading-3^.^heading-4^.%arabic%"
         type="SEQ" />
    </numbered>
    <keep-paragraph-with-next />
  </level>
  <level value="6" wordstyle="heading 6" >
    <numbered select="true" >
      <fieldcode
         regexp=
   "^heading-1^.^heading-2^.^heading-3^.^heading-4^.^heading-5^.%arabic%"
         type="SEQ" />
    </numbered>
    <keep-paragraph-with-next />
  </level>
</heading>

The <heading> element defines the mapping between the PageSeeder heading level and the Word heading style. By default, every heading level maps to the equivalent heading style (heading level 1 to heading 1 style, heading level 2 to heading 2 style...). Or each PSML heading level can be transformed into an arbitrary DOCX style.

As of pso-docx version 0.7.2 the @numbered and @prefixed attributes on <level> can also be used to map different Word styles to PSML <heading> where @prefix or @numbered="true". These can be output as a <fieldcode> element under the corresponding level/numbered or level/prefix.

The level/@prefixed attribute is ignored in this case.

As of pso-docx version 0.6.2, the <prefix> element supports a @separator="[tab|space|none]" attribute. This defines the character between the prefix and the heading text (tab is the default) unless @select="false" in which case neither the prefix, or the separator are output.

The <keep-paragraph-with-next/> element can be used to keep this with the next content.

The level/@prefixed attribute is ignored in this case.

Word styles “heading [x]” must be in lower case but all other Word styles must match the case in the DOCX template (for example, “Heading Numbered 1”).

<para>
<para>
  <indent level="0" wordstyle="Body Text" >
    <prefix select="true" separator="space" >            
      <fieldcode regexp="Note %arabic%" type="SEQ" />
    </prefix>
  </indent>

  <indent level="1" wordstyle="List Continue" >
    <numbered select="true">
      <fieldcode
         regexp=
"^heading-1^.^heading-2^.^heading-3^.^heading-4^.^heading-5^.^heading-6^.%arabic%"
         type="SEQ" />
    </numbered>
  </indent>

  <indent level="2" wordstyle="List Continue" >    
  </indent>

  <indent level="3" wordstyle="List Continue" >      
  </indent>

  <indent level="4" wordstyle="List Continue" >
    <keep-paragraph-with-next />
  </indent>

  <indent level="5" wordstyle="List Continue" >
    <numbered select="true" >
      <fieldcode
         regexp=
"^heading-1^.^heading-2^.^heading-3^.^heading-4^.^heading-5^.^heading-6^.^para-^.%arabic%"
         type="SEQ" />
    </numbered>
  </indent>

  <indent level="6" wordstyle="List Continue" >
    <numbered select="true" >
      <fieldcode
         regexp=
"^heading-1^.^heading-2^.^heading-3^.^heading-4^.^heading-5^.^heading-6^.^para-1^.^para-5^.%arabic%"
         type="SEQ" />
    </numbered>
    <keep-paragraph-with-next />
  </indent>

  <!-- Prefixed paragraphs -->
  <indent level="1" prefixed="true" wordstyle="List Manual" />

  <indent level="2" prefixed="true" wordstyle="List Manual 2" />

  <indent level="3" prefixed="true" wordstyle="List Manual 3" />

    <!-- Numbered paragraphs -->
  <indent level="1" numbered="true" wordstyle="List Number" />

  <indent level="2" numbered="true" wordstyle="List Number 2" />

  <indent level="3" numbered="true" wordstyle="List Number 3" />
</para>

 

Element <para> and the @wordstyle attribute map the PageSeeder paragraph indent level to a Word style.

As of pso-docx version 0.6.1, the @numbered and @prefixed on <indent> can be used to apply different Word styles to PSML <para> with @prefix or @numbered="true".

If the paragraph is numbered, or has a prefix, it can be transformed into a fieldcode in the output. This is defined by the <fieldcode> element under the corresponding indent/numbered or indent/prefix.

The indent/@prefixed attribute is ignored in this case.

As of pso-docx version 0.6.2 the <prefix> element can have a @separator="[tab|space|none]" to define the character between the prefix and the paragraph text (tab is the default) but if it has @select="false" the prefix and separator won’t be output.

The <keep-paragraph-with-next/> element can be used to keep this with the next content.

The indent/@prefixed attribute is ignored in this case.

<title>
<title wordstyle="heading 1"/>

Element <title> is used to define the Paragraph Style of each section title.

By default title is set to heading 1. It can be transformed into any value that exists in the Word Export Template.

<nlist>

Contains the list definitions for numbered lists inside of Word.

<nlist liststyle="Numbered List" />
  <role value="highlight" liststyle="Highlighted Numbered List" />
</nlist>

As of pso-docx version 0.6.1, the @liststyle on <nlist> and <role> can be used to apply a specific Word list style. The <default> and <level> elements are no longer supported under these elements.

If the PSML list has a @role attribute, it can be associated with a Word list style using the <role> element.

<list>

Contains the list definitions for unnumbered lists inside of Word.

<list liststyle="Bulleted List" >
  <role value="highlight" liststyle="Highlighted Bulleted List" />
</list>

As of pso-docx version 0.6.1, the @liststyle on <list> and <role> can be used to apply a specific Word list style. The <default> and <level> elements are no longer supported under these elements.

If the PSML list has a @role attribute, it can be associated with a Word list style using the <role> element.

The @type on <list> and <nlist> in PSML is ignored as it could clash with the default and role based word styles. To alert editors to this in PageSeeder the following custom CSS could be added:

.psml-content

       ul[data-type]:before,

        ol[data-type]:before

    {
    color: white;
    content:"LIST TYPE IS NOT SUPPORTED BY WORD EXPORT";
    background: red;
    border-radius: 2px;
    padding: 1px 4px;
    }

.psml-content ul[data-type]

       li, ol[data-type] li

{
    color: red
}

<listpara>

Contains style for a <para> inside a <list> or <nlist> that is not the first <para>. The @value corresponds to the nesting level of the <list> or <nlist>. Requires pso-docx version 0.7.5 or higher.

<listpara>
  <level value="1"  wordstyle="List Continue" />
  <level value="2"  wordstyle="List Continue 2" />
  <level value="3"  wordstyle="List Continue 3" />
  <level value="4"  wordstyle="List Continue 4" />
  <level value="5"  wordstyle="List Continue 5" />
  <level value="6"  wordstyle="List Continue 6" />
</listpara>
<preformat>

Contains style for <preformat> elements.

<preformat wordstyle="HTML Preformatted"/>
<xref>

Contains styles for specific types of cross-references (the child elements are optional but must appear in the order below). Requires pso-docx version 0.7.4 or higher.

<xref>
  <citation referencestyle="My Citation Reference" />

  <endnote textstyle="My Endnote Text"
           referencestyle="My Endnote Reference" />

  <footnote textstyle="My Footnote Text"
            referencestyle="My Footnote Reference" />

  <xrefconfig name="field"
              hyperlinkstyle="My Field Link"
              referencestyle="My Field Reference" />

  <xrefconfig name="term"
              hyperlinkstyle="My Term Link" />
</xref>

For <citation> the text style is always Bibliography and the default @referencestyle is the default character style (see <default> above).

For <endnote> the default @textstyle is Endnote Text and the default  @referencestyle is Endnote Reference.

For <footnote> the default @textstyle is Footnote Text and the default @referencestyle is Footnote Reference.

There might be multiple <config> elements and the @name refers to the @config on the XRef. The default @hyperlinkstyle and @referencestyle are defined in the <default> element above. Requires pso-docx version 0.7.6 or higher.

In the word-export-template.docx, any hyperlink or reference styles must be character only style.

Created on , last edited on