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

Prerequisites

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 .

Tutorial

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.

image_meta_config.png

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

Document Template

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

The corresponding 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

Created on , last edited on