XSLT Editor and Debugger

Features

Using the XSLT Editor and Debugger

Liquid Studio provides extensive XSLT authoring, processing and debugging tools. XSLT is useful in a wide range of projects, particularly where XML data is being output for Web publishing. However, while XSLT syntax is relatively simple, authoring XSL transforms for successful results can be an error-prone process. With the Liquid XML XSLT debugger, you can create your transforms, execute them to see the results and debug them to produce reliable output. Let's work through the process.

Authoring

As with all XML editing tasks in Liquid Studio, the software provides intellisense prompts, auto-complete, syntax / error highlighting, validation and output previews when creating XSLT documents. The images and sample code below use the following source XML data to demonstrate XSLT processing:

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML (http://www.liquid-technologies.com) -->
<?xml-stylesheet type="text/xsl" href="research.xsl"?>
<research>
    <section heading="physics">
        <volume format="book">
            <details>
                <author>Jim Smith</author>
                <title>The Universe</title>
                <published>1991</published>
                <rating>5</rating>
            </details>
        </volume>
        <volume format="paper">
            <details>
                <author>Mary Jones</author>
                <title>All About Particles</title>
                <published>1999</published>
                <rating>7</rating>
            </details>
        </volume>
        <volume format="book">
            <details>
                <author>Mark Johnson</author>
                <title>Radioactivity</title>
                <published>2003</published>
                <rating>2</rating>
            </details>
        </volume>
    </section>
    <section heading="language">
        <volume format="book">
            <details>
                <author>Maria Davidson</author>
                <title>Prepositions and Pronouns</title>
                <published>1998</published>
                <rating>6</rating>
            </details>
        </volume>
        <volume format="paper">
            <details>
                <author>Arthur Jackson</author>
                <title>French Verbs</title>
                <published>2000</published>
                <rating>4</rating>
            </details>
        </volume>
        <volume format="paper">
            <details>
                <author>John McDonald</author>
                <title>Syntax in German</title>
                <published>1989</published>
                <rating>8</rating>
            </details>
        </volume>
    </section>
    <section heading="computing">
        <volume format="paper">
            <details>
                <author>James Harrison</author>
                <title>Processors</title>
                <published>1996</published>
                <rating>2</rating>
            </details>
        </volume>
        <volume format="book">
            <details>
                <author>Sarah Thomson</author>
                <title>How RAM Works</title>
                <published>2003</published>
                <rating>5</rating>
            </details>
        </volume>
        <volume format="paper">
            <details>
                <author>Thomas Donaldson</author>
                <title>Computer Architecture</title>
                <published>2005</published>
                <rating>8</rating>
            </details>
        </volume>
    </section>
</research>

Notice that the XML links to an XSL file in its stylesheet element - this will make client applications automatically use the transforms when rendering the XML data. When you author and execute your XSL transforms in Liquid Studio you can specify a source input file to test the transforms on.

A common use of XSLT is to transform the XML data into a Web page, with the XSLT writing out the XML data items in HTML markup, so that is what the sample code below will demonstrate. To create a new XSLT file, click the New button and choose "XSLT 1.0", "XSLT 2.0" or "XSLT 3.0".

You can save your new file with a name of your choice, again either choosing XSLT 1.0, 2.0 or 3.0 as the type depending on your requirements. Inside the xsl:stylesheet element, you can enter your XSLT structures.

To see the code editing tool in action, start by typing "<" - you will be presented with a list of elements you can include in your XSLT. When you start to build the HTML elements for your output you will see that the editor also prompts you with these. You can either browse through the list or filter the options by starting to type your required element - try it with the output element by typing "<xsl:o" - notice that the intellisense prompt continually updates to present relevant syntax as you type. Choose the output element from the list.

When you select the output element, its opening tag is inserted into the document. This is a self-closing element, but for elements with separate opening and closing tags the editor will automatically enter the closing tag. When you type a space in an opening tag, you will be prompted with relevant attributes - select method from the list.

Enter the attribute value, using "html" if you plan on producing a Web page. After the method attribute, insert another space and choose indent from the list - this time notice that the intellisense prompt presents the two possible attribute value options, "yes" and "no". You can benefit from this auto-complete functionality for attribute values whenever there is a finite range of options. Choose a value either using your arrow keys or the mouse.

As you can see, the editor offers relevant suggestions to save on the amount of manual coding you have to carry out wherever possible. You can distinguish between entity types at a glance from the displayed icons, with the options including elements, attributes and complex types.

Complete the body of your XSLT file, using the following sample if you simply want to see the XSLT processing engine in action.

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML (http://www.liquid-technologies.com) -->
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns="http://www.w3.org/1999/xhtml">
                <xsl:output method="html"
                indent="yes"
                doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"
                doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
encoding="UTF-8" />
    <xsl:param name="Heading">Output Heading</xsl:param>
    <xsl:template match="/">
        <html>
        <head>
        <title>Research</title>
        <style type="text/css">
            body, html {
                font-family:Arial, Tahoma, sans-serif; 
                color:#FFFFFF; 
                background:#000000; 
                width:80%; 
                margin:auto; 
                padding:10px;}
            div.physics {background:#330000;}
            div.language {background:#003300;}
            div.computing {background:#000033;}
            p.book {font-weight:bold; padding:5px;}
            p.paper {font-style:italic; padding:5px;}
        </style>
        </head>
        <body>
            <h1><xsl:value-of select="$Heading"/></h1>
            <xsl:apply-templates select="research/section"/>
            <p>*21st century</p>
        </body>
        </html>
    </xsl:template>
    <xsl:template match="section">
        <div>
        <xsl:attribute name="class">
            <xsl:value-of select="@heading" />
        </xsl:attribute>
        <xsl:for-each select="volume">
            <xsl:sort select="details/title" />
            <xsl:apply-templates select="details" />
        </xsl:for-each>
        </div>
    </xsl:template>
    <xsl:template match="details">
        <p>
        <xsl:attribute name="class">
            <xsl:value-of select="../@format" />
        </xsl:attribute>
        <xsl:value-of select="title" />: 
        <xsl:value-of select="author" />
        <xsl:choose>
            <xsl:when test="rating > 7">
             (Excellent)
            </xsl:when>
            <xsl:when test="rating > 5">
             (Good)
            </xsl:when>
            <xsl:when test="rating > 3">
             (OK)
            </xsl:when>
            <xsl:otherwise>
             (Poor)
            </xsl:otherwise>
        </xsl:choose>
        <xsl:if test="published > 1999">
             *
        </xsl:if>
        </p>
    </xsl:template>
</xsl:stylesheet>

This sample contains a lot of commonly used structures, including a couple of templates, attributes and some control structures such as for-each, sort and the choose and if conditionals. When the XSLT engine processes this, it will iterate over the "section" elements, working through each "volume/details" element in turn. Notice that the XSLT contains a parameter named "Heading" - you can pass this into the transformation process as an input value using the configuration options outlined below.

Editing

While you're working with your XSLT files the editor will highlight any syntax errors with red lines. By keeping the Error List window open you can see a rundown of errors in the current document, double-clicking on any to jump to the error location in code. The following screenshot shows this when we introduce an error into the XSLT code above, attempting to start one template declaration inside the previous one:

You can also use the validator on your XSLT markup by clicking the "Validate Document" () button or F7 at any time. If you have any experience using markup validation you will know that a single error can cause multiple knock-on errors, so start at the first error in the list, fix it then save or validate again to see what, if any, errors remain.

Configuration

Developing and debugging XSLT successfully requires processing your transforms into output markup. As well as examining the output code, having the ability to step through the transformation process can be an essential tool in identifying any errors - this is what the XSLT debugger allows you to do. Set the debugging options by clicking "Configure Debugger" () or F2.

The Debugger Configuration screen can be used to prepare for detailed debugging of your XSLT code and output. You can analyse what is happening throughout the process by splitting it into steps, or you can simply execute the XSL transforms, emulating what will happen in the client application, e.g. the Web browser. Either way, you will use the configuration screen to set what happens when you run the XSL transforms.

The Main Module Filename represents your XSLT document, which should already be populated with the file you were working on when you entered the configuration screen. The Context Item represents the source XML you want to execute the transforms on. The Output section allows you to specify a file to write the output markup into so that you can then examine the results of your transformations. This is where Liquid Studio can be much more useful than simply executing your XSLT in the client, because you are writing the HTML or other output into a dedicated file. Since it will also be XML structured, you can then examine, validate and troubleshoot the markup and rendered appearance all within the software.

In the Context Item field, browse to your source XML data. In the Output Filename field, enter a location and name for your output file, with ".html" as extension and HTML selected in the Format list if you are generating a Web page.

The configuration screen also provides the ability to use input parameters. The Input Values section allows you to pass such data parameters into your XSLT. Click "Add" to define a parameter.

In the Edit Variable pop-up, enter a name, an optional namespace and a value, optionally reading the value from a file. For the sample code above, in which we included a parameter, enter "Heading" as the name and "Research Data" as the value, leaving the "Text Value" radio button selected - click "OK". You will see the parameter listed in the Input Values section. Click "OK" to configure the options for your XSLT document.

You can receive any passed parameter values in your XSLT code. The following excerpts from the example above demonstrate:

<xsl:param name="Heading">Output Heading</xsl:param>
...
...
...
<h1><xsl:value-of select="$Heading"/></h1>

We use the input parameter name to write its value into the output. For the example above the heading element will display "Research Data" in the output HTML.

You can also use the drop-down selector next to the configuration button on the XSLT toolbar to choose between Saxon and .NET engines.

Advanced Debugger Options

Back in "Configure Debugger", advanced options also include the ability to set properties including whitespace and DTD validation rules, as well as start-up options for the Saxon environment. You will see these listed in the bottom area of the configuration screen alongside the Input Values section. Select the Properties tab for fine-tuning the XSLT processing details. Select the Start-up Options tab to toggle initialising the Saxon engine with an external .NET assembly.

Processing

By writing the output of your XSL transforms into a separate file, you can then see its source code and rendered appearance, particularly useful when dealing with HTML. Once you have the debugger configured, click the "Start Debugging" () button or F5 to process the transforms. If you need to stop debugging, click the "Stop Debugging" () button or Shift+F5 at any time.

When the XSLT is processed, the editor will open your new HTML file in a separate tab. Switch to it to see the results. You can use the available windows to see the HTML source code or the page as it will render in the browser, or optionally a split view with both.

If your XSLT didn't contain any errors you should see the page you attempted to build in HTML via your XSLT structures. You can again use the Error List window and validation tool to check that your output HTML is well-formed. If there are any problems with your XSLT output, you can use the debugger to identify them.

Here is the HTML output for the example - notice the parameter value passed in during configuration and written out within the "h1" heading element:

<!DOCTYPE html
          PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <title>Research</title><style type="text/css">
        body, html {
            font-family:Arial, Tahoma, sans-serif; 
            color:#FFFFFF; 
            background:#000000; 
            width:80%; 
            margin:auto; 
            padding:10px;}
        div.physics {background:#330000;}
        div.language {background:#003300;}
        div.computing {background:#000033;}
        p.book {font-weight:bold; padding:5px;}
        p.paper {font-style:italic; padding:5px;}
    </style></head>
    <body>
        <h1>Research Data</h1>
        <div class="physics">
        <p class="paper">All About Particles: 
        Mary Jones 
        (Good)
        </p>
        <p class="book">Radioactivity: 
        Mark Johnson 
        (Poor) 
        *
        </p>
        <p class="book">The Universe: 
        Jim Smith 
        (OK)
        </p>
        </div>
        <div class="language">
        <p class="paper">French Verbs: 
        Arthur Jackson 
        (OK) 
        *			
        </p>
        <p class="book">Prepositions and Pronouns: 
        Maria Davidson 
        (Good)			
        </p>
        <p class="paper">Syntax in German: 
        John McDonald 
        (Excellent)			
        </p>
        </div>
        <div class="computing">
        <p class="paper">Computer Architecture: 
        Thomas Donaldson 
        (Excellent) 
        *
        </p>
        <p class="book">How RAM Works: 
        Sarah Thomson 
        (OK) 
        *	
        </p>
        <p class="paper">Processors: 
        James Harrison 
        (Poor)
        </p>
        </div>
        <p>*21st century</p>
    </body>
</html>

Debugging

Being able to view and validate the output of XSLT is useful, but errors can be difficult to locate manually - ideally you want to see what is happening while the transforms are being executed. The XSLT debugger lets you step through this process. By adding breakpoints to your XSLT code, you can see the output being built a step at a time, making it far easier to spot when things are going wrong.

With an XSLT file open, add breakpoints by clicking in the margin to the left of the structure you want to pause execution at, or pressing F9 with the relevant line of code selected.

During debugging, the XSLT will pause processing when it reaches a breakpoint. If a breakpoint is placed inside an element which will be matched or executed more than once for the source data, for example a template or for-each element, the execution will pause once for each instance of the matched entity. So for the above example, if we place a breakpoint at the "details" template, the execution will pause 9 times since there are 9 "details" elements. This means that you get to see the processing stages iterate over the source. You can toggle your breakpoints on and off while debugging using the "Toggle Breakpoint" () button or F9.

Click the "Step Into" () button or F9 to move to the first processing step in the XSLT.

A range of useful debugging windows are opened.

Now you can press the "Start Debugging" () button to work through the transforms. Each time the XSLT engine encounters a breakpoint it will stop. As the debugger steps through the transforms, you can see the elements in the output document being built.

You can configure the visible views to interact with the debugging data in a way that suits your needs. In the Breakpoint Window, you can right-click on listed breakpoints to disable, enable or delete them as well as using the Goto option to jump to the breakpoint location in code. Continue pressing "Start Debugging" () until your transforms are complete.

For a finer level of control over the processing during debugging, use the other buttons in the Debugging toolbar. You can step over () when execution is paused, to resume execution and pause after the current operation is complete. Step out () to resume, when all operations in the current call stack are complete. While the debugger is running you can use the "Pause" () button to pause at the next operation. Use the Stack Trace window during debugging to see the functional context of any paused operations.

While your XSLT is being processed you can see contextual data in the Variables window, in which you can explore relevant variable data by expanding and collapsing nodes. If your XSLT uses input parameter they will be displayed here.

Another tool you may find useful with the debugger is the Watch expression utility. You can use this to examine data items during debugging via expressions. With your XSLT file open, click to step into the processing instructions. Open the Watch window and right-click in it. Choose "Add Watch Expression" from the list.

In the Watch Expression Editor, add an expression you wish to check during debugging. For example, since we have a breakpoint at the "details" template in the above example, we could check the length of the "title" element string inside the current "details" element using the following code:

string-length(title)

Clicking the "Start Debugging" () button will step through the transforms, pausing at the breakpoints as usual. Each time the debugger pauses at a breakpoint, the watch expression will be re-evaluated. In this case the value will reflect the length of the "title" element value inside each "details" element. Notice that the Watch and Variable windows distinguish types at a glance using different icons for elements, attributes, text, CDATA, comments and so on.

This can be extremely useful if you wish to analyse data values during your XSLT processing. Delete, edit and re-evaluate Watch expressions by right-clicking them in the Watch window.

Usage

Using the XSLT debugger is a straightforward process in most cases, but the tool is also highly configurable for complex projects, so explore the configuration settings if you have particular requirements.

The XSLT processing and debugging tools in Liquid Studio offer a level of detailed troubleshooting and fine-tuning that should provide the ability to produce reliable results even in the most complex cases. However, if your needs are less complex in nature and you simply want to run through the transformation process, checking your output for reliability, you can do so in a few straightforward steps - just configure the debugger to write to an output file and execute your transforms without setting any additional debugging options such as breakpoints, watch expressions or variables. The process is quicker and easier for HTML output than continual browser tests, as you can preview and troubleshoot, all within a single environment.