How to Publish XML Files as HTML

Table of Contents

Overview of Process

This documentation describes how to integrate XML files that are stored on an external server into Knowledge Management (KM) and to display them as HTML files in the portal.

Prerequisites

The examples used in the following sections assume that the set of XML files, which you want to display as HTML, all have the same structure. This ensures that they can all be transformed into HTML using the same XSLT stylesheet. If you have XML files with different structures, you need to provide an XSLT file for each differently structured type of XML.

Process

To integrate external XML files into KM and to display them as HTML, you need to perform a number of steps:

• Transfer the external files into a folder that is located in a CM repository
• Write an XSLT stylesheet that specifies how to transform the elements in the XML file into HTML
• Make sure that the stylesheet is availabe in a KM repository: Normally stylesheets are stored in the /etc repository.
• Configure an XSLT filter that defines the transformation of the XML files to HTML with the help of an XSLT stylesheet.

The sections that follow describe the above steps in detail.

Integrating External XML Files into Knowledge Management

You can transfer external files to a CM repository in different ways. One way, which we recommend when a large number of documents are involved, is to make use of WEbDav. If your XML files are located on a machine that is a WEbDav-enabled client, you can easily copy the XML files to a CM target folder. Prerequisite for the copy operation is a connection from the WebDav client to the CM target folder. In Microsoft® Windows®, you can establish the connection by configuring the CM target folder as a MS Web Folder.

The following procedure describes how to transfer files from a Microsoft® Windows® 2000 file system to a CM repository. Microsoft® Windows® is a WebDav-enabled client by default.
Note that if the XML files are located on a machine with a different Windows version, the steps may not be exactly the same as described here.

1. In the portal, create a target folder for the XML files in the CM repository.
2. In the Windows Explorer, on the machine where the XML files are located, create a connection to the CM target folder. To do this, configure the CM folder as a MS WebFolder:

1. In the portal, open the Details dialog box for the folder with the XML files and choose Settings → Properties → Access Links.
2. Select the entire content of the field WebDAV URL, and copy the URL into the Windows clipboard using Ctrl + c.
3. In the Windows Explorer, click on My Network Places using the secondary mouse button, and choose Map Network Drive from the context menu.
4. Choose Create a shortcut to a Web folder or FTP site. Insert the WebDAV URL from the clipboard into the input field using Ctrl + v. If a folder name contains spaces, you have to replace them with the character sequence %20. For example, you would replace /Public Documents with /Public%20Documents.
5. Choose Next. You are asked for authentication. Enter your username and password for the portal. Confirm them with OK.
6. Enter a display name for the folder in the Explorer, and choose Finish.
7. The CM target folder is opened on your desktop. It is now a network drive in the Windows Explorer. Before the contents are displayed, you are asked for authentication again. Enter your username and password for the portal. Confirm them with OK.
   

3. Copy the XML files to the CM target folder in the Windows Explorer.

Creating an XSLT StyleSheet

To transform an XML file into HTML, you need to apply an XSLT stylesheet. The stylesheet specifies how the XML elements must be transformed into HTML.

The following examples show a simple XML file and a corresponding XSLT stylesheet that defines the details of the transformation. The transformation only functions for XML files that have the elements specified in the XSLT file. If other elements are included in the XML file, no transformation instructions will be available for them, and the conversion to HTML will fail.

XML File

<?xml version="1.0" encoding="utf-8"?>
<addressbook>
   <owner>Peter Miller</owner>
   <lastupdated>01/05/2003</lastupdated>
   <address>
     <name>
       <firstname>Montgomery</firstname>
       <lastname>Scott</lastname>
     </name>
     <city>Cambridge</city>
     <street>123 Maple Street</street>
     <telephone>0815-472-2328</telephone>
   </address> 
   <address>
     <name>
       <firstname>James T.</firstname>
       <lastname>Kirk</lastname>
     </name>
     <city>Beverly Hills</city>
     <street>234 Main Street</street>
     <telephone>0815-123-4428</telephone>
   </address>
</addressbook>

XSLT Stylesheet

<xsl:stylesheet
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   version="1.0">
<xsl:template match="addressbook">
  <html>
  <head>
    <title><xsl:value-of select="owner" /></title>
  </head>
  <body>
    <xsl:apply-templates select="owner" />
    <xsl:apply-templates select="lastupdated" />
    <xsl:apply-templates select="address" />
  </body> 
 </html>   
</xsl:template>
<xsl:template match="owner">
  <div align="center"><h1>Addresses of: <xsl:value-of select="." /></h1></div>
</xsl:template>
<xsl:template match="lastupdated">
  <div align="center"><h3>Last updated: <xsl:value-of select="." /></h3></div>
</xsl:template>
<xsl:template match="address">
  <xsl:apply-templates select="name" /> <br/>
  <xsl:apply-templates select="city" /> <br/>
  <xsl:apply-templates select="street" /> <br/>
  <xsl:apply-templates select="telephone" /> <br/>
  <p/>
</xsl:template>
<xsl:template match="name">
  <i><xsl:value-of select="." /></i>
</xsl:template>
<xsl:template match="city">
 <xsl:value-of select="." />
</xsl:template>
<xsl:template match="street">
  <xsl:value-of select="." />
</xsl:template>
<xsl:template match="telephone">
  <xsl:value-of select="." />
</xsl:template>
</xsl:stylesheet>

Configuration

To ensure that the XSLT stylesheet is applied to the XML files whenever they are displayed in KM, you need to define an XSLT filter. To do this:

1. Store the XSLT stylesheet in a new subfolder of the /etc repository, for example, under /etc/filter/my_xslt
   The /etc repository is the standard location for stylesheets, but you can also store them elsewhere in a CM repository.
2. Make sure you are logged on as an administrator and then choose System Administration -> System Configuration -> Knowledge Management -> Content Management-> Repository Filters.
3. Choose XSLT Filter and then define a new XSLT filter: Enter data as follows:

Name: A unique name for the filter

Extension: File extension XML because the filter must be applied to XML files

Paths: Path to the XML files. Do not specify the repository name in the path.
If you add ** to the folder name, the filter is also applied to subfolders. For example, /<path>/transformation** means that all XML files in subfolders of transformation will also be displayed as HTML.

Stylesheet: Enter the path to the XSLT stylesheet using the following format:
wcm://<repository_name>/<path>/<stylesheet>
For example: wcm://etc/filter/my_xslt/address.xsl

Select the repository where the XML files are located and save the entries.

4. Restart the servlet engine to activate the new filter.

Output

When you have completed the configuration of the filter, the XML files are displayed as HTML files in the portal. Whenever you click on an XML file to display it, the filter automatically applies the XSLT stylesheet so that it can be displayed as HTML. For the simple example introduced above, the source code of the displayed html looks like this:

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Peter Miller</title>
</head>
<body>
<div align="center">
<h1>Addresses of: Peter Miller</h1>
</div>
<div align="center">
<h3>Last updated: 01/05/2003</h3>
</div>
<i>
       Montgomery
       Scott
     </i>
<br>Cambridge<br>123 Maple Street<br>0815-472-2328<br>
<p></p>
<i>
       James T.
       Kirk
     </i>
<br>Beverly Hills<br>234 Main Street<br>0815-123-4428<br>
<p></p>
</body>
</html>