XSLT in Arbortext APP

Summary

This chapter details the specifics of using the XSLT standard within the Arbortext APP environment.

1 Introduction

XSLT provides a method to transform and re-use XML data in a variety of formats and contexts. XSLT therefore increases document portability and transference across hardware and software. Arbortext APP and XSLT combine to make a flexible system for handling XML data and presentation.

Please note that this document is not a comprehensive technical overview of XSLT. This is because XSLT is well documented and there are many external resources for learning XSLT. This document assumes that the reader has some prior knowledge of XSLT and therefore the purpose is to provide a specific description of XSLT in Arbortext APP. It is assumed that the reader is familiar with XML. It is recommended that you read the XML section before reading the XSLT section.

For more information see the XML in APP chapter.

2 Overview

This chapter provides an overview of XSLT and how it works in conjunction with Arbortext APP. XSL stands for Extensible Stylesheet Language. It is an XML application that transforms XML documents.

XSL is split into two languages:

XSL-FO - Extensible Stylesheet Language - Formatting Objects. XSL-FO is an XML application that describes the layout of printed pages.

This chapter covers XSLT, for more information on XSL-FO see the XSL-FO in 3B2 chapter.

XSLT is an official recommendation of the World Wide Web Consortium (W3C). It provides a flexible, functional, declarative programming language for transforming XML documents into other text based documents, for example an HTML document, another XML document or a mark-up of your choice. XSLT is a tree structured hierarchical transformation language that uses XPath to select elements and text which are output from the XML. An XSLT stylesheet is a well-formed XML document used to define the rules which an XSLT processor uses to transform a number of XML instances.

XSLT has the following features:

It is a thoroughly researched recommended standard from the W3C.

It encompasses other standards such as XPath. XSLT is also the driving force behind XSL-FO.

It supports the Unicode (character encoding) standard. For more information see the Unicode chapter.

2.1	XSLT Processing

XSLT processing enables you to apply template rules to selected nodes of XML documents. XSLT uses XML and XPath to transform XML source trees in to results trees.

2.2	XSLT Transformation Example

Below is a simple example of an XSLT transformation that converts one input XML instance into an output XML instance.

A similar process can be used to transform an XML document into the format of your choice.

2.3 Input XML

In this example the following Input XML is used:

<?xml version='1.0'?>	1
<book type='fiction'>	2
<title>White Fang</title>	3
<writer>Jack London</writer>	4
<year>1906</year>	5
</book>	6

2.4	XSLT Stylesheet

Below is an example of an XSLT stylesheet:

<?xml version='1.0'?>	1
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/xsl/Transform'>	2
<xsl:template match='writer'>	3
<author>	4
<xsl:apply-templates/>	5
</author></xsl:template>	6
<xsl:template match='year'>	7
</xsl:template>	8
<xsl:template match='@\|node()'>	9
<xsl:copy>	10
<xsl:apply-templates select='@'\|node()'/>	11
</xsl:copy>	12
</xsl:template>	13
</xsl:stylesheet>	14

Below is an explanation of each line in the above stylesheet:

1: The XML declaration. For more information see the XML in APP chapter.

2-3: Defines the XSLT stylesheet. Note that the root node must be called stylesheet. This line also defines the XML namespace. For more information see Namespaces in the XML in APP chapter.

4: Find and match the content of the element writer.

5-7: Apply the XSL template. Replace the element writer with author.

8: Close the XSL template for the writer element.

9: Find and match the node year. Because year is not replaced with anything it will be removed and not shown in the output XML.

10: Close the XSL template for the year element.

11: Find and match all attributes and nodes.

12-14: Copy all the attributes and nodes and keep them as they were in the input XML.

15: Close the XSL template.

16: Close the XSL stylesheet.

2.5	Output XML

Below is the output XML that is created when the above stylesheet is applied to the input XML:

<?xml version='1.0'?>	1
<book type='fiction'>	2
<title>White Fang</title>	3
<author>Jack London</author>	4
</book>	5

3 XSLT Processing in Arbortext APP

There are many potential uses of XSLT and Arbortext APP, for example it is possible to:

Extract information contained in an XML stream so that pre-processing can be done before a single page is built. For example, graphic references can be extracted and used to form a script to preload them before formatting pages.

Sort and format a generated list on the fly, for example a pseudo index.

3.1	Libxml parser

The XSLT processing is used in the same manner as with the previous 3B2–XML processing, i.e. through the “txform” macro. If the document is being parsed with the libxml parser, then the libxml XSLT processor will automatically be used. Should the old XSLT processor need to be used for backward compatibility, then the 3B2–XML parser must be selected first. Any extensions and functionality mentioned in related chapters, for example XInclude or custom functions, also apply equally to XSLT.

For more information on parsers in Arbortext APP see the XML inArbortext APP- Parsers and processors chapter.

3.2	The txform macro

XSLT transformations are controlled using the txform command. This macro allows you to specify and control the transformation parameters.

The txform macro requires the following parameters:

Definition of the output stream name.

Parameter control stream (libxml only).

The txform macro controls more than just the XSLT type of transformations. It is also possible to specify the frequency of the transformation required, for example transformations can be performed automatically or as a one off. Other no-XSLT transformation can be performed such as using a translation map or a search and replace mini-script.

It is also possible for multiple transformations to be applied simultaneously to one XML stream to generate multiple output streams with different formats.

For more information see txform

3.2.1 Passing Parameters

Should the XSLT stylesheet require parameters to be passed in, i.e. they have <xsl:param> top-level elements, then it is possible to specify a parameter control stream that defines or overrides the default parameters in the stylesheet.

However, in Arbortext APP, it is also possible to pass parameter values to a stylesheet using a Parameter Control Stream. This enables stylesheets and their output to be controlled and customised by a Arbortext APP script.

It is only possible to pass parameters to the XSLT Parameter Control Stream when using the libxml parser.

Below is the syntax for a Parameter Control stream:

Parameter name="parameter value"

Below is an example of passing a Parameter Control stream:

fact="real life"

fiction="made up"

Below is an example of the XSLT stylesheet that the control stream can be applied to:

<?xml version='1.0'?>	1
<xsl:stylesheet version='1.0'>	2
<xsl:param type='fact'>unknown</xsl:param>	3
<xsl:template match='/'>	4
<title type='{$fact}'/>	5
</xsl:template>	6
</xsl:stylesheet>	7

13: The XML declaration.

15: Defines the XSLT stylesheet. Note that the root node must be called stylesheet.

17: Defines the default if a control stream is not applied.

19: Find and match the following.

21: If the attribute type of the element title is 'fact', replace with the control stream alternative. In this example the output would be 'real life' in accordance with the control stream.

23: Close the XSL template.

25: Close the XSL stylesheet.

Only one parameter is permitted per line, and the quotes around the value must be included in the control stream for the value to be recognised, but they do not appear when the value is used inside the XSLT stylesheet. To use the parameter control stream in a transformation, it should be specified as an input parameter to the txform dialogue or macro.

3.3	Viewing transformation properties

When you have set up a transformation on a tag using the txform command, it is possible to view its properties using the following syntax:

txform "result_tagname

The Tag Transform dialogue box will appear and all your previous transformation settings will be displayed in the entry boxes.

It is also possible to see this information by selecting [Document/Tags/Browse Tags] to invoke the Browse Tags dialogue box. Select the Info ▶ tab and you will see the transformation settings. Alternatively, it is possible to invoke the Browse Tags dialogue box using the tbrowse macro.

3.4	The tttaginfo command

Sometimes you may want to use information about an XSLT transformation in a script. To this end it is possible to use the ttaginfo macro to populate the ^ttaginfo_ variables for tag. The variables generated by an XSLT will have the following values set:

Variable

Description

Possible Values

ttaginfo_tx_xml

Defines whether the stream an XML document

0 = Not XML 1 = XML

ttaginfo_tt_type

Type of transformation

10 XSLT Transformation

12 Output XML Tree (preserve)

14 Output XML Tree (strip)

ttaginfo_tt_freq

Frequency of transformation

Manual

One-off transform only

ttaginfo_tt_src

Source Stream

Tag name

ttaginfo_tt_ctl

Control Stream

Tag name

ttaginfo_tt_prm

Parameter Control Stream

Tag name

For more information see ttaginfo

3.5	Error Reports

3.5.1 XML Error Streams

Whenever there is an error the xslterr:namespace is created. Arbortext APP creates a text stream of the same name as the error namespace. This contains any error messages with the same name as the XSLT stream, of type 'XML Error' (.xe).

3.5.2 Viewing Parser Errors

To view parser errors:

Select [XML/View Parser Errors]

This invokes the Browse Tags dialogue box showing all of the '.xe' streams.

3.5.3 The txmlerror macro

It is also possible to use the txmlerror macro to view parser errors.

For more information see txmlerror

3.5.4 Saving XML Error Streams

To specify whether to save the error stream with the XML document:

Tick the Save Parser Errors with Document: □ tick box.

3.5.5 Error Bar

In order to see the last error code from the libxml parser you can use the libxml Error Bar.

To enable the libxml Error Bar:

Select libxml_errorbar under the drop down lists under the Name: field.

Alternatively, enable the libxml Error Bar using the toolbars macro as shown below:

toolbars 'libxml_errorbar',4

The following is an explanation of the two fields in the libxml Error Bar:

Field	Displays	Numerical error code getvar	String error code getvar
Libxml status	Displays the last error code from libxml parser	21881	11882
Libxslt status	Displays the last error code for the last transform.	21883	11884

3.6	Inline XSLT Processing (V9)

Should only a fragment of an XML document require transformation, then it is possible to do an XSLT transform inline during formatting in a show-string. The syntax for this is as follows:

	1
^[xslt "xml", nodeid\|"path", "xslt", "param"]	2

where "xml" is the name of the source XML, "xslt" is the name of the stream containing the XSLT stylesheet, "param" is the name of the parameter control stream, and "nodeid" or "path" are either the number or the location path of the nodes in the source XML to be transformed.

The input node is treated as if it occurs in a separate XML document by itself, along with its children. If a location path is specified and the path contains multiple nodes, then the XSLT is processed against each node individually with the results being combined and formatted together.

Any errors occurring during the transformation are returned by the function variable instead of the output.

4 EXSLT

EXSLT is an initiative to provide extensions to XSLT. Libxml supports the EXSLT extension functions for use in XSLT processing in Arbortext APP.

The EXSLT extension functions are accessed by declaring the relevant namespace for the EXSLT module:

http://www.exslt.org/<module>

where <module> is the name of the required module.

4.1	EXSLT Functions

The following EXSLT functions are provided by the libxml parser in Arbortext APP:

Module	XPath namespace	Functions Available
common	exsl:	document(*)	node-set	object-set
dates-and-times	date:	add	day-name	month-in-year
		add-duration	day-of-week-in-month	month-name
		date	difference	second-in-minute
		date-time	duration	seconds
		day-abbreviation	hour-in-day	time
		day-in-month	leap-year	week-in-month
		day-in-week	minute-in-hour	week-in-year
		day-in-year	month-abbreviation	year
dynamic	dyn:	evaluate
math	math:	abs	cos	min
		acos	exp	power
		asin	highest	random
		atan2	lowest	sqrt
		constant	max	tan
sets	set:	difference	has-same-node	leading
		distinct	intersection	trailing
strings	str:	align	padding
	concat	split	tokenize

All functions listed above, with the exception of exsl:document() are available to use in XPath expressions in the specified namespace providing the "x3b2 namespace" option is selected.

5 Example XSLT transformation

Below is an example of a XSLT transformation from XML to HTML.

5.1 Input XML

Below is the Input XML. It is a basic XML stream that will be transformed into HTML Output using an XSLT transformation within Arbortext APP.

<?xml version="1.0"?>	1
<chapter>	2
<chapter.title>Common Acronyms</chapter.title>	3
<chapter.description>	4
<p>This is a list of acronyms and abbreviations. </p>	5
</chapter.description>	6
<description.list value="API">Application Programming interface</description.list>	7
<description.list value="ASCII">American Standard Code for Information Interchange</description.list>	8
<description.list value="ASP">Active Server Pages</description.list>	9
<description.list value="B2B">Business to Business</description.list>	10
<description.list value="B2C">Business to Consumer</description.list>	11
<description.list value="BPML">Business Process Modelling Language</description.list>	12
<description.list value="BPMS">Business Process Management Systems</description.list>	13
<description.list value="BPQL">Business Process Query Language</description.list>	14
<description.list value="CALS">Computer-Aided Acquisition and Logistics Support</description.list>	15
<description.list value="CAN">Controller Area Network</description.list>	16
<description.list value="CC">Container Catalog</description.list>	17
<description.list value="CGM">Computer Graphics Metafile</description.list>	18
<description.list value="CLIR">Cross Language Information Retrieval</description.list>	19
<description.list value="CMS">Content Management System</description.list>	20
<description.list value="COBOL">COmmon Business Oriented Language</description.list>	21
<description.list value="COM">Component Object Model</description.list>	22
<description.list value="CPP">Collaboration Protocol Profiles</description.list>	23
<description.list value="CSS">Cascading Style Sheets</description.list>	24
<description.list value="DBMS">Database Management Systems</description.list>	25
<description.list value="DDB">Device Database</description.list>	26
<description.list value="DI">Document Instance</description.list>	27
</chapter>	28

5.2	XSLT Stylesheet

Below is the XSLT stylesheet that transforms the XML Input into HTML.

<?xml version="1.0"?>	1
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">	2
<xsl:output method="html" indent="yes"/>	3
<xsl:template match="/">	4
<html>	5
<head>	6
<title><xsl:apply-templates select="//chapter.title"/></title>	7
</head>	8
<body>	9
<center>	10
<h1><xsl:apply-templates select="//chapter.title"/></h1>	11
<xsl:apply-templates select="//chapter.description"/>	12
<table width="70%">	13
<xsl:apply-templates select="//description.list"/>	14
</table>	15
</center>	16
</body>	17
</html>	18
</xsl:template>	19
<xsl:template match="chapter.title">	20
<xsl:apply-templates/>	21
</xsl:template>	22
<xsl:template match="chapter.description">	23
<p><xsl:apply-templates/></p><hr/>	24
</xsl:template>	25
<xsl:template match="description.list">	26
<tr><td><b><xsl:value-of select="position()"/>.<xsl:text disable-output-escaping="yes">&nbsp;</xsl:text>	27
<xsl:value-of select="@value"/>.</b></td><td><xsl:apply-templates/></td></tr>	28
</xsl:template>	29
</xsl:stylesheet>	30

1: The XML declaration.

2: Defines the XSLT stylesheet. Note that the root node must be called stylesheet. This line also defines the XML namespace. All standard XSLT elements are in the http://www.w3.org/1999/XSL/Transform namespace. This mapping is normally declared on the root element.

3: Specifies that the output method of the stylesheet is HTML. This also inserts the HTML meta tags in the Output HTML. This line also specifies that the Output HTML should be indented as shown below in the Output HTML.

4: Find and match the following.

5: Output the HTML <html> element. If the output method was not specified above (see line 3), the stylesheet would recognise the <html> tag as the first element in the output stream and would output HTML and insert the HTML meta tags in the Output HTML.

6: Output the HTML <head> element.

7: Output the HTML <title> element. Applies the <chapter.title> element transformation (detailed below). This selects and outputs the text between the chapter.title element in the XML Input. Then, output the the HTML </title> element.

8: Output the HTML </head> element.

9: Output the HTML <body> element.

10: Output the HTML <center> element.

11: Output the HTML <h1> element. Applies the <chapter.description> element transformation (detailed below). This selects and outputs the text between the chapter.description element in the XML Input. Then, output the HTML </h1> element.

12: Apply this template. Select and output the elements and the text between the <chapter.title and </chapter.title

13: Output the HTML <table width="70%">.

14: Select and output the text in between the chapter.description element in the XML Input.

15: Output the HTML </table>.

16: Output the HTML </center>.

17: Output the HTML </body>.

18: Output the HTML </html>.

19: Close the XSL template.

20: Specifies the <chapter.title> element transformation; find and match the content of the element <chapter.title>.

21: Apply the <chapter.title> template.

22: Close the XSL template for the<chapter.title> element.

23: Specifies the <chapter.description> element transformation; find and match the content of the element <chapter.title>.

24: Output the HTML <p> element. Apply the <chapter.description> template. Then, output the the HTML </p> and <hr/>elements.

25: Close the XSL template for the<chapter.description> element.

26: Specifies the <description.list> element transformation; find and match the content of the element <description.list>.

27-28: Output HTML table row containing two cells with selected data from the XML source.

29: Close the XSL template for the <chapter.description.list> element.

30: Close the XSL stylesheet.

5.3	Output HTML

Below is the HTML Output that has been transformed from XML.

<html>	1
<head>	2
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">	3
<title>Common Acronyms</title>	4
</head>	5
<body>	6
<center>	7
<h1>Common Acronyms</h1>	8
<p>This is a list of acronyms and abbreviations.</p>	9
<hr>	10
<table width="70%">	11
<tr>	12
<td><b>1. API.</b></td>	13
<td>Application Programming interface</td>	14
</tr><tr>	15
<td><b>2. ASCII.</b></td>	16
<td>American Standard Code for Information Interchange</td>	17
</tr>	18
<tr>	19
<td><b>3. ASP.</b></td><td>Active Server Pages</td>	20
</tr>	21
<tr>	22
<td><b>4. B2B.</b></td>	23
<td>Business to Business</td>	24
</tr>	25
<tr>	26
<td><b>5. B2C.</b></td>	27
<td>Business to Consumer</td>	28
</tr>	29
<tr>	30
<td><b>6. BMI.</b></td>	31
<td>Body Mass Index</td>	32
</tr>	33
<tr>	34
<td><b>7. BPML.</b></td>	35
<td>Business Process Modelling Language</td>	36
</tr>	37
<tr>	38
<td><b>8. BPMS.</b></td>	39
<td>Business Process Management Systems</td>	40
</tr>	41
<tr>	42
<td><b>9. BPQL.</b></td>	43
<td>Business Process Query Language</td>	44
<tr>	45
<td><b>10. CALS.</b></td>	46
<td>Computer-Aided Acquisition and Logistics Support</td>	47
</tr>	48
<tr>	49
<td><b>11. CAN.</b></td>	50
<td>Controller Area Network</td>	51
</tr>	52
<tr>	53
<td><b>12. CC.</b></td>	54
<td>Container Catalog</td>	55
</tr>	56
<tr>	57
<td><b>13. CGM.</b></td>	58
<td>Computer Graphics Metafile</td>	59
</tr>	60
<tr>	61
<td><b>14. CLIR.</b></td>	62
<td>Cross Language Information Retrieval</td>	63
</tr>	64
<tr>	65
<td><b>15. CMS.</b></td>	66
<td>Content Management System</td>	67
</tr>	68
<tr>	69
<td><b>16. COBOL.</b></td>	70
<td>COmmon Business Oriented Language</td>	71
</tr><tr>	72
<td><b>17. COM.</b></td>	73
<td>Component Object Model</td>	74
</tr>	75
<tr>	76
<td><b>18. CPP.</b></td>	77
<td>Collaboration Protocol Profiles</td>	78
</tr>	79
<tr>	80
<td><b>19. CSS.</b></td>	81
<td>Cascading Style Sheets</td>	82
</tr>	83
<tr>	84
<td><b>20. DBMS.</b></td>	85
<td>Database Management Systems</td>	86
</tr>	87
<tr>	88
<td><b>21. DDB.</b></td>	89
<td>Device Database</td>	90
</tr>	91
<tr>	92
<td><b>22. DI.</b></td>	93
<td>Document Instance</td>	94
</tr>	95
</table>	96
</center>	97
</body>	98
</html>	99

6 Further Information and References

6.1	Associated documentation

xmlparser

xml_conf

Technote 0077; Libxml Parser; 7.77

If using HTML (online or local) documentation, mouse over the links above for a summary.

6.2	Internet Resources

The World Wide Web Consortium (W3C) XSLT activity and information:

www.w3.org/Style/XSL/

General and in-depth information about XML and XSLT:

www.xml.com

News, education, and information about XML in industrial and commercial settings:

www.xml.org

Information about EXSLT:

www.exslt.org/

6.3	Books/Literature

XSLT

Doug Tidwell

Published by O'Reilly.

XSLT Programmer's Reference

Michael Kay

Wrox Press Ltd.

XSLT For Dummies

Richard Wagner

Published by Hungry Minds Inc.

7 Subject Index

Subject index only applicable to the PDF version.

Document created on 17-Sep-2002, last reviewed on 03-Oct-2005 (revision 3)

Summary

Contents

1

2

2.1

2.2

2.3

2.4

2.5

3

3.1

3.2

3.2.1

3.3

3.4

3.5

3.5.1

3.5.2

3.5.3

3.5.4

3.5.5

3.6

3.7

3.8

3.9

4

4.1

5

5.1

5.2

5.3

6

6.1

6.2

6.3

7