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

Objective

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 might use the same resolution image as the editing process. However, when the same document is output for print, the images might be substituted with a higher resolution version.

Prerequisites

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

Tutorial

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, in the admin menu for the project, go to the Template configuration page, Media types tab, then click  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:

media-template.psml

<document
              level="metadata"
 xmlns:t="http://pageseeder.com/psml/template">

  <metadata>
    <properties>
      <property name="caption"
                title="Caption"
                      value="" />
      <property name="action"
                title="Action"
                      value="" />
      <property name="hi-res"
                title="Hi-res"
                datatype="xref" />
    </properties>
  </metadata>
</document>

editor-config.json 

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

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 Document info & metadata.

In the Document info & metadata panel, open the Metadata tab and select the property with the browse option. Navigate to the hi-res image file and select it. This creates 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'.
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':

[project]/document/psml/export

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

build.xml

alternate-images.xsl

numbering-config.xml

validate-psml.sch

word-export-config.xml

word-export-template.docx

ant-schematron-2010-04-14.jar

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

<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <!-- 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')]"/>
    </image>
  </xsl:template>

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

</xsl:stylesheet>

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, in the admin menu for the project, select Template files and create the following folder:

[project]/publish

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

publish-config.xml

Test

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 'Run' button.

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

Validation

When substituting with hi-res images it might 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 Documents page for the group containing your images.
2. Select the Template configuration page.
3. Click create under Schematron next to the PNG media type.
4. Copy and paste the following Schematron code and click Save.
5. Select the Documents page for the group containing your images again.
6. Click the Validate button at the top right 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="http://purl.oclc.org/dsdl/schematron">
  <sch:title>Rules for images</sch:title>
  <sch:pattern>    
    <sch:title>Document</sch:title>    
    <sch:rule context="/document">
      <!-- Must have hi-res alternative -->
      <sch:assert test="metadata//property[@name='hi-res']/xref[@type='alternate'] or
                        .//reversexref[@forwardtype='alternate']">
        No hi-res alternative defined.</sch:assert>
    </sch:rule>
  </sch:pattern>
</sch:schema>