Task-driven tutorials and recipes for PageSeeder

How to use metadata to substitute lo-res with hi-res images

Skills requiredXML
Time required (minutes)30
Intended audienceDeveloper


This tutorial describes how metadata on images can be used to control which images are used when exporting a document. For example, when publishing a PageSeeder document to a website or mobile device, there may be a requirement to use a low resolution, RGB image. When publishing the same image to a hardcopy format such as PDF or Docx, it may be preferable to substitute in a high resolution, CMYK image.


This tutorial assumes:

  • access to a PageSeeder server with an administrator account.
  • have created a project and a group under it on the PageSeeder server.
  • have created a document in the group containing a lo-res image and have also uploaded a hi-res version of the image to the group.

All the files for this tutorial are on GitHub .


Configure Image Metadata

Determine the image type to be used, and then configure the metadata template in the document template.

In the project, go to the Document config page located under the Dev tab in the Developer perspective, then "Create media type". In this example, we use "png" as image type.


Then edit the following files to add support for .png images:

Document Template

<document level="metadata" xmlns:t="http://pageseeder.com/psml/template">
      <property name="caption" title="Caption"   value="" />
      <property name="action"  title="Action"    value="" />
      <property name="hi-res"  title="Hi-res"    datatype="xref" />

The corresponding editor-config.json 

  "PSMLMetadataConfig": {
    "fields": {
      "action" : {
        "type": "checkbox",
        "label": "Action",
        "values": ["None", "Zoom", "Fullscreen"]


The caption and action properties and the editor-config.json file are not required for the image substitution.  This is simply a convenient opportunity to illustrate how to configure an object for multiple metadata properties. 

Edit Image Metadata

Ensure the following:

  • both the lo-res and hi-res versions of the image have been uploaded to a group in the correct project;
  • the lo-res image has been referenced by document created using the correct template.

Then view the lo-res image file and edit the Properties.


On the 'Document Properties' page, expand the 'Metadata properties' section and select the 'Browse Documents' option. Navigate to the hi-res image file and select it. This will create a cross-reference to the hi-res image in the metadata of the lo-res image.


Follow these steps to complete the connection of the images:

  1. Edit the hi-res link
  2. Select a 'Link Type' of 'alternate',
  3. Select 'Save Link', 
  4. Select 'Save'.




Configure the 'Exporting with Substitution' function

Follow these steps to log on to the Publish server:

  1. Select 'Toolbox' located under the Dev tab in the Developer perspective,
  2. Select 'Project files',
  3. Use an account with Administrator privileges.



Once logged on to the Publish server,  create the following  location for the configuration file under 'Template':



From the material downloaded from GitHub (see Prerequisites above), upload the following files to the export folder:


alternate-images.xsl – is the code that actually substitutes the images, see the following:

<xsl:stylesheet version="2.0"

  <!-- change image src to alternate image -->
  <xsl:template match="image[.//xref/@type='alternate']">
    <image src="{.//xref[@type='alternate']/@href}">
      <xsl:copy-of select="@*[not(name()='src')]"/>

  <!-- copy all other elements unchanged -->
  <xsl:template match="*">
      <xsl:copy-of select="@*" />
      <xsl:apply-templates select="node()" />


build.xml – has been modified so the following elements have been added to <ps:process> This initiates the XSLT and embeds the metadata:

<images embedmetadata="true"/>
<posttransform xslt="alternate-images.xsl" />

Prepare publish config file for PDF and DocX format

Through the user interface, select 'Project files' located under the Dev tab in the Developer perspective and create the following:


then upload the following file that should have been retrieved from Github in Step 3.




To ensure that process is functioning as expected:

  1. Select the Export icon for the document that contains the lo-res image,
  2. Select the option labelled 'Create PDF with Image Replacement', 
  3. Click the 'Export' button. 


After completion, the PDF document will feature a hi-resolution image in place of the low-resolution image. 


Created on , last edited on