Introduction
SketchPath can be used in a number of different ways. However, it is most commonly used to simply and quickly build an XPath expression based on an XML instance, and then view and check the result of the expression. This brief guide takes you through this scenario but does not include topics such as advanced management of XPath expression libraries or renaming prefixes in the Namespace Manager.
First Steps
- Open an XML Source File
- (Optional) Set the Context Node
- (Optional) Select the XPath Version
- Enter the XPath Expression
- Review the Results
- Save the Expression
- View Saved XPath
- Check the Expression
Open XML Source File
Select 'Open' from the File menu (or type Ctrl-O ), and from the 'File Open' dialog, select an XML file to load and use as the source for one or more expressions. The formatted XML text is shown in the central pane, and a tree-view of all the XML elements is shown to the left.
Note: If you wish to open a compressed XML file, as in ODF/ OO-XML you will need to use the 'Open Package' option instead, and then double-click the package item required.
(Optional) Set the Context Node
If you're typing a relative XPath expression (one that doesn't start with the '/' root node character), you will need to set the context node. The easiest way to do this in SketchPath is to double-click on the corresponding node in the Element Tree-View Pane, the left-most pane in the SketchPath view.
The Context Node is highlighted with a 'house' icon (see left image). Also the path for the Context Node is always shown in the SketchPath status bar (above)
The Element Tree-View
(Optional) Set the XPath Version
The XPath version is controlled from the menu on the XPath toolbar (see right). When SketchPath is first opened the XPath version pre-selected on the toolbar is controlled by user settings (see left).
Enter the Expression
The XPath Editor lets you immediately start typing in the expression (or paste it in from another source, if you wish to edit or check an existing expression). As you type in a location-path, so long as the expression is valid and resolves to a node/node-set, the corresponding node(s) in the various SketchPath views will be highlighted. The location-path of the first node returned is also shown immediately above the XPath editor
Note: All the usual undo, redo, copy and paste commands are available through the standard keyboard shortcuts ctrl-z, ctrl-y, ctrl-c, ctrl-v respectively.
IntelliSense
To assist in building the expression, SketchPath includes IntelliSense in the form of a permanently displayed 'Intelli-List' that is populated with possible node-names or values for that context as you type. The first match is highlighted and, if this is the required one, simply press the <tab> key to select it. If another node is required, continue typing until the required node is selected before pressing the <tab> key, to let it auto-complete the value in the editor pane .
The Assist Pane
Using the Mouse
You may of course choose to use the mouse (and/or keyboard) to build the expression. To help with this the Intelli-List is bordered on each side by a column of buttons with the most commonly used operators used in an XPath expression. ('Previous' and 'Next' step buttons are also included here.) Also, if 'Assist' is on, the complete set of XPath Axes and functions are arranged to the right-side of the Intelli-List for convenience.
Clicking on any of these items will result in the XPath editor pane being filled and the expression evaluated. Note that the completion attempts to be smart, so if for example, you click one Axis and then click another Axis (when a node-test is actually required instead), the first Axis will be replaced by the second Axis clicked.
Auto-Generating the Expression
The final way of entering an XPath expression is by auto-generating it by double-clicking either on the XML Pane (raw XML) or on the Nodes Pane to the right of the raw XML Pane.
Auto-Generating: Using a little help from Regular Expressions
SketchPath in Regex Mode
To auto-generate a path, you first need to find it in your source. To assist in this, SketchPath provides a Regular Expression (labelled Regex in the toolboar) mode. Selecting this turns the XPath Editor into a regular expression editor which by default is not case-sensitive.
Complex regular expressions are supported, but often a simple wildcard * (as in xs:*) will be all you need. In this mode the Results Pane lists all the matches, selecting each match returned highlights the XML 'hit' and shows the XML location-path in the 'Current Path' text pane.
Review Results
As soon as you've entered a valid XPath expression the result is evaluated (in the default Auto Mode). If the result of your expression is a nodeset, you can now browse results either by:
(i) selecting nodes in the results list or
(ii) going directly to the tree-view and selecting the 'bookmarked' element nodes indicating the hits
The Results Pane
Either method will result in the the associated raw xml text of the node being selected in the main central view. However, if the nodes in the resultant nodeset are not element nodes the results list provides a more useful method for highlighting the exact node.
The results pane is by default shown in document order (because all node-sets are in document order), but it can be resorted by any of the columns, name, value, type or ordinal document position (labelled '#')
Save XPath Expression
Once you're happy that the XPath expression is a good start and worth keeping, you need to click the 'Run XPath' button. Now, if you're in Auto mode, the expression will already have been resolved as you typed. However, explicitly clicking this button reruns the XPath and saves the expression for reuse in your current session, or to be reused as an XPath variable to be referenced within another XPath expression (by using the $variable-name syntax).
The XPath Editor Toolbar
Note: Saved XPath expressions are saved between sessions as 'unfiled'. You can also save the expressions at any time to a different file by clicking the 'Save XPath' button on the XPath Editor toolbar.
Variables Pane
View (and Reusing) Saved XPath
Each newly saved XPath expression is given a nominal new name and listed in the XPath Variable pane seen to the right of the results list. This pane (see left) shows and manages all the XPath variables that are available to be referenced within the next XPath expression. Rename any expression by typing the new name over the existing name.
XPath expressions are saved in named groups that can be used for managing them more effectively or controlling their scope. Expressions are persisted (in XML) between SketchPath sessions and can also be saved and loaded in different 'library' files.
Double-Click on a saved XPath expression to overwrite the current XPath expression with a saved expression, or use '$' to reference one expression from within another (the Intelli-List is populated with available variable names).
Note: You can start a new group by clicking the 'New Group' button and typing the name. The drop down list in the Variables pane allows different groups to be the 'active group'.
Check the Expression
XPath Editor in 'Trace Mode' (here the result of the 'concat' function with a predicate is being checked)
If the expression you've entered does not provide the intended result, or simply if you want to confirm perhaps how a complex nested predicate is working, you may want to check a specific part of the expression.
To isolate a specific part of an expression and evaluate that part, double-click on that part of the expression you wish to evaluate, function, node or axis. The part will be highlighted and the result for that part will be shown, this feature is known in SketchPath as the 'XPath Trace' mode. You can use the <escape> key to exit this mode.
Note: To include an adjacent predicate, just use the 'right-arrow' cursor key to expand the highlighted part.