Skip to main content


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 image metadata can control which version of an image is used when PageSeeder outputs a document. For example, publishing a document to a website or mobile device may use the same resolution image as the editing process. However, when the same document is output for print the images may be substituted with a higher resolution version.


This tutorial assumes:

  • administrator rights on a PageSeeder server,
  • a project to host the customization and a group for the example document,
  • a PSML document which has an low resolution image inserted,
  • a high resolution version of the same image used in the PSML document.

All the files for this tutorial are on GitHub .


Configure Image Metadata

Determine the image type to be used, and then configure the metadata using the media template. In the project selected for this tutorial, 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.


Use the interface to add support for .png images by either create or edit of the following two files:



      <property name="caption"
                      value="" />
       <property name="action"
                      value="" />
       <property name="hi-res"
               datatype="xref" />


  "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. 



When substituting with hi-res images it may be useful to validate your images to ensure that all have hi-res alternatives defined. This can be done using schematron as follows:

  1. In PageSeeder select the group containing your images.
  2. Select the Document config page under the Dev menu in developer perspective.
  3. Click create under Schematron next to the png media type.
  4. Copy a paste the schematron code below and click Save.
  5. Select the group containing your images again.
  6. Click the Validate documents icon validate-icon.png at the top left of the page.
  7. Select .png and click Validate (any .png images without a hi-res alternative should be listed in the validation report).
 <sch:schema xmlns:sch="">
  <sch:title>Rules for images</sch:title>
    <sch:rule context="/document">
      <!-- Must have hi-res alternative -->
      <sch:assert test="metadata//property[@name='hi-res']/xref[@type='alternate'] or
        No hi-res alternative defined.</sch:assert>

This process can be repeated for other image types (e.g. .jpg, .gif).

Created on , last edited on

Available tutorials