This tutorial assumes:
- You are interested in XSLT. Previous knowledge of XSLT is not required
for this tutorial. The XSLT Tutorial walks you through a simple program and
later suggests various resources for further information.
In the Perl Tutorial,
a Perl program converts a text file containing exported email messages to an
XML file. In this tutorial, XSLT converts the XML file to HTML. Note that you
do not need to complete the Perl Tutorial before doing the XSLT Tutorial. Each
tutorial can be completed independently. In this tutorial you will:
-
Open the XSLT Tutorial Project and associated files.
-
Analyze mailexport.xml the XSLT program
included in the XSLT Tutorial Project.
- Run the Program
and generate HTML output through the transformation.
- Debug the program
using the Komodo debugger.
On File menu, click Open|Project
and navigate to the xslt_tutorial.kpf project file on the
xslt_tutorials subdirectory. The location differs depending on your
operating system.
Windows
<komodo-install-directory>\lib\support\samples\xslt_tutorials
Linux
<komodo-install-directory>/lib/support/samples/xslt_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/xslt_tutorials
All files included in the tutorial project are displayed on the
Projects tab in the Left Pane.
On the
Projects tab, double-click the files mailexport.html,
mailexport.xml, and mailexport2html.xsl. These files
open in the Editor Pane; a tab at the top of the pane displays each of
their names.
- mailexport.xml: An input file that contains email
messages converted to XML format. (See how this was done in the
Perl Tutorial.)
- mailexport2html.xsl: An XSLT program that
generates an HTML file from the mailexport.xml input file.
- mailexport.html: A file that stores the HTML output
from the XSLT transformation.
In this step, you will analyze the XSLT program on a line-by-line basis.
Open the XSLT Tutorial Project and associated files as described in
the previous step. Be sure
Line Numbers are enabled in Komodo (View|View Line Numbers).
Be sure the mailexport2html.xsl file is displayed in the Komodo Editor
Pane.
Lines 1 to 3 - XML and XSLT Declarations
- an XSLT program is an XML document - thus, the XML version and
character set are declared on the first line
- the namespace declaration on the second line tells the "parser" (the XSLT
interpreter) that XSLT elements are prefixed with
xsl: to prevent
confusion with user-defined element names and non-XSLT elements
xsl:output controls the appearance of the generated output;
for example, the presence of this line generates a META
declaration in the head of the HTML output
Komodo Tip: Notice that different
types of language elements are displayed in different colors. Adjust the
display options for language elements in the
Preferences dialog box. |
XSLT Pointer: Processing routines
in XSLT programs are enclosed in opening and closing tags similar to those
in XML. |
Line 6 - XSLT "template"
template is the main processing element in an XSLT program
- the
match="/" attribute specifies that the template is
selected when the document element is processed
XSLT Pointer: XSLT commands have
(up to) four components:
namespace ("xsl"), element ("template"), attribute(s) ("match="), and
attribute value(s) ("/"). |
XSLT Pointer:
XSLT uses XPath expressions to select data from XML documents. On
line 6, match="/" selects a "node" in the XML document's
hierarchy, rather than a specific item of data. |
Lines 7 to 11 - HTML Tags
- writes standard HTML tags to the output document
Line 12 - XSLT apply-templates
- processes each node of the XML document (that is, each sub-section
contained beneath the current position in the XML document)
- for each node, the XSLT "engine" (the internal processor) checks the
XSLT program for a matching template
- the first XML tag with a corresponding template is
<EMAIL>
Lines 13 to 15 - HTML Tags
- after processing all the nodes in the XML document, processing
returns to line 13, where the closing tags for the HTML page are written to
the output
- line 15 closes the XSLT processing routine, completing the program
Lines 18 to 21 - Select HEADER content
- when line 18 is processed, content in
<HEADER>
tags in the XML document are processed
- lines 19 and 21 write standard HTML formatting around the content
generated in line 20
- on line 20, the
value-of statement selects content
contained in the <SUBJECT> tag and writes it to the
output document
Komodo Tip: Click the
minus symbol to the left of line 19. The entire section of nested code
is collapsed. This is called
Code
Folding. |
Lines 22 to 29 - call-template
- after the
From: text, the call-template routine
causes the XSLT program to proceed to the template formatEmail
on line 51; after completing the formatEmail routine, processing
returns to line 23
with-param indicates that the parameter address
should be applied to the contents of the <ORIGADDRESS>
XML tag
- the same selection and formatting routine is applied to the contents of the
<DESTADDRESS> XML tag on lines 26 to 28
XSLT Pointer: Notice the
<BR/> HTML tag on line 25. XML and XSLT treat all tags as
container tags that have both opening and closing elements. However, some
HTML tags (like <BR> and <IMG> )
stand alone, and do not require a closing tag. They are represented with a
closing slash. XSLT tags also use a closing slash if they are not a tag pair
(as shown on line 23). |
Lines 33 to 34 - Process First Message
- when the
apply-templates tag in line 12 is encountered,
processing jumps to line 33
- on line 34, the
HEADER node is selected and processing jumps
to line 18
XSLT Pointer: Comments in XSLT
programs are enclosed in the tags <!-- and --> ,
the same as in HTML. |
Lines 36 to 39 - Process Email Body
- after processing the email header, the XSLT program proceeds to line 36
- the contents of the
BODY tag are placed in the HTML tags
Komodo Tip: XSLT programs and XML
input documents must be "well-formed" in order to perform transformations.
Komodo's
Background Syntax Checking makes it easy to identify and fix coding
errors. |
Lines 45 to 52 - Format Email Addresses
- the routine that starts on line 47 is called from lines 22 and 26
address parameter contents are determined on lines 23 and 27
- on line 49, the contents of the
address parameter are
converted to a variable and concatenated with the text that constitutes a
valid email address reference in HTML
To start, generate program output by running the program through the
debugger without setting any breakpoints.
- Assign XML input file: On the Debug
menu, click Go/Continue. In the
Debugging
Options dialog box, specify mailexport.xml as the XML input
file. Use the Browse button to navigate to the directory
containing the XSLT tutorial project files.
- Run the debugger: Click OK to run the
debugger.
- Stop the debugger: From the Debug menu,
select Stop to end the debugging process.
- View Debug Output: Notice the messages displayed on the
status bar in the bottom left corner of the screen; these indicate the
debugger status. The results of the transformation are displayed on
the Debug tab.
- View the Output as HTML: On the right side of the Bottom
Pane, click the HTML tab. The rendered HTML is displayed in
the Bottom Pane. Click the Output tab to return to the
HTML code.
- Create New File: To create a new HTML file that will later
contain the HTML code in the Bottom Pane, select File|New|New File.
In the New File dialog box, select the HTML Category.
Click Open.
- Save the Output: Delete the contents of the new HTML file
tab in the Editor Pane, and then select the contents of the Output
tab on the Bottom Pane. Copy the contents to the new HTML file tab in the Editor
Pane. Select File|Save As to save the file with a unique name.
This section reviews how to add breakpoints to the program and "debug" it.
Adding breakpoints lets you to run the program in parts, making it possible to
watch variables and view output as they are generated. Before beginning, be
sure that line numbering is enabled in Komodo
(View|View Line Numbers).
- Step In/Assign the XML input file: If necessary, click on the
mailexport2html.xsl tab in the editor. From the menu, select
Debug|Step In. In the
Debugging
Options dialog box, specify mailexport.xml as the XML
input file. This should already be set if the input file was assigned in the
previous step. Assigning the XML
input file to the XSLT program file selects the XML file as the default input
file when running the transformation.
- Start Debugging: In the
Debugging
Options dialog box, click OK to start debugging.
Komodo Tip: Debugger commands
can be accessed from the Debug menu, by shortcut keys,
or from the Debug Toolbar. For a summary of debugger
commands, see the
Debugger
Command List. |
- Watch the debug process: A yellow arrow on line 7
indicates the position in the XSLT file where the debugger has halted.
- View Debug tab: In the
Bottom Pane,
click the Debug tab. On the right side of the
Debug tab, click the Call Stack tab.
On the Call Stack tab, notice that the current call stack
is the template in line 6 of the XSLT program.
- Set a breakpoint: On the
mailexport2html.xsl tab in the Editor Pane, click the
gray margin immediately to the left of the code on line 12. This sets a
breakpoint, indicated by a red circle.
Komodo Tip: Breakpoints can be set
at any time. An enabled breakpoint is a solid red circle. A disabled
breakpoint is a white circle with a red outline. Click once in the gray
margin to enable a breakpoint. Click an enabled breakpoint once to disable
it. |
- Line 7: Continue: Select
Debug|Go/Continue. The debugger runs until it
encounters the breakpoint on line 12. If no breakpoint had been set,
the debugger would have run to the end of the program.
- Line 12: Step In: Click Debug|Step In.
Notice the debugger jumps to line 33 of the XSLT program, and shows a
pointer in the XML file on line 3. When the debugger processed line 12
(
xsl:apply-templates ), it looked for a template that matched the
top node in the XML document (<EMAILCOMMENTS> ). When no
matching template was found, it proceeded to the next node in the XML document
(<EMAIL> ) and found a matching template on line 33.
- View the Debug tab: Notice that the
Call Stack tab displays the current template match. Previous
template matches can be selected from the list; double-clicking them
jumps to the corresponding lines in both files.
- Line 33: Step In: Use the Step In
command until the current-line pointer in the XSLT file is on line 20.
- Line 20: Step In: Watch the Bottom Pane as
you Step In line 21. The
xsl:value-of statement selects the
contents of the <SUBJECT> field on line 7 of the XML file
and places it within the HTML tags on lines 19 and 21.
- Line 21: Step In: Line 22 calls the template
formatEmail on line 45. Continue to step in until line 49 is
processed. The formatEmail template is processed with the
address parameter on line 46. This routine processes the contents
of the <ORIGADDRESS> node in the XML document. In order to
generate the hyperlink in the output HTML document, lines 48 and 49 concatenate
the string mailto: with the contents of the
<ORIGADDRESS> node.
- Line 49 to end: Go/Continue: On
Debug menu, click Go/Continue to run
the rest of the XSLT program. The program's output is displayed in the
Bottom Pane: raw output in the Output tab and rendered output in the
HTML tab.
ASPN, the ActiveState Programmer Network
ASPN, the ActiveState
Programmer Network, hosts the
XSLT Cookbook,
a collaborative library of XSLT code.
Documentation
The W3C (World Wide Web Consortium) specifications are available online:
Tutorials and Reference Sites
There are many XSLT tutorials and beginner XSLT sites on the Internet,
including:
|