XSLT Debugger

xml spy
XSLT Debugger

XSLT Debugger allows you to create and edit XSLT stylesheets to transform XML documents into other document formats. You can comfortably edit and debug XSLT stylesheets, view the contents of variables and parameters of the current node, and have the results of each step displayed in a separate window.

Features:
· Altova XSLT engine with additional support for Microsoft MSXML 3.0 and 4.0 processor
· Debug XML and XSL files in Grid and Text view
· Dynamic Output in Grid, Text and Browser views
· Single stepping: Step into, Step out and Step over
· Node based breakpoint management
· Call Stack and Context windows
· View and change variables during execution
· Watch windows with complete XPath support
· Template Explorer with Priorities

Top Next

© 2002 Altova


Overview

Overview

There are two main areas that make up XSLT Debugger, the three data windows and the two debugger info windows below.

The data windows consist of the XML file to be transformed, the XSLT stylesheet that defines how the transformation is to occur, and the Output window that displays the current state of the transformed document.

· The debugger XML and XSLT windows can be displayed in both Enhanced Grid and Text views while debugging. The debugger has to be stopped if you want to change the view of either window. A prompt appears telling you that this needs to be done if you are viewing either document in a different view when the debugger is started.
· The Output window can be additionally displayed in the Browser view. The Output view can be changed at any time during the debugging session, the debugger does not have to be stopped.

The debug info windows contain the Show Context and Show Callstack windows, which each contain several tabs supplying all necessary debug info.

A debugging session starts when you start the debugger using the Start Debugger/Go command. XSLT Debugger allows you to debug multiple files in a debugging session, you are not confined to just one XML/XSL document pair.

Stopping a debugging session does not terminate it, this must be terminated explicitity by selecting XSL | End Debugger session.

Depending on how you associate the respective XML/XSL documents, you can easily debug multiple XSLT stylesheets using a single XML source file, or use one XSLT file for several XML files.

Previous Top Next


Associating XML and XSLT files

Associating XML and XSLT files

To debug an XSLT file you need to associate it with a corresponding XML file, which supplies the necessary data. There are several methods of associating XML and XSLT files:

Direct assignment:
This method inserts the appropriate assignment declaration in the specific file. The debugger does not have to be active to do this.

· Open the XML file (in Text or Enhanced grid view), select the menu option XSL | Assign XSL, and select the XSL file, and/or
· Open the XSLT file, select the menu option XSL | Assign sample XML file..., and select the XML file.
Each option directly inserts the approiate declaration in the XML and XSL file. Using this option facilitates debugging as you are not prompted for the appropriate XML or XSLT files during the debugging session.

Assignment on the fly:
This method allows you to associate files when starting or running the debugger.

· Open/click an XML file and select the menu option XSL | Start Debugger/Go. You will be prompted to select an associated XSLT file, or
· Open/click an XSLT file and select the menu option XSL | Start Debugger/Go. You will be prompted to select an associated XML file.

Assignment using Project properties:
The Project properties window allows you to assign XML and XSLT files during debugging, on a project or folder basis.

1. Click the project name or the specific project folder, and select the menu item Project | Project properties.
2. Select the Use this XSL / Use this XML check box, and use the Browse button to select the files you want the project or folder to be associated with.

Defining the XSLT debugger Output:
You will generally transform XML files into HTML files. You can, however, transform them into XML files as well:

1. Right click the project or folder (in the project window) containing the XML files you are converting.
2. Select the menu option Project | Project properties.
3. Define the folder that will contain the transformed files, and select the file extension of the transformed files, in this case File extension is .xml.


Symbols and icons

Symbols and icons

View the active document only
Maximizes the currently active document in the debugger.

View XSLT and Output
Displays the XSLT and Output windows, while hiding the XML window.

View XML, XSLT and Output
Displays all three windows in the upper half of the debugger, this is the default view.

Start Debugger/Go Hotkey: CTRL+F10
Starts or continues processing the stylesheet till the end. If breakpoints have been defined, then processing will be paused at that point.

If the debugger session has not been started, then this button will start the session and stop at the first node to be processed. If the session is running, then the XSLT will be processed to the end, or until the next breakpoint is encountered.

Stop Debugger
Stops the currently active debugger session. To restart the debugger session, click the Start Debugger/Go (or Step Into or Step Over) icon.

Restart Debugger
Restarts the debugger and clears the output window.

End Debugger Session
Ends the Debugger session and returns you to the normal XMLSPY 5 view active prior to starting the debugger. The documents that were open during the debug session, remain open in the main window (depending on the settings in XSL | XSLT Debugger Settings).

Step into Hotkey: F11
Single steps through all nodes in the stylesheet including all template code. This command can start the debugger. Please note that the debugger only steps onto open nodes, the closing nodes are ignored.

Step Out Hotkey: SHIFT+F11
From the current node, steps out to the next sibling of the parent node if it exists. If not, steps out to the next node at the same level as the parent, or higher.

Step Over Hotkey: F10
From the current node, steps to the next node at the same level as the current node, or higher. This command can start the debugger.

Show current execution node
Displays/selects the current execution node. This is useful when you have clicked in other tabs which show or mark specific code in the XSLT stylesheet or XML file, and you want to return to where you were on your last step.

Insert/Remove Breakpoint Hotkey: F9
Inserts or removes a breakpoint at the current cursor position. Note that you can set breakpoints in both the source XML file and the XSLT stylesheet during debugging. Breakpoints cannot be defined on closing nodes.

Breakpoints can be defined down to the node level, and can be set for elements and attributes. A dashed red line appears above the node when you set a breakpoint.

Please note: Breakpoints on attributes that are part of an XSL element, in XSL stylesheets, are usually not processed, as they are generally part of the XSL element that is being processed.

Enable/Disable Breakpoint Hotkey: CTRL+F9

This command enables or disables previously defined breakpoints. The red breakpoint highlight changes to gray, to differentiate between the two. The debugger does not stop at disabled breakpoints.

XSL Breakpoints dialog
This dialog box displays the currently defined breakpoints in all currently open XML and XSLT files, both enabled, as well as disabled.

· Edit Code, goes to the specific breakpoint in the code
· Remove, deletes the currently selected breakpoint
· Remove All, deletes all breakpoints in the XSLT document
· The check boxes allow you to enable or disable the existing breakpoints


Starting XSLT Debugger

Starting XSLT Debugger

This section uses the OrgChartDebug.xslt stylesheet to describe the main features of XSLT Debugger. Please note that this XSLT file only shows off the debugger features, it is not intended to be a real-life example. You can also use the OrgChart.xml file in the Examples folder, to debug a larger XSLT file.

Aim of the XSLT stylesheet is to:
· extract the first name and surname of all OrgChart employees for each office
· sort the employees by surname
· output a complete list of these employees by first and then surname
· test a condition and perform a conditional output
· display text conditionally, using variables defined by an XPath expression

The XSLT Stylesheet uses the following constructs to extract the data:
· An XSL variable "Chrisitian Name", which stores the first names
· A template called "Surname", which extracts the Family names, using
· an XSL parameter "Family-Name", which stores the family names, and
· XSL with-param, which allows you to override the default parameter
· An XSL variable "Num-Employees", which stores the resulting XPath expression for the number of employees in each office

To start XSLT Debugger:
1. Open the XML document to be transformed in XMLSPY 5, using the menu option File | Open (e.g. OrgChart-Debug.xml from the ..\Examples folder).

2. Select the menu option XSL | Start Debugger/Go, or hit the CTRL+F10 hotkey.
A message appears stating that the document view will be changed to the Text view, click OK to confirm.
This opens the XSLT Debugger, and stops at the first node to be processed. You are ready to start debugging the XSLT file.

The top half of the display shows three windows:
· The top window contains the XML file you want to transform.
· The middle window contains the XSLT file that defines how the transformation is to occur.
· The right window displays the generated output file defined by the XSLT Stylesheet. This window is currently empty.

The lower half of the display shows two windows:
· The Context and Callstack windows, which display debug information in several tabs.

Please note:
· The OrgChart.xml file contains a declaration assigning the OrgChartDebug.xslt file to it.
· Likewise, the OrgChart.xslt file contains a declaration assigning the OrgChart.xml file to it.


Starting the debugging process

Starting the debugging process

To start the debugging process:
Having opened/enabled the debugger,
1. Click the Step into icon, or hit F11.
2. Hitting F11 several times, inserts the company title and associated headings into the Output window.

When the xsl:variable... statement is processed, the variable "Christian-name" appears in the Variables tab.

3. Click the Node Set hyperlink in the Value column (the number in brackets, displays the number of nodes in the node fragment).
This displays the context node name First, and the string value Jessica in the Node Set window. Note that the XML file also displays the corresponding node and contents.
4. Click the Start Debugger/Go icon to transform the rest of the XML document and have the complete result appear in the Output window.
5. Repeat this process with a breakpoint set on the variable "Num_Employees".
6. Hit F11 several times (Step into), and watch the variable value in the Variables tab.
The XPath statement is evaluated and assigned to the variable "Num_Employees".

Please note:
A letter precedes the variable name in the Variables tab. G denotes a global variable, L a local variable, and P a Parameter.


Setting breakpoints

Setting breakpoints

XSLT Debugger allows you to define node specific breakpoints. You are not confined to defining breakpoints for only a single line in the XSLT code. Breakpoints can be defined for any number of nodes in a line of XSLT code. Breakpoints cannot be set on closing nodes.

Breakpoints can be set in either Enhanced grid or in the Text view. When you press the Start Debugger/Go icon, the processor stops at the first breakpoint and displays all node relevant data in the debugger info windows. Pressing Go again, will take you to the next breakpoint if one has been set, or process the rest of the document till the end.

Breakpoints can be defined using the:

· F9 shortcut key

· menu option XSL | Insert/Remove Breakpoint

· context menu - right click, and select Insert/Remove Breakpoint
· the breakpoint icon [image] in the XSLT toolbar.

Breakpoints can also be set in the source XML file. However, only those nodes that are used as context nodes in the XSLT file can be successfully defined as breakpoints. Non context node breakpoints are ignored during debugging.

To see which nodes are context nodes, single step through the XSLT stylesheet with the Context tab active. Any nodes that appear in this tab, can be defined as breakpoints in the source XML file.

To define a breakpoint in XSLT Debugger:
· Click a node in the XSLT file, and press the F9 shortcut key.

Breakpoints are displayed as a dashed red line, and appear above the node they apply to. Breakpoints appear over an element or attribute name, and only on the start tag of the node.

To continue debugging after a breakpoint
· Press the Step into icon or press the Start Debugger/Go icon.

To delete a breakpoint:
1. Click the specific node containing the breakpoint, and press the F9 shortcut key to delete it, or
2. Select the menu option XSL | Breakpoints.
3. Click the breakpoint in the dialog box, and click the Remove button.

The Remove All button deletes all the breakpoints from the dialog box (and all XSLT stylesheets).

Disabling breakpoints:
Having defined breakpoints in the Text or Enhanced Grid view,
1. Select the menu option XSL | Breakpoints.
This opens the XSLT Breakpoints dialog box which displays the currently defined breakpoints in all open XML source and XSLT stylesheet documents.
2. Remove the check mark of the breakpoint(s) you want to deactivate, and click the OK button to confirm.
Please note: you can also use the CTRL+F9 hotkey to disable breakpoints.

The breakpoint changes from red to gray to show that it has been deactivated. Use the same method to reactivate the breakpoint.

Finding a specific breakpoint:
1. Select the menu option XSL | Breakpoints.
2. Click the specific breakpoint in the breakpoint list.
3. Click the Edit Code button.
The dialog box is closed and the text cursor is placed directly in front of the breakpoint in Text view. In the Enhanced Grid view, the table cell containing the breakpoint is highlighted in red.


Debug Windows

Debug Windows

The debugger editing environment supplies all the necessary options needed to debug code: syntax coloring, tag auto completion and automatic cursor positioning. The debug info windows display all the data you need to debug your XSLT files.

There are two sets of debug windows containing several tabs each:

Show Context window:

· Context: displays the context node and associated attributes or value(s).

· Variables: displays the current variable or parameter.

· XPath-Watch: displays the result of XPath expressions, which you can define here.

· Message: Displays the xsl:message instruction(s), or any error messages that may occur during debugging.

Show Callstack window:

· Call Stack: displays a list of the previously processed XSL instructions.

· Templates: displays all templates used while debugging the current XSLT file. This includes the provided default templates in the built-in template, as well as any included or imported templates.

· Node Set: displays the name and value of the current node set.

Some of the tabs in the debug windows allow you to display and select nodes by clicking an entry in the tab. The specific nodes are then displayed in either the XML or XSLT file. These tabs are currently:

· Context tab
· Call stack tab
· Templates tab
· Node Set tab


Context

Context

This tab displays the context nodes and associated attributes or value(s), as well as commented text.

Clicking an entry in the Context tab, displays the specific node in the XML document that is being processed. Any of the nodes that appear in this tab, can be used as breakpoints in the source XML document.


Variables

Variables

This tab displays the global, local and parameter based variables as well as the name and variable value. When the variable value is a node set or node fragment, a hyperlink is displayed in the value column.

Clicking the hyperlink displays the node-set name and value in the Node Set tab. The value in brackets indicates the number of nodes in the node set or node fragment.

Variable scope:
· Global variables, prefixed with a G, are declared at the top level of the stylesheet
· Local variables, prefixed with a L, are declared in a template
· Parameter, prefixed with a P, are passed to a template with the xsl:param command.

Variable types:
· Number
· Boolean
· String
· Node set
· Node fragment

Variables can also deliver a node fragment as a result. The node fragment also appears as a hyperlink; clicking it displays the node-fragment name and value in the Node Set tab. The value in brackets indicates the number of nodes in the node set or node fragment.

Changing variables during debugging:
String, Boolean and Number variables can be changed during the debugging process.

1. Double click in the Value field of one of these types of variable, and change the value/entry.
2. Click the Step Into icon to continue processing the stylesheet.
The new variable value appears in the Output window.

E.g. We want to be able to control if the company name is output, by testing the state of the Show_Company_Name variable which is boolean.

1. Set a breakpoint on the xsl:if variable, then hit F11, to continue single stepping through the stylesheet.
The company name is output when the Show_Company_Name variable is true.

2. Set a breakpoint on the xsl:variable OfficeName.
3. Click the Restart icon to restart debugging, and click the Go icon.
The debugger pauses at the specified breakpoint.
4. Double click in the Value field, and change the true entry, to false.
5. Click the Go icon to continue debugging.

The company name is not displayed in this instance as the xsl:if condition is now false.


XPath-Watch

XPath-Watch

This tab displays the result of XPath expressions, which are evaluated against the root or context node, depending on how they are entered. You can define the XPath expressions you want to monitor here.

To enter an XPath:
· Double click in the text field under the Name column and enter the XPath.

Please note:
You have to use a namespace prefix for each node, if a namespace has been declared in the XML file or XSLT stylesheet.

You can also watch for variables or parameters using the appropriate XPath syntax. E.g. to see the family names parameter, enter $Family-name.

An XPath statement can also deliver a node fragment as a result. (The node fragment also appears as a hyperlink; clicking it displays the node-fragment name and value in the Node Set tab.)


Message

Message

This tab displays the xsl:message instruction(s), or any error messages that may occur during debugging.

In this example, the message above appears when the node value of the variable "Show_Company_Name" is set to true.


Call Stack

Call Stack

This tab displays a list of the previously processed XSL instructions and templates, with the current instruction appearing at the top of the list.

Clicking an entry in this window, causes the XSL instruction to be displayed in the XSL window. Clicking on a "Built In Templates" entry, opens the built-in template and displays the specific template code.


Templates

Templates

This tab displays the template name(s) match criteria, mode, template name, priority and location for the current XSLT file. The mode and priority entries, are used to determine which template is to be selected while processing the XSLT file.

Clicking an entry in this window, causes the XSL template to be displayed and selected in the XSL window. The only local template visible here is the Surname template, which supplies the surnames of all employees.

Please note:
If the entry you click is a built-in template, it is automatically displayed in a separate window, in the same position as the XSLT window. E.g. Clicking the processing-instruction() entry, displays the corresponding template in the "Built In Templates" window.

Built-in templates are part of the XSLT specification, and are used when no specific template is defined for the current node in the XSLT file.


Node Set

Node Set

This tab displays the name and value of variables or XPath expressions, which appear as hyperlinks in either the Variables or XPath-Watch tabs.

E.g. Node set of the XPath //n1:Department/n1:Name, entered in the XPath-Watch tab.

A node-set hyperlink has to be clicked for the associated data to appear in this tab. The result can also be a node fragment. E.g. Clicking the Christian-name Node Set entry, causes the associated data to appear in the Node Set tab.

Clicking an entry in the Node Set tab, causes the corresponding value to be displayed in the XML file.


XSLT Debugger Settings

XSLT Debugger Settings

This dialog box allows you to set the global XSLT Debugger settings:

Output Window:
This group lets you define in which view the XSLT output is to be displayed. You can select any of the standard views, or use the default view.

The default view is assigned using the File Types tab of the Tools | Options dialog box. The standard setting for .html files is the Browser view; the diagram below shows how to change this to the Text view.

If you are outputting to XML, select .xml, in the File types list, and choose the (default) view you want this type of file to be displayed in.

Debugging:
Activating "Debug built-in templates", causes the debugger to step into built-in templates code whenever appropriate.

Please note :
This option does not disable the displaying of the built-in templates when clicking this type of template entry in the Templates tab, or if the callstack shows a node from the built-in template file.

Previous Top