Tutorials

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
DifficultyMedium
CategoryDocument

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

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

Tutorial

Configure Image Metadata

Determine the image type to be used, and then configure the metadata using the document 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.

image_meta_config.png

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

document-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"]
        }
      }
   }
 }

Note

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.

edit_image_meta1.png

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.

edit_image_meta4.png

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

edit_image_meta5.png

 

 

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.

add_exporting_config1.png

add_exporting_config2.png

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

[project]/document/psml/export

add_exporting_config3.png

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, select 'Project files' located under the Dev tab in the Developer perspective and create the following:

[project]/Publish

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

publish-config.xml

add_exporting_config4.png

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

export_test1.png

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

export_test2.png

Validation

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

Note

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

Created on , last edited on