0% found this document useful (0 votes)

402 views

Stylus Studio User Guide

XML editor manual

Uploaded by

vb_pol@yahoo

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

402 views

Stylus Studio User Guide

XML editor manual

Uploaded by

vb_pol@yahoo

Available Formats

Download as PDF, TXT or read online on Scribd

In-place Editing
Drag-and-Drop
QuickEdit
Refactoring
Description of Sample XML Schema
Defining a complexType in a Sample XML Schema in the Diagram View
Defining the Name of a Sample complexType in the Diagram View
Adding an Attribute to a Sample complexType in the Diagram View
Adding Elements to a Sample complexType in the Diagram View
Adding Optional Elements to a Sample complexType in the Diagram View
Adding an Element That Contains Subelements to a complexType in the Diagram View
Choosing the Element to Include in a Sample complexType in the Diagram View
Defining Elements of the Sample complexType in the Diagram View
Opening Files in Stylus Studio
Types of Files Recognized by Stylus Studio
Opening Unknown File Types
Opening Files Stored on Third-Party File Systems
Modifications to Open Files
Using the File Explorer
How to Use the File Explorer to Open Files
Other Features of the File Explorer
Working with the File Explorer Filter
Dragging and Dropping Files in the Stylus Studio
Other Ways to Open Files in Stylus Studio
Adding File Types to Stylus Studio
Deleting File Types
Working with Projects
Displaying the Project Window
Displaying Path Names
Other Documents
Creating Projects and Subprojects
Saving Projects
Opening Projects
Recently Opened Projects
Adding Files to Projects
Other Ways to Add Files to Projects
Copying Projects
Rearranging the Files in a Project

Stylus Studio Users Guide

Contents

Examples of Patterns and Expressions

Frequently Asked Questions About XSLT
Sources for Additional XSLT Information
Benefits of Using Stylus Studio
Structural Data View
Sophisticated Editing Environment
XSLT and Java Debugging Features
Integrated XML Parser/XSLT Processor
Tutorial: Understanding How Templates Work
Creating a New Sample Stylesheet
Understanding How the Default Templates Work
Instantiating the Template That Matches the Root Node
Instantiating the Root/Element Default Template
Instantiating the Text/Attribute Default Template
Illustration of Template Instantiations
Editing the Template That Matches the Root Node
Creating a Template That Matches the book Element
Creating a Template That Matches the author Element
Working with Stylesheets
About the XSLT Editor
Creating Stylesheets
Creating a Stylesheet from HTML
Specifying Stylesheet Parameters and Options
Applying Stylesheets
About Applying Stylesheets
Results of Applying a Stylesheet
Applying Stylesheets to Large Data Sets
Creating a Scenario
Cloning Scenarios
Saving Scenario Meta-Information
Applying a Stylesheet to Multiple Documents
Applying the Same Stylesheet in Separate Operations
Applying a Stylesheet to Multiple Documents in One Operation
About Stylesheet Contents
Contents Provided by Stylus Studio
Contents You Can Add
Updating Stylesheets
Dragging and Dropping from Schema Tree into XSLT Editor
Using Sense:X Automatic Tag Completion

Stylus Studio Users Guide

xvii

Contents

Using Sense:X to Ensure Well-Formed XML

Using Standard Editing Tools
Saving Stylesheets
Using Updated Stylesheets
Specifying Extension Functions in Stylesheets
Using an Extension Function in Stylus Studio
Basic Data Types
Declaring an XSLT Extension Function
Working with XPath Data Types
Declaring an Extension Function Namespace
Invoking Extension Functions
Finding Classes and Finding Java
Debugging Stylesheets That Contain Extension Functions
Working with Templates
Viewing Templates
Viewing a List of Templates
Viewing a Specific Template
Checking if a Template Generates Output
Using Stylus Studio Default Templates
Contents of a New Stylesheet Created by Stylus Studio
About the Root/Element Built-In Template
About the Text/Attribute Built-In Template
Creating Templates
Saving a Template
Applying Templates
Updating Templates
Deleting Templates
Using Third-Party XSLT Processors
How to Use a Third-Party Processor
Passing Parameters
Setting Default Options for Processors
Validating Result Documents
Post-processing Result Documents
Generating Formatting Objects
Developing Stylesheets That Generate FO
Troubleshooting FOP Errors
Viewing the FO Sample Application
Deploying Stylesheets That Generate FO
Example

Stylus Studio Users Guide

xxi

Contents

xsl:sequence
Format
Description
Example
xsl:sort
Format
Description
Example
xsl:strip-space
xsl:stylesheet
Format
Description
xsl:template
Format
Description
xsl:text
Format
Description
Examples
xsl:transform
xsl:value-of
Format
Description
Example
xsl:variable
Format
Description
xsl:when
xsl:with-param
Format
Description
Example

Chapter 6: Creating XSLT Using the XSLT Mapper

Overview of the XSLT Mapper
Example
Graphical Support for Common XSLT Instructions and Expressions
Setting Options for the XSLT Mapper
Simplifying the Mapper Canvas Display
xxii

Stylus Studio Users Guide

Contents

Other Mapper Display Features

Exporting Mappings
Searching Document Panes
Ensuring That Stylesheets Output Valid XML
Steps for Mapping XML to XML
Source Documents
Choosing Source Documents
Source Documents and XML Instances
Types of associations
Source document icons
How to change a source document association
How to Add a Source Document
How to Remove a Source Document
How Source Documents are Displayed
Document structure symbols
Getting source document details
Target Structures
Using an Existing Document
Building a Target Structure
Modifying the Target Structure
Adding a Node
Removing a Node
Mapping Source and Target Document Nodes
Preserving Mapper Layout
Left and Right Mouse Buttons Explained
How to Map Nodes
Removing Source-Target Maps
Working with XSLT Instructions in XSLT Mapper
What XSLT Instructions Are Represented Graphically
Instruction Block Ports
Specifying Values for Ports
Understanding Input Ports
Specifying Values for Input Ports
Red Input Ports
The Flow Port
Adding an Instruction Block to the XSLT Mapper
Notes About Creating Instruction Blocks
xsl:if and xsl:choose
Processing Source Nodes

Stylus Studio Users Guide

xxiii

Contents

XPath Function Blocks

Parts of a Function Block
Types of Function Blocks
XPath Mathematical Functions
Creating a Function Block
Deleting a Function Block
Logical Operators
Setting a Text Value
Example
How to Set a Text Value on the Mapper Canvas
How to Set a Text Value on the Target Node
Defining Java Functions in the XSLT Mapper
About Adding Java Class Files
Creating and Working with Templates
What Happens When You Create a Template
How to Create a Named or Matched Template
Creating an XSLT Scenario
Overview of Scenario Features
XML Source Documents
Global Parameters
XSLT Processors
Performance Metrics Reporting
Result Document Validation
Post-Processing Result Documents
How to Create a Scenario
How to Run a Scenario
How to Clone a Scenario

Chapter 7: Debugging Stylesheets

Steps for Debugging Stylesheets
Using Breakpoints
Inserting Breakpoints
Removing Breakpoints
Start Debugging
Viewing Processing Information
Watching Particular Variables
Evaluating XPath Expressions in the Current Processor Context
Obtaining Information About Local Variables
Determining the Current Context in the Source Document
xxiv

Stylus Studio Users Guide

Contents

Displaying a List of Process Suspension Points

Contents

Finding Strings That Contain Strings You Specify

Finding Substrings That Appear Before Strings You Specify
Finding Substrings That Appear After Strings You Specify
Finding Substrings by Position
Manipulating Strings
Concatenating Strings
Determining the Number of Characters in a String
Normalizing Strings
Replacing Characters in Strings with Characters You Specify
Converting Objects to Strings
Finding Strings That Start with a Particular String
Obtaining the Text Contained in a Node
Specifying Boolean Expressions and Functions
Using Boolean Expressions
Case Sensitivity
Examples
Calling Boolean Functions
Converting an Object to Boolean
Obtaining Boolean Values
Determining the Context Node Language
Specifying Number Operations and Functions
Performing Arithmetic Operations
Calling Number Functions
Converting an Object to a Number
Obtaining the Sum of the Values in a Node Set
Obtaining the Largest, Smallest, or Closest Number
Comparing Values
About Comparison Operators
How the XPath Processor Evaluates Comparisons
Comparing Node Sets
Two Node Sets
A Node Set and a Number
A Node Set and a String
A Node Set and a Boolean Value
Comparing Single Values With = and !=
Comparing Single Values With <=, <, >, and >=
Priority of Object Types in Comparisons
Examples of Comparisons
Operating on Boolean Values

xxxii

Stylus Studio Users Guide

Contents

Parts of a FLWOR Block

Creating a FLWOR Block
Function Blocks
Standard Function Block Types
Creating a Function Block
Parts of a Function Block
User-Defined Functions
concat Function Blocks
IF Blocks
Condition Blocks
Predicate Blocks
Enabling Predicate Blocks
Creating a Predicate Block
Example
SQL Function Blocks
User-Defined Functions
Creating a User-Defined Function
Working with User-Defined Functions
Finding Uses of a User-Defined Function
Locating a User-Defined Function Declaration
Renaming a User-Defined Function
Working with Relational Data Sources
Using the collection() Function in Stylus Studio
How the collection() Function is Processed
Database Connections
Handling Invalid Characters
Creating a Database Connection
Supported Databases
The Connection Settings Dialog Box
Using the Server URL Field
How to Create a Database Connection
How to Edit a Database Connection
Creating a collection() Statement
collection() Function Syntax
What Happens When You Create a collection() Statement?
Creating Multiple Connections
How to Create a collection() Statement
Other Ways to Register a Database Configuration
Choosing a Database Object

xxxvi

Stylus Studio Users Guide

Contents

Working with Zip Archive Format Files as Data Sources

Example
Updating Relational Databases
Overview
Using SQL Function Blocks in XQuery Mapper
About the Output Port
Creating an Insert Function Call
How to Create an Insert Function Call
Example
Creating an Update Function Call
How to Create an Update Function Call
Example
Creating a Delete Function Call
How to Create a Delete Function Call
Example
Working with XQuery Library Modules
Creating a Library Module
About Namespaces
Importing a Library Module
Using a Library Module
Removing a Library Module
Debugging XQuery
Using Breakpoints
Inserting Breakpoints
Removing Breakpoints
Start Debugging
Viewing Processing Information
Watching Particular Variables
Evaluating XPath Expressions in the Current Processor Context
Obtaining Information About Local Variables
Displaying a List of Process Suspension Points
Displaying XQuery Expressions for Particular Output
Using Bookmarks
Inserting
Removing
Moving Focus
Profiling XQuery
About Performance Metrics
Enabling the Profiler

Stylus Studio Users Guide

xxxvii

Contents

Displaying the XQuery Profiler Report

Using DataDirect XQuery Execution Plans
Query Plans in Stylus Studio
Example of a Query Plan
Parts of a Query Plan
Navigation
Query Plan Toolbar
Formatting
Saving a Query Plan as HTML
Displaying a Query Plan
Prerequisites
How to display a query plan
Optimizing Your XQuery
Creating an XQuery Scenario
Specifying XML Input
Selecting an XQuery Processor
Using Custom URI Resolvers
Implementing a Custom URI Resolver Interface
Registering a Custom URI Resolver
Registering a Default Custom URI Resolver
Setting Default Options for Processors
Setting Values for External Variables
Performance Metrics Reporting
Validating XQuery Results
How to Create a Scenario
How to Run a Scenario
How to Clone a Scenario
Generating XQuery Documentation
Documentation Defaults
Syntax and Usage
Save the XQuery
ActiveX Controls
Viewing Code Samples
How to Generate XQuery Documentation
Using XQuery to Invoke a Web Service
Choosing an XQuery Processor
Invoking a SOAP Request in an XQuery
Invoking Multiple SOAP Requests
Rules

Stylus Studio Users Guide

Contents

Output Port

Chapter 15: Publishing XML Data

The XML Publisher
Parts of the XML Publisher Editor
Building an XML Publisher Report
Process Summary
How to Create an XML Publisher Report
The XML Publisher Canvas
Choosing a Report Format
Working with Data Sources
How Data Sources are Represented in XML Publisher
Working with Namespaces
Adding a Data Source
Specifying a Default Data Source
Data Source Required for XSLT
Using XML Schema or DTD as a Data Source
Choosing a Root Element
Associating an XML Instance with the Schema
Grouping Data
What is a Relationship?
Creating a Relationship
Example Using a Relationship in a Report
Deleting a Relationship
Adding Data to a Report
How to Add Data to a Report
Example: Dropping a Repeating Node
How Data is Represented on the Canvas
Example
More About the Navigation Bar
Click the Glyph to Navigate
Working with Report Components
Types of Components
Tables
Creating a Table
Graphical Representation
Sorting
Adding Rows and Columns
Deleting Rows, Columns, and Tables
Stylus Studio Users Guide

xlvii

Contents

Lists
Creating a List
Graphical Representation
Sorting
Adding Items
Deleting an Item or a List
Text
Creating a Text Component
Graphical Representation
Images
Creating an Image
Graphical Representation
Specifying an Image Source
Specifying Image Size
Repeaters
Creating a Repeater
Graphical Representation
Sorting
Ifs
Creating an If
Graphical Representation
Example
Component Properties
Context and XPath Sub-Properties
The Properties Window
Example: Using Context and XPath Sub-Properties to Format Text
Entering XPath Expressions
Formatting Components
Formatting Numbers
Styles
Ways to Apply Styles
Formatting Influenced by Component Hierarchy
Setting Default Properties
Clearing Formats
Formatting Decimal Numbers
Where You Specify Decimal Number Formats
Where You Specify Picture Strings
Example
Generating Code for an XML Publisher Report

xlviii

Stylus Studio Users Guide

Contents

Supported Transformation Languages

Sources
Additional Sources
More About Relational Sources
How to Generate Code
Example: Building an XML Publisher Report
Getting Started
Insert and Populate a Table
Simple Table Formatting
Format Data Conditionally
Generate the Code
Properties Reference
Context and XPath Sub-Properties
Body Properties
Table Properties
Row Properties
Column Properties
Cell Properties
List Properties
Item Properties
Text Properties
Repeater Properties
If Properties
Image Properties
Dynamic Value Properties

Chapter 16: Integrating with Third-Party File Systems

Using Stylus Studio with TigerLogic XDMS
Overview
TigerLogic XDMS Version Support
Connecting to TigerLogic XDMS
What Happens When You Connect
How to Connect to TigerLogic XDMS
Reconnecting
Using Documents Stored on TigerLogic XDMS
Opening Documents
Saving Documents
Using Documents in XQuery and XSLT
Creating Collections
Stylus Studio Users Guide

xlix

Contents

Chapter 17: Extending Stylus Studio

Custom XML Validation Engines
Registering a Custom Validation Engine
Configuring a Custom Validation Engine
The Custom Validation Engines Page
How to Configure a Custom Validation Engine
Custom Document Wizards
Registering a Custom Document Wizard
Configuring a Custom Document Wizard
The Custom Document Wizards Page
Defining Arguments
How to Configure a Custom Document Wizard

Chapter 18: The Stylus Studio Java API

Chapter 19: Stylus Studio GUI Reference
About Stylus Studio XML Enterprise Suite
About Stylus Studio XML Home Edition
About Stylus Studio XML Professional Suite
Add Column
Add Element or Composite Reference
Add References to Schema
Add Segment Reference
Add Table
Assign Shortcut
Associate Schema with Variable
Associate XML Schemas to Project Folder
Associate with XML Instance
Attach to JVM
Authentication Required
Backmap Stack
Breakpoints
Build Project From SCC
C# Code Generation
Call Stack
Choose Module
Choose Provider
Choose Root Element
l

Stylus Studio Users Guide

Contents

Choose Server
Choose Source and Destination Schema
Choose the WSDL Operation
Class Properties
Code Definition
Code List Definition
Composite Definition
Configure External XQuery Processor
Connection Settings
Convert DTD to XML Schema
Convert HTML to XML
Convert HTML to XSLT
Convert XML to XML Schema
Create Java Console
Create Java Servlet
Create Relationship
Create Schema or DTD
Create User-Defined Catalog
Create XML Document from DTD
Create XML Document from XML Schema
Custom Document Wizard Arguments
Custom XML Conversion Editor
Customize Toolbars
DataDirect XQuery Options
Default Value
Description
Diagram Properties Schema Details
Diagram Properties WSDL Details
Diff Folders
Document Wizards
DTD Schema Editor Text Tab
DTD Schema Editor Tree Tab
DTD to XML Schema (Trang)
EDI Document Pane
EDI Structure Tree
EDI to XML Editor
Element Definition
Find
Find (Mapper)

Stylus Studio Users Guide

Contents

File Explorer
Generate C# .NET Code for XML Pipeline
Generate Java Code for XML Pipeline
Generate Transformation
Generate XML Schema from EDI Standards
Generate XQuery from EDI Standards
Generate XQuery/XML Schema
Go To (Custom XML Conversion)
Go To
Group Definition
Illegal Character Found
Import File
Imported Files
Imported Modules
Java Class Browser
Java Code Generation
Java Editor
Java Method Browser
Keyboard Accelerators
Lookup List
Message Definition
Name
Named Template
Named/Matched Template
New Custom XML Conversion Definition
New EDI to XML Conversion
New Function
Notes
Open and Save As
Options
Options - Application Settings
Options General Back-mapping
Options General Components XML Converters for Java
Options General Components XML Converters for .NET
Options General Components DataDirect XQuery
Options - General - Custom Document Wizards
Options - General - Custom Tools
Options - General - Custom Validation Engines
Options - General - Editor Format

lii

Stylus Studio Users Guide

Contents

Options - General - Editor General

Options - General - Editor Sense:X
Options - General - File Types
Options - General - Java Virtual Machine
Options General Spell Checking
Options - Module Settings - EDI to XML - EDI Viewer Settings
Options - Module Settings - Java - Debugger
Options - Module Settings - WSDL Editor - WSDL Details
Options - Module Settings - XML Diff - Engine
Options - Module Settings - XML Diff - Presentation
Options - Module Settings - XML Editor - XML Settings
Options - Module Settings - XML Schema Editor - Schema Details
Options - Module Settings - XML Schema Editor - Documentation
Options - Module Settings - XML Schema Editor - XML Schema to XML
Options - Module Settings - XQuery - Mapper
Options - Module Settings - XQuery - XQuery Settings
Options - Module Settings - XSLT Editor - Mapper
Options - Module Settings - XSLT Editor - XSLT Settings
Output Window
Personal Dictionary Editor
Preview Window
Processor Mismatch
Processor Settings (XQuery)
Processor Settings (XSLT)
Project Window
Project Wizards
Properties for Custom XML Conversions
Properties for EDI to XML Conversions
Properties for XML Pipelines
Properties for XML Publisher
Properties for DTD Nodes
Properties for XML Schema and WSDL Documents
Proxy Settings
Redefine Schema Symbols
Referenced Schemas
Register and Activate Stylus Studio
Rename
Rename Column
Replace

Stylus Studio Users Guide

liii

Contents

Saxon XQuery Settings

Saxon XSLT Settings
Scenario Properties Bindings Tab (Web Services)
Scenario Properties for EDI to XML Conversions
Scenario Properties Execution Framework
Scenario Properties General Tab (XSLT)
Scenario Properties Parameter Values Tab (XSLT)
Scenario Properties Post-process Tab (XQuery)
Scenario Properties Post-process Tab (XSLT)
Scenario Properties Profiling Options Tab (XSLT)
Scenario Properties Processor Tab (XQuery)
Scenario Properties Processor Tab (XSLT)
Scenario Properties General Tab (XQuery)
Scenario Properties Parameter Values Tab (XQuery)
Scenario Properties Profiling Options Tab (XQuery)
Scenario Properties Validation Tab (XQuery)
Scenario Properties Validation Tab (XSLT)
Segment Definition
Select Multiple URLs
Select Source/Target Folder
Select XML Converter
Select XML Converter Properties
Set Classpath
Set Node and Match Pattern
Shortcut Keys
Source Code Control Properties
Spelling
Start New Region
Stylus Studio
Stylus Studio Update
Text Catalog to XML Catalog
Toolbox Pane
TigerLogic XDMS Server Login
Type Derivation
UDDI Registry Browser
Value
Variables
View Sample XML
Watch

liv

All rights reserved. Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"), to deal in the
Software without restriction, including without limitation the rights to use, copy, modify,
merge, publish, distribute, and/or sell copies of the Software, and to permit persons to
whom the Software is furnished to do so, provided that the above copyright notice(s) and
this permission notice appear in all copies of the Software and that both the above
copyright notice(s) and this permission notice appear in supporting documentation.
Software developed by the OpenSSL Project for use in the OpenSSL Toolkit
(http:/www.openssl.org/). Copyright 1998-2006 The OpenSSL Project. All rights
reserved. And Copyright 1995-1998 Eric Young ([email protected]). All rights
reserved.
DataDirect SequeLink includes:
Portions created by Eric Young are Copyright 1995-1998 Eric Young
([email protected]). All Rights Reserved.
OpenLDAP, Copyright 1999-2003 The OpenLDAP Foundation, Redwood City,
California, US. All rights reserved.
No part of this publication, with the exception of the software product user documentation
contained in electronic format, may be copied, photocopied, reproduced, transmitted,
transcribed, or reduced to any electronic medium or machine-readable form without prior
written consent of DataDirect Technologies.
Licensees may duplicate the software product user documentation contained on a CDROM or DVD, but only to the extent necessary to support the users authorized access to
the software under the license agreement. Any reproduction of the documentation,
regardless of whether the documentation is reproduced in whole or in part, must be
accompanied by this copyright statement in its entirety, without modification.

lviii

Stylus Studio X14 User Guide

How to Use This Help System

The HTML Help Viewer contains three areas.

Figure 1. HTML Help Viewer

Tool bar
The Tool bar provides the following buttons:

Hide/Show Opens or closes the Navigation pane.

Locate Opens the Contents tab, and highlights the current topic to indicate where
it is located.

Back Takes you to the previously viewed topic.

Forward Returns you to the topic you were viewing before you clicked Back.

Print If you are in the Contents tab, provides options to print the selected topic or
the selected heading and all its subtopics. If you are in the Index or Search tab, it
opens the Print dialog box to print the current topic.

Stylus Studio X14 User Guide

lix

Options Opens a menu that contains all of the commands found on the Toolbar,

providing accessibility shortcut keys for each. The following commands are also
provided:

Home Jumps you to the Help systems home page.

Stop Stops downloading file information. Use this feature when the Help
system contains a link to the Web; you can choose this option to stop a Web page
from downloading.

Refresh Updates the current topic in the Topic pane. Use this feature when the
Help system contains a link to the Web.

Internet Options Opens the Microsoft Internet Explorer Internet Options

dialog box.

Search Highlight Off/On Turns highlighting of search terms off or on.

Navigation pane
The Navigation pane displays four tabs:

Contents Click the plus (+) or minus (-) sign to the left of the topic titles to expand
or contract the table of contents.

Index Type the word or phrase you want to find into the box at the top, or use the
scroll bar to the right to scroll up and down.

Search Use advanced full-text search to search the Help system using Boolean,
wildcard, and nested expressions. See Search Tips on page lxiii for more
information.

Favorites Create a list of your favorite Help topics. To add a topic to the Favorites
tab, navigate to the topic you want and click Add.

Topic pane
The Topic pane displays the Help topics.
Click the Previous
and Next
icons, which are located at the top and bottom of
this pane, to navigate to the topics that immediately precede and follow the topic that you
are viewing.

Search Tips
Advanced full-text search allows you to search the entire Help system.
lx

Stylus Studio X14 User Guide

Search Tips

This section covers

AND, OR, NEAR, and NOT (Boolean) Operators on page lxiv

Search Tab Options on page lxv

Other Helpful Tips on page lxvi

See also How to Use This Help System on page lxii.
For more information, see Using HTML Help Search at
www.helpware.net/htmlhelp/hhfindingtext.htm.

AND, OR, NEAR, and NOT (Boolean) Operators

Click the right-arrow button
to your search.

to add the Boolean operators AND, OR, NEAR, and NOT

Table 1. AND, OR, NEAR, and NOT Operators

Operator

Searches For

Example

Returns

AND

Both words in the same

topic, anywhere in the
topic

rain AND snow

All topics containing

both the word rain and
the word snow
anywhere in the topic

Either word in a topic

cat OR feline

All topics containing the

word cat or the word
feline as well as topics
containing both words

NEAR

Both words in the same

topic, close together

hike NEAR camp

All topics containing

both the word hike and
the word camp but only
when they appear close
together in the topic

NOT

The first word without

the second word

orange NOT juice

All topics containing the

word orange but not the
word juice

AND narrows a search by returning only topics containing all of the words you search
for. The more words you join together with AND, the fewer topics the search returns.

Stylus Studio X14 User Guide

lxi

OR expands a search by returning topics containing either word by itself or both

words together. Use OR to search for words that are similar in meaning; the more
words you join together with OR, the more topics the search returns.
NEAR searches for words that appear close together, in any order, in a topic. Using
NEAR instead of AND can return a more relevant list of topics.
NOT limits your search by returning only topics containing the first word but not the
second word, even if the first word also appears in the topic.

Nested Expressions
Use parentheses to group words together when you are using more than one Boolean
operator and three or more words. Expressions that are placed between parentheses are
evaluated before the rest of the search statement. This allows you to combine several
search statements into one, therefore creating more complex searches. For example, water
AND (polo OR aerobics) searches for topics containing information about both water polo
and water aerobics.
Note If a search contains multiple Boolean operators, but does not contain a nested expression,

it is evaluated from left to right. For example, water AND polo OR aerobics (without
parentheses) is the same as (water AND polo) OR aerobics, and finds topics containing
information about water polo or aerobics, but not water aerobics.

Search Tab Options

Use the three options at the bottom of the Search tab, in any combination, to limit your
search to previous results, match similar words, or search only topic titles. To find an exact
word in all topics of the Help system, leave all three options unchecked.
Note Whichever options you checked and unchecked for the previous search will still be

checked and unchecked when you select the Search tab for a new search.

Search previous results

Choose this option to search only the results of a previous search. This lets you narrow
a search that resulted in too many topics the first time. If you want to search all topics
of the Help system, you must make sure this option is unchecked.

Match similar words

Choose this option to find any close match to the word you are searching for. This lets
you match similar spellings and minor grammatical variations. For example, if you
search for jump, choosing this option will find jump, jumps, and jumped.

lxii

Stylus Studio X14 User Guide

Search Tips

Search titles only

Choose this option to search among topic titles only, rather than for every instance of
the word. This narrows your search to topics that might be the most pertinent.

Other Helpful Tips

The following tips allow you to enhance the search capabilities of the Help system:

Wildcards
Use the asterisk (*) in a search to represent one or more letters. For example, searching
for h*t returns a list of topics that contain pat, pet, pit, pot, and put, while searching for
dat* returns a list of topics containing date, data, dateline, and database.

Case Sensitivity
Searches are case insensitive. You can type the word you want to search for in uppercase
or lowercase letters, or in a combination of the two, without affecting the results.

Sorting Topics
One search returns up to 500 topics. You can sort the list of topics in ascending order,
alphabetically by title or numerically by rank. To sort the list, click the Title or Rank
column heading.
Note Since the Location column contains no distinguishing information, you can omit it from

your view by dragging the Rank column over it.

Searching for a Phrase

Use double or single quotation marks ( or ) to search for a specific phrase. For example,
searching for lunch room (without quotation marks) finds all topics that contain both the
word lunch and the word room anywhere in the topic. However, searching for lunch
room (with quotation marks) finds only those topics that contain the exact phrase lunch
room, with the words in precisely the order specified, and no other words between.

Java and COM

When searching for a fully qualified Java or COM name (such as com.exln.dxe.Session
or IXlnSession::GetFileData()), you must put the entire name that you want to search

Stylus Studio X14 User Guide

lxiii

for in quotation marks. Otherwise, the periods and colons are treated by the search as OR
operators.

Conventions in This Document

This section describes the typographical and formatting conventions used in this
document for text, notes, warnings, and important messages. It covers

Typographical Conventions on page lxvii

Syntax Notation on page lxviii

Information Alerts on page lxviii

Edition Alerts on page lxviii

Typographical Conventions
This document uses the following typographical conventions:

Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and
the names of windows, menu commands, buttons, and other user-interface elements.
For example, From the File menu, select Open.

Italic typeface in this font emphasizes new terms when they are introduced.

Courier typeface is used for code samples.

Monospace typeface indicates text that might appear on a computer screen other than
the names of user-interface elements, including all of the following:

Values that the user must enter

System output (such as responses, error messages, and so on)

Filenames and pathnames

Software component names, such as class and method names

Essentially, monospace typeface indicates anything that the computer is saying, or
that must be entered into the computer in a language that the computer understands.
Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface.
Monospace typeface in italics or Bold monospace typeface in italics (depending
on context) indicates variables or placeholders for values you supply or that might
vary from one case to another.

lxiv

Stylus Studio X14 User Guide

Conventions in This Document

Syntax Notation
This document uses the following syntax notation conventions:

Brackets ([ ]) in syntax statements indicate parameters that are optional.

Braces ({ }) indicate that one (and only one) of the enclosed items is required. A
vertical bar (|) separates the alternative selections.

Ellipses (...) indicate that you can choose one or more of the preceding items.

Information Alerts
This document highlights special kinds of information by shading the information area,
and indicating the type of alert in the left margin.
Tip A Tip flag indicates helpful usage information about Stylus Studio.
Note A Note flag indicates information that complements the main text flow. Such information

is especially needed to understand the concept or procedure being discussed.

Important An Important flag indicates information that must be acted upon within the given context

in order for the procedure or task (or other) to be successfully completed.

Warning A Warning flag indicates information that can cause loss of data or other damage if

ignored.

Edition Alerts
Some features are supported only in certain Stylus Studio XML editions. Documentation
that describes these features is identified with an alert like the following:
:

XML Pipeline support is available only in Stylus Studio XML Enterprise Suite
.
A summary of features by edition can be found in Stylus Studio Editions on page 3.

Stylus Studio X14 User Guide

lxv

Video Alerts
Stylus Studio provides many video demonstrations of its features. Documentation that
describes a feature for which a video demonstration exists is preceded by an alert like the
following:
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XQuery
Mapper video.
You can learn more about other video demonstrations here:
http://www.stylusstudio.com/xml_videos.html (or select Products > XML Video
Demonstrations from the Stylus Studio Web site menu.

Technical Support
Submit questions and report problems using the Stylus Studio Developer Network
(SSDN). SSDN has numerous active forums, including specialized forums for

XQuery

XSLT

Code samples and utilities

General technical questions

Feature requests
SSDN is fully searchable, and contains current as well as historical information about
Stylus Studio and XML technologies. If you cannot find the answer to the question you
have, submit it to the forum and a Stylus Studio technician will respond to you.
When submitting a question or reporting an issue, it often helps to state the version of
Stylus Studio you are running (click Help > About Stylus Studio on the menu bar) as well
as any other information about your environment you think might be relevant (such as the
JVM version you are using, for example).

lxvi

Stylus Studio X14 User Guide

Chapter 1

Getting Started with Stylus Studio

Stylus Studio is an integrated development environment (IDE) for XML and related
technologies. Stylus Studio allows you to design, develop, and test XML applications
using its intuitive graphical interface, textual editors, and debuggers for XML, XML
Schema, DTD, XQuery, XSLT, Web services, and Java.

Figure 1. Stylus Studios XML Pipeline Editor

Stylus Studio User Guide

Getting Started with Stylus Studio

Stylus Studio includes modules for:

XML

XQuery

XSLT

XML Pipelines

XML reporting

Relational data sources

DTD

XML Schema

Web services

Java

Converting non-XML files to XML, and vice versa

Each module has one or more editors to help you author, edit, and debug XML
applications.
This chapter provides a tour of the basic operations Stylus Studio provides with each of
its modules. It also includes information about opening files in any module, using projects
to organize files, and setting options that affect all modules.
This chapter is organized as follows:

Stylus Studio Editions on page 3

Integrated Components on page 4

Starting Stylus Studio on page 8

Updating an XML Document Getting Started on page 10

Working with Stylesheets Getting Started on page 33

Using the XSLT Mapper Getting Started on page 44

Debugging Stylesheets Getting Started on page 52

Defining a DTD Getting Started on page 61

Defining an XML Schema Using the Diagram Tab Getting Started on page 66

Opening Files in Stylus Studio on page 92

Working with Projects on page 100

Customizing Tool Bars on page 118

Specifying Stylus Studio Options on page 120

Defining Keyboard Shortcuts on page 125

Stylus Studio User Guide

Stylus Studio Editions

Using Stylus Studio from the Command Line on page 128

Managing Stylus Studio Performance on page 130
Configuring Java Components on page 133

Stylus Studio Editions

Stylus Studio is offered in several editions to provide a tool that is appropriate for every
level of user, from integration architects and application developers providing enterpriseclass solutions, to students and non-professional users just starting out with XML and
related technologies.

Stylus Studio XML Enterprise Suite

Stylus Studio XML Enterprise Suite is Stylus Studios most comprehensive XML IDE,
offering a complete and robust set of tools for writing, testing, debugging, and deploying
XML applications. In addition to editors for XML, XML Schema, XQuery, and XSLT,
Stylus Studio XML Enterprise Suite provides the following features exclusive to this
edition of Stylus Studio:

Java and C# for .NET code generation for deployment of XQuery and XSLT
transformations

The ability to expose XML Schema to Java bindings

XQuery and XSLT Profilers to help you gather performance metrics and troubleshoot
performance bottlenecks

Custom XML Conversions, a module that allows you to easily convert non-XML files
like EDI and CSV to XML

Web Service Call Composer to help you build and test calls to hundreds of industrystandard Web services

Integration with Raining Data Tiger Logic XDMS

Support for OASIS catalogs, including dozens of catalogs bundled with Stylus Studio

Stylus Studio XML Professional Suite

Stylus Studio XML Professional Suite provides a complete set of tools for the XML
application developer, including XML Differencing for comparing multiple XML
documents and folders.
XML Differencing is also included in Stylus Studio XML Enterprise Suite.
Stylus Studio User Guide

Getting Started with Stylus Studio

Stylus Studio Home Edition

Stylus Studio Home Edition is a value-priced XML IDE that provides an excellent way to
learn about and work with XML and its related technologies. Stylus Studio Home Edition
offers many of the features of Stylus Studio XML Professional Suite, allowing you to do
real work with XML, XML Schema, XSLT, DTD, and other important XML
technologies.

Edition Alerts
The Stylus Studio User Guide describes features found in all Stylus Studio editions.
Alerts, like the one shown here, are used to identify documentation describing features
found only in particular Stylus Studio editions.
The XML Editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.

More Information
For a complete description of Stylus Studio XML Enterprise Suite, Stylus Studio XML
Professional Suite, and Stylus Studio Home Edition, see the Stylus Studio Web site:
http://www.StylusStudio.com/xml_feature_comparison.html

Integrated Components
Stylus Studio XML Enterprise Suite is fully integrated with these DataDirect products:

DataDirect XML Converters for Java

DataDirect XML Converters for .NET

DataDirect XQuery
The XML Converters are high-performance Java and .NET components that provide
bi-directional, programmatic access to virtually any non-XML file including EDI, flat
files, and other legacy formats. DataDirect XML Converters allow developers to
seamlessly stream any non-XML data as XML to industry-leading XML processing
components or to any application. They support StAX, SAX, XmlReader, XmlWriter,
DOM and I/O streaming interfaces, and can be embedded directly for transformation
purposes, or as part of a chain of programs including XSLT and XQuery, or even inside
XML pipelines. DataDirect XML Converters maximize developer productivity and

Stylus Studio User Guide

Integrated Components

provide a fast, scalable solution for converting between EDI and other legacy formats and
XML.
DataDirect XQuery is an XQuery processor that enables developers to access and query
XML, relational data, SOAP messages, EDI, legacy, or a combination of data sources,
and, in addition, provides full update support for relational data. DataDirect XQuery
supports the XQuery for Java (XQJ) API, and is easily embedded into any Java program
it does not require any other product or application server, and has no server of its own.
Evaluation copies of these DataDirect products are installed in the \Components directory
where you installed Stylus Studio. These copies provide full development libraries,
sample code, and user documentation.

How Stylus Studio Uses Integrated Components

Stylus Studio uses the DataDirect XQuery and XML Converters engines to process
XQuery and XML conversions. These processing engines run under the covers
throughout Stylus Studio in the XQuery module, EDI to XML Conversions module,
XML Pipelines module, and the Custom XML Conversions module, to name a few.
You can also use the APIs for these components to build and test applications that run
outside Stylus Studio. You might, for example, want to build an XQuery application using
Java or C# code for .NET generated by Stylus Studio for the XQuery you develop using
the Stylus Studio XQuery module.

Managing Component Licenses

Each DataDirect component is installed with an evaluation license that allows you to
develop and test XQuery and XML conversion applications. Applications that you deploy
outside Stylus Studio might require a license for DataDirect XML Converters,
DataDirector XQuery, or both, regardless of whether the application is built using a
DataDirect API or simply takes advantage of the XQuery or XML Converters processing
engines.

The Stylus Studio License Manager

The Stylus Studio License Manager allows you to perform the following tasks for
DataDirect XQuery and XML Converters components. You can

Extend the evaluation period

Add and remove license keys

Stylus Studio User Guide

Getting Started with Stylus Studio

The License Manager is on the Components page of the Options dialog box (click Tools
> Options on the Stylus Studio menu). As seen in the following illustration, licenses for
each component are managed separately:

Figure 2. Stylus Studio License Manager

The component name Folder field displays the location of the DataDirect component
installation whose license you wish to manage. You can use the License Manager to
manage license keys for

The copies of the DataDirect components that are installed with Stylus Studio. This
is the default.

Standalone installations of the DataDirect components. If you acquired a separate

copy of a DataDirect component, you can specify its URI in the component name
Folder field.

How to Extend an Evaluation

To extend an evaluation:

Select the component whose evaluation you wish to extend from the Components
tree in the Options dialog box.

If necessary, change the URI in the component name Folder field to point to the folder
where the component whose license you wish to manage is installed.

Stylus Studio User Guide

Integrated Components
3.

Click the Extend Evaluation button.

An entry field appears in the License Manager list box.

Replace the instructional text with the IPE key.

Press Enter or click the OK button.

The license is added to your XML Converters installation.

Click OK to close the Options dialog box.

How to Add a License

To add a license:
1.

Select the component for which you wish to add a license from the Components tree
in the Options dialog box.

If necessary, change the URI in the component name Folder field to point to the folder
where the component whose license you wish to add is installed.

Click the Add button.

An entry field appears in the License Manager list box.

Replace the instructional text with the IPE key.

Press Enter or click the OK button.

The license for your XML Converters installation is added to the license manager.

Click OK to close the Options dialog box.

How to Remove a License

To remove a license:
1.

Select the component whose license you wish to remove from the Components tree
in the Options dialog box.

If necessary, change the URI in the component name Folder field to point to the folder
where the component whose license you wish to remove is installed.

Select the license you want to remove from the License Manager list box.

Click the Remove button.

Stylus Studio User Guide

Getting Started with Stylus Studio

Press Enter or click the OK button.

The license is removed from the license manager.

Click OK to close the Options dialog box.

Starting Stylus Studio

Throughout this chapter, you perform exercises that require you to first start Stylus
Studio. For example, if you installed Stylus Studio XML Enterprise Suite, you would
Select Start > Programs > Stylus Studio XML Enterprise Suite > Stylus Studio.

The path shown here assumes that you accepted the defaults when you installed Stylus
Studio. If you did not, you must alter your selection path accordingly.
You can also start Stylus Studio by double-clicking the desktop icon, which is added to
your desktop by default when you install Stylus Studio:

Figure 3. Example of a Stylus Studio Desktop Icon

Stylus Studio User Guide

Starting Stylus Studio

On startup, Stylus Studio displays the Tip of the Day dialog box.

Figure 4. Stylus Studio on Startup (XML Enterprise Suite Shown)

Getting Updates
By default, Stylus Studio checks the Stylus Studio Web site for newer versions each time
you start the application. You can review and modify this and other application settings
by selecting Tools > Options from the menu bar and selecting the Application Settings
page.
If you want, you can perform this check manually by selecting Help > Check for latest
version from the Stylus Studio menu.

Getting Help
As you use Stylus Studio, you can press F1 at any time to obtain context-sensitive help.
If you want, you can open the online help manually (and independent of the Stylus Studio

Stylus Studio User Guide

Getting Started with Stylus Studio

application) by selecting Start > Programs > Stylus Studio XML Edition Name> Stylus
Studio Documentation.
Note The online documentation is not installed with Stylus Studio. The first time you access

the online documentation, you are prompted to download it from the Stylus Studio web
site. By default, the online documentation is installed in the \doc directory where you
installed Stylus Studio.

Updating an XML Document Getting Started

Each of the following topics contains instructions for editing a sample XML document.
You should perform the steps in each topic before you move on to the next topic. After the
first topic, some steps depend on actions you performed in a previous topic. This
introduction to updating XML documents in Stylus Studio is organized as follows:

Opening a Sample XML Document on page 10

Updating the Text of a Sample Document on page 12

Updating the Schema of a Sample Document on page 20

Updating the Tree Representation of a Sample Document on page 26

Updating a Sample Document Using the Grid Tab on page 30

Opening a Sample XML Document

To open the your-quotes.xml sample XML document in Stylus Studio:
1.

In the File Explorer window, navigate to the examples\quotes directory in your Stylus
Studio installation directory.

Tip The \examples directory is a sibling of \bin.

Double-click your-quotes.xml.

Stylus Studio User Guide

Updating an XML Document Getting Started

Stylus Studio displays the your-quotes.xml document in the XML editor. The initial
view of the document is the Text view, as you can see by the tab at the bottom of the
window.

Figure 5. Editors Use Color-Keyed Text

Tip Stylus Studio uses different colors to distinguish markup, tag names, and data in all of its

text editors. Orange, for example, identifies elements that are not associated with a
schema. You can change the colors for editors individually. Select Tools > Options from
the menu bar, then select Editor Format. You select the editor whose settings you want to
modify using the Editor drop-down list.

Alternatives
The File Explorer window is the primary way to open and access files in Stylus Studio,
but you can also open files using:

The Open dialog box, which is displayed when you select File > Open from the menu
bar or click the Open
button on the tool bar, for example.

The Project window, which is displayed on the left of the Stylus Studio desktop. The
Project window shows only those files associated with Stylus Studio projects.
Stylus Studio User Guide

Getting Started with Stylus Studio

For more information

See Opening Files in Stylus Studio on page 92 to learn more about the File Explorer
window.
See Working with Projects on page 100 to learn more about projects in Stylus Studio.

Updating the Text of a Sample Document

When you update an XML document in the Text view of the XML editor, you can use the
usual editing tools, as well as tools tailored for handling XML.
Each of the following topics contains instructions for editing a sample XML document.
You should perform the steps in each topic before you move on to the next topic. After the
first topic, some steps depend on actions you performed in a previous topic.
For more information on editing tools and features, see Using the Text Editor on
page 143.
This section provides instructions for

Displaying Line Numbers on page 12

Adding Elements in the Text View of a Sample Document on page 13

Copying and Pasting in the Text View of a Sample Document on page 14

Undoing Operations in the Text View of a Sample Document on page 14

Inserting Indents in the Text View of a Sample Document on page 16

Querying in the Text View of a Sample Document on page 17

Deleting and Saving Queries on page 19

Displaying Line Numbers

Stylus Studio lets you optionally display line numbers in most of its editors. Line numbers
provide simple, unobtrusive points of reference that can make working large or complex
documents easier. Line numbers are off by default; turn them on now.
To display line numbers:
1.

Select Tools > Options from the Stylus Studio menu.

Stylus Studio displays the Options dialog box.

Stylus Studio User Guide

Updating an XML Document Getting Started

Click Application Settings > Editor General.

Figure 6. Sense:X and Other Editor Features are in the Options Dialog Box
3.

Select XML Editor from the Editor drop-down list.

Click Show line numbers.

Click OK.

Adding Elements in the Text View of a Sample Document

To add elements in the Text view of your-quotes.xml:
1.

In the XML editor window, click in the first line just after <ticker>.

Press Enter and type <quote><company>data</.

Sense:X Auto-Completion
As soon as you type the closing forward slash, Stylus Studio displays company> because
it is the only element that is appropriate to close. Automatic closing of open tags is part
of Stylus Studios Sense:X intelligent editing. You can change this and other Sense:X
options on the Editor General page of the Options dialog box for example, you can have
Stylus Studio display a list of appropriate elements, even if that list includes one only
item.

Stylus Studio User Guide

Getting Started with Stylus Studio

Stylus Studios Sense:X provides even greater functionality if the document you are
editing has either a DTD or XML Schema associated with it. See Sense:X Speeds
Editing on page 145 for more information.

Copying and Pasting in the Text View of a Sample Document

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Adding Elements in the Text
View of a Sample Document on page 13.
To copy and paste elements in the Text view of your-quotes.xml:
1.

Use the mouse to select the text for one quote element and its contents.

In the menu bar, select Edit > Copy.

Alternatives: Press Ctrl+C or click Copy.

Scroll down in the XML editor and click just before </ticker>.

In the menu bar, select Edit > Paste.

Stylus Studio copies the quote element here, but the indentations are not quite right.
Instructions for fixing this are in the topic Inserting Indents in the Text View of a
Sample Document on page 16.
Alternatives: Press Ctrl+V or click Paste.
.

Undoing Operations in the Text View of a Sample Document

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Adding Elements in the Text
View of a Sample Document on page 13.
To undo operations performed on the your-quotes.xml document:

In the menu bar, select Edit > Undo to remove the text you just pasted.
Alternative: Press Ctrl+Z.

In the menu bar, select Edit > Redo to replace the text you just removed.
Alternative: Press Ctrl+Y.

In the XML editor window, click Indent XML Tags

, which is the left most button.

Stylus Studio User Guide

Updating an XML Document Getting Started

Stylus Studio displays a message that alerts you that there is an open tag for a quote
element but no close tag. The messages indicates the line and column in which the
error was found.
4.

In the alert box, click OK. Because the document is not well-formed XML, Stylus
Studio does not insert indents in the document. The next topic, Inserting Indents in
the Text View of a Sample Document on page 16, shows how to fix the document so
that it is well-formed.

Stylus Studio User Guide

Getting Started with Stylus Studio

In the menu bar, click Edit.

The Undo and Redo operations are no longer active. After you click the Indent XML
Tags button, you cannot automatically undo or redo recent changes. It does not matter
whether or not Stylus Studio actually inserts the indents. After you make another
change, the Undo operation becomes active again.

Inserting Indents in the Text View of a Sample Document

In the XML editor tool bar, click Indent XML Tags

again.
Stylus Studio displays the message that indicates that a close tag is missing. It
specifies the element name, and the line and column numbers that identify where the
error was found.

In the alert box, click OK.

Stylus Studio moves the cursor so that it appears immediately after the quote tag that
has no closing tag.
The current cursor location within the document is displayed as line/column
coordinates in the Stylus Studio status bar at the bottom of the Stylus Studio window.

Tip

Updating an XML Document Getting Started

Click the symbol element.

In the Text view, Stylus Studio uses its back-mapping feature to move the cursor to
the source element for the symbol result element you clicked.

Figure 9. Backmapping from XPath Query Result to XML Document

In the Text view, click the down arrow to the right of the query field.

In the XPath Query Editor window, click the New Query button (
Stylus Studio adds a new tab for each query you define.

Type //company and click the Execute Query button ( ).

Stylus Studio runs the new query and displays the results.

Close the XPath Query Editor window by clicking the x in that windows upper right
corner.

Deleting and Saving Queries

You cannot explicitly delete a query. In addition, queries you define are not saved with an
XML document unless that document belongs to a Stylus Studio project if you close the
XML document and then reopen it, the queries you defined in the previous editing session
are no longer there.

Stylus Studio User Guide

Getting Started with Stylus Studio

For more information

See Using the XPath Query Editor on page 694 to learn more about the XPath Query
Editor.
See Working with Projects on page 100 to learn more about projects and their role in
Stylus Studio.

Updating the Schema of a Sample Document

This section provides instructions for updating the internal DTD for your-quotes.xml.
When an XML document has an external DTD, you can view the external DTD in the
Schema tab of the XML Editor, but you cannot edit it. To be able to edit an external DTD,

you must open it in the DTD editor. When an XML document has an internal DTD, you
can view and edit it in both the Schema tab and the Text tab of the XML editor.
You should have already performed the steps in Updating the Text of a Sample
Document on page 12. Each of the following topics contains instructions for editing the
sample XML document. You should perform the steps in each topic before you move on
to the next topic. After the first topic, some steps depend on actions you performed in a
previous topic.
This section includes the following topics:

Creating a Sample Schema on page 20

Defining a Sample Element on page 22

Adding an Element Reference to a Sample Schema on page 24

Defining an Entity in a Sample Schema on page 25

Exploring Other Features in a Sample Schema on page 25

For more information, see Defining a DTD Getting Started on page 61.

Creating a Sample Schema

To create the schema of a sample XML document:

If it is not already open, open your-quotes.xml. See Opening a Sample XML

Document on page 10 if you need help with this step.

At the bottom of the XML editor window, click the Schema tab.

In the left tool bar, Stylus Studio activates only those buttons that are applicable to the
DTD you can add elements, entities, comments, and so on. But you cannot add an
attribute definition, a reference to an element, or a #PCDATA node, for example.

In the left tool bar, click New Element Definition

field at the bottom of the tree.

. Stylus Studio displays an entry

Figure 14. Entry Field for a New DTD Element

Type location and press Enter. Stylus Studio displays the properties for the new
location element in the Properties window.

Stylus Studio User Guide

Getting Started with Stylus Studio

In the left tool bar, click New Modifier . Stylus Studio displays a drop-down menu
of options that specify the rules for the occurrence of the children of the new element.

Figure 15. Drop-Down List for Modifier Values

Double-click Zero or More (or click once to select it and press Enter).

In the left tool bar, click Add #PCDATA

. Your definition of the location element
specifies that it can contain only raw data.

Adding an Element Reference to a Sample Schema

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Creating a Sample Schema on
page 20.
To update the definition of the quote element to include an optional location
element:

In the Schema tab, expand the quote element.

Click its Sequence modifier.

In the left tool bar, click New Modifier

.
Stylus Studio displays an entry field for the new modifier at the end of the list of
modifiers that already apply to the Sequence modifier. The entry field consists of a
drop-down list of available values for the new modifier.

In the drop-down list, double-click Optional.

In the left tool bar, click New Reference to Element

entry field after the new Optional modifier.

Type location and press Enter.

To move the location element to be earlier in the sequence, click its Optional
modifier.

. Stylus Studio displays an

Stylus Studio User Guide

Updating an XML Document Getting Started

In the XML editor top tool bar, click Move Up

element is where you want it to be.

repeatedly until the location

Defining an Entity in a Sample Schema

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Creating a Sample Schema on
page 20.
To define an entity in the internal DTD for your-quotes.xml:
1.

Click the DTD node.

In the left tool bar, click New Entity

.
At the end of the schema, Stylus Studio displays Ent and a entry field for the name of
the new entity.

Type TCBCC for the name of the entity and press Enter.
In the Properties window, Stylus Studio displays the properties for the new entity.

In the Properties window, double-click the Value field.

Type The

Countrys Best Computer Company and

press Enter.

Exploring Other Features in a Sample Schema

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Creating a Sample Schema on
page 20.
To toggle white space or validate your document:
1.

Click Toggle Display of White Space

to display nodes that represent white space
in the DTD. Click the button again to hide the white space nodes.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click Validate Document

.
Stylus Studio displays a message in the Output window that indicates that the
document is valid.

Figure 16. Output Window After Schema Validation

Updating the Tree Representation of a Sample Document

This section provides instructions for updating the DOM tree representation of the yourquotes.xml document.
You should have already performed the steps in Updating the Schema of a Sample
Document on page 20. Each of the following topics contains instructions for editing the
sample XML document. You should perform the steps in each topic before you move on
to the next topic. After the first topic, some steps depend on actions you performed in a
previous topic.
This section includes the following topics:

Adding an Element to a Sample Document Tree on page 27

Changing an Elements Data in a Sample Document Tree on page 27

Adding Attributes and Other Node Types to a Sample Document Tree on page 28

Adding an Entity Reference to a Sample Document Tree on page 29

Stylus Studio User Guide

Updating an XML Document Getting Started

Adding an Element to a Sample Document Tree

To add an element to the tree representation of your-quotes.xml:
1.

If it is not already open, open your-quotes.xml.

See Opening a Sample XML Document on page 10 if you need help with this step.

At the bottom of the XML Editor window, click the Tree tab.
Stylus Studio closes the Properties window.
You can close the Output window if it is still open from the previous exercise.

Tip
3.

Click the plus sign next to the ticker element to expose the children of the ticker
element.

Click New Element

in the left tool bar to add a quote element to the document.
Stylus Studio displays a drop-down menu that lists the elements you can add at that
position in the tree.

Click quote and press Enter.

Stylus Studio displays a field next to the new quote element. The DTD allows a quote
element to contain data.

Click outside the field to close it without entering data.

Changing an Elements Data in a Sample Document Tree

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Adding an Element to a Sample
Document Tree on page 27.
In the Tree tab of your-quotes.xml, to change the data that an element contains:
1.

Expand the third quote element.

Click the symbol element.

In the XML Editor top tool bar, click Change Value

.
Stylus Studio activates the field to the right of the symbol element and selects the
current value.

In the active field, type XSOL and press Enter.

To the right of the exchange element, right-click Nasdaq NMS.

Stylus Studio displays a shortcut menu.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click Change Value. Stylus Studio activates the value field for the exchange element.

In the active field, type NYSE and press Enter.

Adding Attributes and Other Node Types to a Sample Document Tree

This topic is part of a sequence. If your-quotes.xml is not open, see Opening a Sample
XML Document on page 10. The sequence starts with Adding an Element to a Sample
Document Tree on page 27.
To add attributes and other types of nodes to your-quotes.xml:
1.

Click the last quote element in the tree.

Click New Attribute

.
Stylus Studio displays an attribute name field immediately below the selected quote
element.

Figure 17. Adding a New Element to a Document Tree

In the attribute name field, type agent and press Enter.

Stylus Studio displays a default value for the attribute, Text, in an entry field to the
right of the new attribute.

In the attribute value field, type Star Brokers and press Enter.
Stylus Studio displays an entry field for a new attribute name, allowing you to easily
add a number of attributes, one after the other.

Click outside the attribute name field to close it.

In the XML editor top tool bar, click Validate Document

.
Stylus Studio displays a message in the Output window that indicates that the
document is not valid. The DTD does not specify the agent attribute for the quote
element. Stylus Studio allows you to modify your document in invalid ways, which
you might want to do during application design. The validation feature informs you
that your document is invalid when you try to validate the document.
Stylus Studio User Guide

Updating an XML Document Getting Started

Click the agent attribute.

In the XML Editor top tool bar, click Delete Node

Click Validate Document

again.
Stylus Studio displays a message in the Output window that indicates that the
document is now valid.

Adding an Entity Reference to a Sample Document Tree

If it is not already selected, click the quote element you defined in the previous topic.

In the left tool bar, click New Element

to add subelements to the new quote
element.
Stylus Studio displays a drop-down menu that lists a number of elements that you can
insert at this point. Scroll the list to view them all.

Click company, which is first in the list, and press Enter.

Stylus Studio displays a field next to the element name. You can enter data here, such
as the name of the company. But rather than entering data, suppose you want to refer
to an entity. To refer to an entity:

Click outside the field or press the Esc key.

Click New Entity Reference

, which is the last button in the left tool bar.
Stylus Studio displays a drop-down menu that lists the defined entities.
If the New Entity Reference button is not active, click Toggle Display of Entity
References
in the XML editor top tool bar. This button allows you to control
whether you can refer to entities.

Double-click TCBCC.
Stylus Studio inserts the text The
the company element.

Countrys Best Computer Company as

the value for

Click the Text tab at the bottom of the XML editor window.
Stylus Studio displays the &TBCC; entity reference in the new company element.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click the Tree tab.

Updating a Sample Document Using the Grid Tab

The XML Editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
This section provides instructions for updating the your-quotes.xml document using the
Grid tab of the XML Editor. The Grid tab is useful for displaying structured data. It is a
convenient way to view a document that contains multiple instances of the same type of
element, for example.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Grid Editor video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
To update an XML document using the Grid tab:
1.

If it is not already open, open your-quotes.xml.

See Opening a Sample XML Document on page 10 if you need help with this step.

At the bottom of the XML Editor window, click the Grid tab.
Stylus Studio displays a table that contains the XML data.

Figure 18. Grid Tab

The left most column, with the Tag Name heading, contains the children of the
<ticker> element. The remaining columns contain the grandchildren of the <ticker>

Stylus Studio User Guide

Updating an XML Document Getting Started

element. The heading of each column identifies the element name company,
symbol, and so on.
You can resize columns by dragging the handle on the column headings right side.
You can change the element order in the document by dragging the handle on the
column headings left side. Stylus Studio swaps positions with the column on which
you come to rest.

Tip

Select the last row by clicking to the left of the last <quote> element.
The row is highlighted in blue.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click the Insert row after ( ) button.

A new instance of the <quote> element is added to the document. The cursor is placed
in the <company> element cell.

Figure 19. Grid with a New Row

Type XML Designs and press Enter.

Stylus Studio creates the value for the <company> subelement.

Press Tab (or use the right arrow key) to move the cursor to the next cell in the row.

Repeat Step 5 and Step 6 to create values for the <symbol> and <exchange>
subelements.

If you want, you can continue to add the data contained in a quote element.

Modifying Values
It is easy to change and delete values in grid fields:

To change the value of any field, double-click the field and type the new data. Press
Enter to save the change.

To delete the value of a field, double-click the field, select the text you want to delete,
and press the Delete key.

Moving Around the Grid

You can move around the grid using the mouse and the keyboard.
Using the mouse, click where you want to place the cursor.
Using the keyboard:

Use the Tab key to advance the focus to the next cell; use Shift + Tab to move the
focus to the previous cell

Use the arrow keys to move the focus in the direction of the arrow you choose
32

Stylus Studio User Guide

Working with Stylesheets Getting Started

This section helps you get started working with XSLT stylesheets. To focus on stylesheets
that map XML to XML, see Using the XSLT Mapper Getting Started on page 44. To
learn about using XML Publisher to generate XSLT for dynamic HTML reports, see
Chapter 15, Publishing XML Data.
Except for the first topic, each of the following topics contains instructions for working
with a sample XSLT stylesheet. You should perform the steps in each topic before you
move on to the next topic. After the first topic, some steps depend on actions you
performed in a previous topic.
This introduction to working with stylesheets in Stylus Studio is organized as follows:

Opening a Sample Stylesheet on page 33

XSLT Stylesheet Editor Quick Tour on page 34

XSLT Scenarios on page 38

To get started, youll need to start Stylus Studio if you havent already. See Starting
Stylus Studio on page 8 if you need help with this step.

Opening a Sample Stylesheet

To open the your-quotes.xsl sample XSLT stylesheet in Stylus Studio:
1.

In the File Explorer or Open dialog box, navigate to the examples\quotes directory in
your Stylus Studio installation directory.
Alternative: If the Stylus Studio examples project is open, you can access this file from
the Project window. To open the examples project, open examples.prj in the Stylus
Studio examples directory.

Stylus Studio User Guide

Getting Started with Stylus Studio

Double-click your-quotes.xsl. Stylus Studio displays the your-quotes.xsl document

in the XSLT Source tab of the XSLT editor.

Figure 20. Stylus Studios XSLT Editor

As with the XML Editor, Stylus Studio uses different colors to distinguish markup,
tag names, and data in the XSLT Editor.

XSLT Stylesheet Editor Quick Tour

When you use the Stylus Studio XSLT stylesheet editor, you work with XSLT stylesheets,
XML source documents, and result documents. This quick tour is organized to introduce
you to some of the main features for working with XSLT in Stylus Studio:

Parts of the XSLT Editor on page 35

Exploring the XSLT Source Tab on page 35

Exploring the Params/Other Tab on page 38

Stylus Studio User Guide

Working with Stylesheets Getting Started

Parts of the XSLT Editor

The XSLT Editor consists of four tabs that allow you to work with XSLT in different
ways, based on your preferences and the functionality that you desire.

XSLT Source. Use the XSLT Source tab when you want to directly edit or view the
XSLT source code that comprises your stylesheet. The XSLT Source tab can also be
a good way to learn more about XSLT.
XSLT source is also visible from a pane within the Mapper tab.

Tip

Mapper. The Mapper tab allows you to create XSLT by graphically mapping source

document nodes to nodes in a target document. Stylus Studio interprets the mappings
to generate XSLT that will yield a document conforming to the document described
in the Set Target Document pane.
Using the Mapper tab is discussed in detail in Using the XSLT Mapper Getting
Started on page 44.

Note

Params/Other. You use the Params/Other tab to specify the encoding Stylus Studio

uses to store the stylesheet, the stylesheets output method, and the encoding Stylus
Studio uses for the document that results from applying this stylesheet. You can also
use this tab to view default values for parameters used by your stylesheet.

Exploring the XSLT Source Tab

This topic is part of a sequence. If your-quotes.xsl is not open, see Opening a Sample
Stylesheet on page 33.
To work with the XSLT Source tab:
1.

In the stylesheet text, click anywhere below the third xsl:template instruction (line
11).

Stylus Studio User Guide

Getting Started with Stylus Studio

In the status bar just below the XSLT Editor tool bar, Stylus Studio displays match: /.
This indicates that the location you clicked is inside a template that matches the root
node.

Figure 21. Current Template Identity Is Displayed at the Top of the Editor
2.

Click in the xsl:stylesheet instruction (line 5).

Now the status bar is blank. This instruction is not part of a template.

In the XSLT Editor tool bar, click Add a new template

.
Stylus Studio inserts the following after the last template already specified in the
stylesheet.
<xsl:template match="NewTemplate">
</xsl:template>

To define a new template, replace NewTemplate with the match pattern you want, and
add contents to the new template as needed.
Tip

You can also create a new template by double-clicking a node on the schema tree.
Templates that match nodes in the XSLT document are displayed with a check in the
schema tree, as shown here.

Yellow indicates that the text cursor in the XSLT source is within that template.

Stylus Studio User Guide

Working with Stylesheets Getting Started

In the XSLT Editor tool bar, click Template Mode

Stylus Studio displays only the new template.

, which is the right most button.

Figure 22. Use Template Mode to Focus on a Single Template

You can edit the stylesheet in either template mode or in full source mode. In template
mode, Stylus Studio displays one template at a time. In full source mode, Stylus
Studio displays the whole stylesheet.
In large or complex stylesheets, use the XSLT Editors status bar to identify the
current template.

Tip

In the upper right corner of the editing pane, click the down arrow.
Stylus Studio displays a list of the templates in the stylesheet with their match
patterns.

Figure 23. You Can Show Individual Templates in a Stylesheet

Click match: *|/. This displays the template that matches every element and the root
node.
Every stylesheet that Stylus Studio creates includes two built-in templates. One builtin template matches every element and the root node. The other built-in template
matches all text and attribute nodes. See Using Stylus Studio Default Templates on
page 437.
To delete a template, click the match pattern for the template you want to delete and
in the XSLT Editor tool bar. You must be in template
then click Delete template
mode to delete a template.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click Full Source Mode

.
Stylus Studio displays the complete stylesheet. The cursor is at the beginning of the
template that was being displayed in template mode.

Exploring the Params/Other Tab

Click the Params/Other tab:

Drop-down menus let you specify the encoding format used to store the stylesheet in
Stylus Studio, as well as method and encoding output attributes. A simple grid displays
the name, source URL, and default value of any global parameters used by the active
stylesheet, as well as by any imported ones.

Figure 24. Specify XSLT Parameters Here or in XSLT Source

All information that you can specify in the Params/Other tab can also be specified in the
XSLT source. For example, you can specify the XSLT encoding in the processing
instruction at the beginning of the stylesheet; you can specify the output method and
encoding with the xsl:output instruction. Stylus Studio automatically updates the XSLT
source with any changes you make in the Params/Other tab, and vice versa.

XSLT Scenarios
This topic is part of a sequence. If your-quotes.xsl is not open, see Opening a Sample
Stylesheet on page 33. The sequence starts with Exploring the XSLT Source Tab on
page 35.
38

Stylus Studio User Guide

Working with Stylesheets Getting Started

To apply a stylesheet to an XML document in Stylus Studio, you use a scenario. A

scenario is a group of customizable settings that allows you to experiment with different
source XML documents (that is, the XML document to which you will apply the XSLT),
processors, parameter values, post-processors, and profiling settings. You can also use
scenarios to perform validation on the XML document that results from the XSLT
processing. (Validation is always performed before any post-processing you specify.)

Figure 25. Scenarios Let You Easily Test Stylesheets and XML Source

You can define multiple scenarios using different settings to see how each affects
document processing. Stylus Studio also supports scenarios for Web service calls,
XQuery, and XML pipelines.
An XSLT scenario is defined by a single stylesheet-XML document pair. You can
associate any number of scenarios with a stylesheet, though only one scenario can be in
effect at the time the XSLT is processed. Similarly, you can associate any number of
scenarios with an XML source document.
Tip Stylus Studio lets you work with several XSLT processors, including Saxon, MSXML

and .NET.
A scenario has already been created for the your-quotes.xsl stylesheet, using the yourthe source XML document. Run the scenario now and look at the output
created by the XSLT defined in your-quotes.xsl.
quotes.xml as

Stylus Studio User Guide

Getting Started with Stylus Studio

To run a scenario, click Preview Result

Stylus Studio processes the source XML document using the XSLT stylesheet you specify
and displays the results in the Preview window.

Figure 26. XSLT Processing Results are Shown in the Preview Window

By default, results are displayed using a Web browser. If you choose, you can display
results in tree or text format, by clicking Preview in Tree
and Preview Text
in the
Preview window tool bar.
Use the scroll bar to review the HTML in the Preview window. You can see that the values
come from the XML document your-quotes.xml.
Tip If it is not already open, you can open the source XML document specified in a scenario
by clicking Open XML From Scenario
in the XSLT Editor tool bar.

Stylus Studio User Guide

Working with Stylesheets Getting Started

Working with Scenarios

To define additional scenarios, click the down arrow next to the scenario field in the XSLT
Editor tool bar, and click Create Scenario. After you have more than one scenario, click
the same down arrow to select the scenario you want to use to preview a result.
To change the properties of a scenario, or to delete a scenario, select the scenario you want
to change or delete, and then click Browse
to the right of the scenario name field.
Stylus Studio displays the Scenario Properties dialog box.

About Preview
When you preview a result, Stylus Studio automatically saves the changes you have made
to the document. If you want to revert to the documents previous state, you can use the
undo function (Edit > Undo).

Working with a Sample Result Document

This topic is part of a sequence. If your-quotes.xsl is not open, see Opening a Sample
Stylesheet on page 33. The sequence starts with Exploring the XSLT Source Tab on
page 35.
To work with a sample result document, follow these steps:
1.

In the Preview window, click anywhere in the display.

Stylus Studio User Guide

Getting Started with Stylus Studio

Using its back-mapping functionality, Stylus Studio displays the template in the
XSLT Editors status bar and flags the line that generated the line you clicked with a
blue pointer.

Figure 27. Back-mapping Shows which XSLT Generated a Result

Stylus Studio User Guide

Working with Stylesheets Getting Started

In the left tool bar of the Preview window, click Preview Text
displays the HTML file that generates the browser display.

. Stylus Studio

Figure 28. You Can Render XSLT Results as Plain HTML

Note

Click anywhere in the HTML display. The gray background identifies any HTML that
was generated by the same template.
This works in reverse as well. If you click a line in a template (full source mode or
template mode), Stylus Studio uses a gray background to display the HTML
generated by that template.

In the left tool bar, click Export Preview

. Stylus Studio displays the Save As
dialog box. If you want, you can enter a file name and click Save to preserve the
generated HTML file. Otherwise, click Cancel.
Notice the tab at the bottom of the XSLT Preview window. It specifies your-quotes
[your-quotes.xsl]. After you create another scenario and apply the stylesheet in that
scenario, another tab with the name of that scenario will be displayed. You can click
the tab for the result you want to view and easily compare result documents from
different scenarios.

Stylus Studio User Guide

Getting Started with Stylus Studio

Using the XSLT Mapper Getting Started

The XSLT Mapper is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
This section helps you get started using the XSLT Mapper to create stylesheets that
aggregate data and transform XML. The sample files used in this section are in the Stylus
Studio examples\simpleMappings directory. If you follow the procedures in this section,
you create the BooksToCatalog.xsl stylesheet. A sample version of this stylesheet,
sampleBooksToCatalog.xsl, is also in the examples\simpleMappings directory of your
Stylus Studio installation directory.
Each of the topics in this section contains instructions for working with sample XML
documents that you can use to familiarize yourself with the XSLT Mapper. You should
perform the steps in each topic before you move on to the next topic after the first topic,
some steps depend on actions you performed in a previous topic.
This section covers the following topics:

Opening the XSLT Mapper on page 44

Mapping Nodes in Sample Files on page 46

Saving the Stylesheet and Previewing the Result on page 50

Deleting Links in Sample Files on page 51

Defining Additional Processing in Sample Files on page 51

In addition to the topics described in this section, the Stylus Studio User Guide contains
other sources of information on XSLT:

To learn more about XSLT, see Working with XSLT on page 377.

To get started XSLT Editor features for stylesheets, see Working with Stylesheets
Getting Started on page 33.

To learn about the XSLT mapper in greater detail, see Creating XSLT Using the
XSLT Mapper on page 507.
To get started, you will need to start Stylus Studio if you havent already. See Starting
Stylus Studio on page 8 if you need help with this step.

Opening the XSLT Mapper

This procedure describes how to open the XSLT Mapper and select the files you want to
use for the drag-and-drop operations that will define your XSLT stylesheet.

Stylus Studio User Guide

Using the XSLT Mapper Getting Started

To open the XSLT Mapper:
1.

From the Stylus Studio menu bar, select File > New > XSLT Stylesheet.
Stylus Studio displays the Scenario Properties dialog box.

Click the Cancel button to dismiss the dialog box.

Click the Mapper tab.

Stylus Studio displays XSLT editor with the Mapper tab selected. The source pane
beneath the mapper panes appears by default, allowing you to see how the mappings
of XML document elements are rendered as XSLT. The source pane is fully editable
and synchronized with the XSLT Mapper. Of course, you can always click the XSLT
Source tab for a full-screen view of your XSLT code.

Figure 29. XSLT Editor Mapper Tab for a New Stylesheet

The Project window also appears if it was open the last time Stylus Studio was
closed. You can close it.

Tip

Click the Add Source Document button at the top of the mappers left pane.
Stylus Studio displays the Open dialog box.

Stylus Studio User Guide

Getting Started with Stylus Studio

For this example, navigate to the examples\simpleMappings directory in the Stylus

Studio installation directory.

Double-click books.xml.

Click the Set Target Document button at the top of the Mappers right pane.
Stylus Studio displays the Open dialog box.

For this example, navigate to the examples\simpleMappings directory in the Stylus

Studio installation directory.

Double-click catalog.xml.
Stylus Studio displays tree diagrams of these XML documents. The default XSLT
source code has not been altered at this point.

Figure 30. XSLT Mapper Tab with Source and Target Documents

Mapping Nodes in Sample Files

This topic is part of a sequence that starts with Opening the XSLT Mapper on page 44.

Stylus Studio User Guide

Using the XSLT Mapper Getting Started

To define links and examine the stylesheet Stylus Studio creates:
1.

You can display an entire tree using the asterisk key (*) on your keyboards number
pad.

Tip

In the Mapper tab, expand the tree for both books.xml and catalog.xml.

In books.xml, place the pointer over the book repeating element.

Press and hold the left mouse button, and drag from book to the Book repeating element
in catalog.xml.
Stylus Studio draws a line as you drag.

Release the mouse button to create the link between book and Book.
Stylus Studio creates an xsl:for-each block that links the book and Book repeating
elements. (If you mouse over the block, xsl:for-each appears in a pop-up to indicate
the XSLT operation represented by the link.)
If you prefer, you can render xsl:for-each as a simple line. You might want to do this
to simplify the appearance of the mapper canvas. Select Tools > Options from the
menu, and then navigate to Module Settings > XSLT Editor > Mapper.

Figure 31. xsl:for-each Block Displayed by the XSLT Mapper

Also notice that the complete xsl:for-each instruction has been added to the XSLT
source, which appears in the XSLT source pane under the XSLT Mapper canvas. The
back-mapping pointer identifies the line of XSLT that was just added to stylesheet.

Stylus Studio User Guide

Getting Started with Stylus Studio

The template contains an xsl:for-each instruction that selects the book element,
which is the node you selected in Step 2. The output from this template is an empty
Book element, which is the node that was the target of the link. Stylus Studio created
the Catalog element automatically, to provide the document structure necessary to
support the Book element.
By default, Stylus Studio creates an xsl:value-of instruction when you link one
element to another; Stylus Studio creates an xsl:for-each instruction if you link two
repeating elements. You can also create other types of instructions graphically,
including xsl:if, xsl:choose, and xsl:apply-template.

Tip

Click the Params/Other tab.

In the Output method: field, display the drop-down list and select xml. (Even if the
setting for Output method is unspecified, Stylus Studio still generates XML.) Other
choices for the output method include text and HTML.

Click the Mapper tab.

The xsl:output instruction is added to the XSLT source:
<xsl:output method="xml"/>

Note

Create another link from the title element to the Title element.
When you map, you always map from the source document to the destination
document.

Stylus Studio User Guide

Using the XSLT Mapper Getting Started

Click the XSLT Source tab to see the new instructions in the template. (If you prefer,
you can simply adjust the splitter between the XSLT source pane and the XSLT
Mapper canvas.

Figure 32. Stylus Studio Builds XSLT Based on the Mapper Links

For each link you define, Stylus Studio adds instructions to the template that matches
the root node. In the XSLT you have composed so far, the XSLT inserts a Book element
for each book element it finds in the source document. In the Book element, the
stylesheet selects the title elements. For each title element, it inserts a Title
element. Finally, in each Title element, the stylesheet extracts the value of the current
context node, which is the title node.
Why does the stylesheet extract the value of the title nodes but not the book nodes?
The title node has only a text node as its child. In this situation, the default is that
the XSLT Mapper inserts an xsl:value-of instruction.

Stylus Studio User Guide

Getting Started with Stylus Studio

Saving the Stylesheet and Previewing the Result

This topic is part of a sequence that starts with Opening the XSLT Mapper on page 44.
To save the stylesheet and preview the result:
1.

Click Save

. Stylus Studio displays the Save As dialog box.

In the URL: field, type BooksToCatalog.xsl.

Click the Save button.

This saves the stylesheet that Stylus Studio has generated. It does not matter that you
have not finished mapping all nodes.

In the upper left corner of the XSLT Mapper, click Preview Result

When you create a stylesheet using the XSLT Mapper, Stylus Studio automatically
creates a scenario for you, using the source document you specify as the source
document for the scenario. Scenarios and their value in the application development
process are described earlier in this chapter. See XSLT Scenarios on page 38.

Tip

Stylus Studio displays the result of processing books.xml with the stylesheet you
created in the XSLT Mapper in the Preview window.

Figure 33. Result of Applying XSLT to books.xml

The result document uses the same schema as the target document, catalog.xml in
this example. Because not all nodes have been mapped yet, the result document does
not contain all nodes found in books.xml (author and subject nodes, for example).

You can confirm that the result document is incomplete by viewing books.xml. Click
Open XML From Scenario
, which is at the top of the Mapper tab.
Stylus Studio displays the books.xml document in the Stylus Studio XML Editor.

Review the XML document, and then click the document tab for the
BooksToCatalog.xsl stylesheet to re-display the XSLT Editor.

Stylus Studio User Guide

Using the XSLT Mapper Getting Started

Deleting Links in Sample Files

This topic is part of a sequence that starts with Opening the XSLT Mapper on page 44.
To delete links:
1.

Click the Mapper tab if it is not already selected.

Click the title to Title link to select it.

Figure 34. Click a Link to Select It

Tip

Press the Delete key, or

Right-click the selected link. This displays a shortcut menu.

Click Delete to delete the selected link.

In addition to Delete, the shortcut menu displays the following options:

Go To Source displays the line of XSLT code represented by the link you select
in the XML Editor.

Carry Value allows you to create <xsl:value-of select="."/> statements. This

option is available for links representing xsl:for-each instructions only.

Defining Additional Processing in Sample Files

The stylesheet that the XSLT Mapper creates is not limited to the instructions that Stylus
Studio adds. You can edit the template as you would any template. Stylus Studio
automatically incorporates any changes you make to the template and displays them in the
Mapper tab, if it is appropriate to do so.
In addition, you can perform external processing by, for example, defining Java functions
and incorporating those functions in your XSLT stylesheet. Like standard supported
XSLT functions, user-defined Java functions can be created graphically in the XSLT
Mapper just right click on the mapper canvas, select Java Functions from the shortcut
menu, and select any registered Java function you want to use.
Stylus Studio User Guide

Getting Started with Stylus Studio

See Processing Source Nodes on page 534.

Debugging Stylesheets Getting Started

The Stylus Studio debugger allows you to follow XSLT processing and detect errors in
your stylesheets. Stylus Studio includes sample files that you can experiment with to learn
how to use the debugger. To get you started, this section provides step-by-step instructions
for using the debugger with these sample files. You should perform the steps in each topic
in the order of the topics.
For complete information about how to use the debugger, see Debugging Stylesheets on
page 551.
In addition, Stylus Studio allows you to observe and debug the interaction between your
Java code and XML data. See Debugging Java Files on page 561.
This section includes the following topics:

Setting Up Stylus Studio to Debug Sample Files on page 52

Inserting a Breakpoint in the Sample Stylesheet on page 53

Gathering Debug Information About the Sample Files on page 55

To get started, youll need to start Stylus Studio if you havent already. See Starting
Stylus Studio on page 8.

Setting Up Stylus Studio to Debug Sample Files

To set up Stylus Studio to debug sample files:

Open the videosDebug.xsl stylesheet, located in the examples\VideoCenter directory

where Stylus Studio was installed.
Alternative: If the Stylus Studio Project window is open, you can access this
stylesheet from the examples project.
Stylus Studio displays the videosDebug.xsl stylesheet in the XSLT editor.

In the XSLT editor tool bar, click Preview Result

to run the predefined scenario
DebugVideosScenario. The source XML document is videos.xml.

Stylus Studio User Guide

Debugging Stylesheets Getting Started

Stylus Studio applies the stylesheet and displays the results (a finished HTML page
that displays information about a single video) in the Preview window.

Figure 35. Preview of videosDebug.xsl

Inserting a Breakpoint in the Sample Stylesheet

This topic is part of a sequence that starts with Setting Up Stylus Studio to Debug Sample
Files on page 52.
As with any debugger, in the Stylus Studio XSLT debugger you insert a breakpoint where
you want to suspend processing and examine what is going on. You can do this using the
Debug menu or the debug set of tools in the tool bar.
Tip Tools in the tool bar are in grouped by function. These groups, like the one for debug tools

shown here, are dockable and can be moved anywhere you please.

Stylus Studio User Guide

Getting Started with Stylus Studio

To insert a breakpoint in the sample stylesheet:
1.

In the XSLT Editor, click in line 202. Line numbers appear in the lower right corner
of the XSLT Editor window. Line 202 starts with
<xsl:template match="director">

To display lines in Stylus Studio text editors, click Tool > Option > Editor General,
and select Show line numbers.

Tip

In the Stylus Studio tool bar, click Toggle Breakpoint

.
Alternative: If you prefer, select Debug > Toggle Breakpoint, or press F9.
Stylus Studio displays a red circle to the left of the line that contains the xsl:template
match="director" instruction. The XSLT processor will stop processing when it gets
to the instantiation of this template.

Figure 36. A Red Circle Shows Where Breakpoints Are Set

Do not do it, but to remove a breakpoint, you click in the line that has the breakpoint
and then click Toggle Breakpoint (or F9). The Toggle Breakpoint button and F9 key
operate as toggles.
3.

Press F5 to start debugging.

Alternative: In the Stylus Studio tool bar, click Start Debugging
.
The XSLT processor displays a yellow triangle to indicate where processing has been
suspended. Instead of the finished HTML created when you first ran the scenario, the
Preview window displays just the HTML code because complete processing of the
XSLT was suspended before the finished HTML could be rendered.

Figure 37. Yellow Triangle Shows Where XSLT Processing Stopped

Do not do it, but to stop debugging, you can click Cancel in the lower right corner of
in the Stylus Studio tool bar.
the XSLT editor window, or click Stop Debugging
54

Stylus Studio User Guide

Debugging Stylesheets Getting Started

If you click Preview Result

instead of pressing F5, Stylus Studio applies the
stylesheet without running the debugger. Pressing F5 always invokes the debugger. If
there are no breakpoints, and no errors, processing completes and Stylus Studio
displays the result in the Preview window.

Gathering Debug Information About the Sample Files

This topic is part of a sequence that starts with Setting Up Stylus Studio to Debug Sample
Files on page 52.
When XSLT processing is suspended at a breakpoint, Stylus Studio displays the
Variables, Call Stack, and Watch windows.

Figure 38. Variable, Call Stack, and Watch Windows Appear During Debugging

Stylus Studio User Guide

Getting Started with Stylus Studio

You can use the information in these windows to learn about potential and actual problems
encountered in your XSLT processing.
Tip You can also control the display of these windows using the Debug menu, shown here, or

the tool bar.

The Variables Window

The Variables window displays a list of variables and their values when processing was
suspended.

Figure 39. Variables Window

As you can see, the stylesheet defines the VideoName parameter, which had no value when
processing was suspended. In addition, the Variables window shows you that when
processing was suspended, the processor was operating on the first director child element
of the first video child element of the first videos child element of the first result element.

Stylus Studio User Guide

Debugging Stylesheets Getting Started

The Call Stack Window

The Call Stack window displays a history of the steps the processor performed to reach
the point at which processing was suspended, including the names of the templates that
are currently instantiated, in most recent-to-oldest order.

Figure 40. Call Stack Window

In this example, the XSLT processor has instantiated the director template, which is part
of the instantiation of the video template, which is part of the instantiation of the template
that matches the root node.
To step out of debug Step out

, or press Shift+F11.

The processor completes the instantiation of the director template, which adds some
HTML to the Preview window. The yellow triangle moves to show the new location in the
XSLT source.

Figure 41. Stepping Out Advances the Processor

As you can see in the Call Stack window, the processor is now two levels deep in the
template that matches the root node, instead of three levels deep as it was previously. The
value of the context node in the Variables window is /result[1]/videos[1]/video[9] (it
was /result[1]/videos[1]/video[9]/director[1]).

Stylus Studio User Guide

Getting Started with Stylus Studio

The Watch Window

If your application contains a lot of variables, the Watch window allows you to focus on
the variables in which you are particularly interested.

Figure 42. Watch Window Lets You Track Variables

To enter a variable to watch:
1.

Double-click the Name field.

Type the name of the variable you want to watch and press Enter.
As processing continues, the Watch window displays the values of the variables you
specify.

Ending Processing During a Debug Session

To end processing during a debug session:
1.

In the Preview window, click any line of text.

In the XSLT Source tab, Stylus Studio displays the blue back-mapping triangle that
indicates the line in the stylesheet that generated the output line you clicked.

Stylus Studio User Guide

Debugging Stylesheets Getting Started

In the lower right corner of the XSLT editor, click the Cancel button to end
processing.

Figure 43. Cancelling Processing During Debugging

Stylus Studio displays a notification message that indicates that processing has been
stopped and, optionally, allows you to jump to the location where processing ended.

Figure 44. You Can Jump to Where XSLT Processing Ended

Click Yes to jump to the location where processing ended.

The cursor appears on line 146 of the XSLT Source tab, which contains
<xsl:apply-templates select="director"/>.

Stylus Studio User Guide

Getting Started with Stylus Studio

In the XSLT editor tool bar, click Open XML from Scenario
.
Stylus Studio displays the XML source document that the stylesheet operates on. As
you can see, the first result element is the document element.

Figure 45. Viewing the XML Source for an XSLT Transformation

This section demonstrated some of the major features of Stylus Studios debug tools,
including specialized windows for presenting call stack and variable information. For
complete information on using the XSLT debugger, see Debugging Stylesheets on
page 551.

Stylus Studio User Guide

Defining a DTD Getting Started

This section provides a quick tour of the main features of the DTD Editor. It provides
instructions that you can follow to actually define a simple DTD. For complete
documentation about how to use the Stylus Studio DTD Editor, see Defining Document
Type Definitions on page 665.

Process Overview
When you use Stylus Studio to define a DTD, the main steps you perform are:
1.

Create a new DTD schema file.

Define the elements that contain the raw data.

Define the elements that contain other elements.

In the container elements, specify the rules for the contained elements. That is,
specify whether a contained element is optional or required, whether there can be
more than one, and what order contained elements must be in.

This section provides step-by-step instructions for defining the bookstore.dtd schema
file. You should perform the steps in each topic in the order of the topics. This section
includes the following topics:

Creating a Sample DTD on page 61

Defining Data Elements in a Sample DTD on page 62

Defining the Container Element in a Sample DTD on page 63

Defining Structure Rules in a Sample DTD on page 63

Examining the Tree of a Sample DTD on page 65

To get started, youll need to start Stylus Studio if you havent already. See Starting
Stylus Studio on page 8.

Creating a Sample DTD

To create a new DTD schema file:
1.

From the Stylus Studio menu bar, select File > New > DTD Schema.

Click Save
.
Stylus Studio displays the Save As dialog box.

Stylus Studio User Guide

Getting Started with Stylus Studio

Navigate to the Stylus Studio examples directory.

In the URL: field, type bookstore.dtd.

Click the Save button.

Defining Data Elements in a Sample DTD

This topic is part of a sequence that starts with Creating a Sample DTD on page 61.
In your DTD, suppose you want a book element to be optional. Further, if a book element
is present, it must always have exactly one title element and it can have any number of
author elements. The title and author elements contain only raw data.
To accomplish this, perform the following steps:
1.

At the bottom of the DTD editor, click the Tree tab.

Click the DTD node at the top of the tree if it is not already selected.

Click New Element Definition

, which is the top button in the tool bar on the left
side of the DTD editor window.
Stylus Studio displays an entry field for the element name.

Type title and press Enter.

Stylus Studio displays the new element, title, and the elements properties in the
Properties window.

Figure 46. New Element in the DTD Editor

Click New Modifier

.
Stylus Studio displays an entry field for the elements modifier.

Stylus Studio User Guide

Defining a DTD Getting Started

Double-click Zero or More.

The new modifier is added to the element.

Click Add #PCDATA

To define the author element, repeat Step 2 through Step 7. In Step 4, type author
instead of title.

When you are done, the Stylus Studio desktop should resemble the following:
i

Figure 47. Creating a DTD with Two Elements

Defining the Container Element in a Sample DTD

This topic is part of a sequence that starts with Creating a Sample DTD on page 61.
To define the book element:
1.

Click the DTD node at the top of the tree.

Click New Element Definition

Type book and press Enter.

Defining Structure Rules in a Sample DTD

This topic is part of a sequence that starts with Creating a Sample DTD on page 61.
To specify the rules for the structure of the book element:
1.

Click the book node in the DTD tree if it is not already selected.

Click New Modifier

In the drop-down list that appears, scroll down and double-click Sequence. This
indicates that the book element can include one or more elements.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click New Reference to Element

Type title in the entry field and press Enter.

Because the reference to the title element appears immediately after the Sequence
modifier, the DTD editor assumes that the default behavior is what is wanted. That is,
the book element must contain exactly one instance of the title element.

Click the Sequence modifier.

Click New Modifier

Double-click One or More. (There can be one or more author elements in each book
element.)

Click New Reference to Element

10.

Type author in the entry field and press Enter.

At this point, the definition of the book element is complete, and the tree diagram of
bookstore.dtd should look like this:

Figure 48. Early Steps of bookstore.dtd

However, you have not yet specified that you want the book element itself to be optional.
You need to do this in the element that references the book element. For example, suppose
the bookstore element is the root element in XML documents that use this DTD. Further
suppose that you want the book element to be a child of the bookstore element.
You can define the bookstore element as follows:

Click the DTD node at the top of the tree.

Click New Element Definition

Type bookstore in the entry field and press Enter.

Click New Modifier

In the drop-down list that Stylus Studio displays, double-click Optional.

Stylus Studio User Guide

Defining a DTD Getting Started

Click New Reference to Element

Type book in the entry field and press Enter.

Click Save

Examining the Tree of a Sample DTD

This topic is part of a sequence that starts with Creating a Sample DTD on page 61.
Your DTD should now look like Figure 49.
i

Figure 49. Finished bookstore.dtd

To complete this DTD, you could define magazine and newsletter elements. In the
bookstore element definition, you could add references to the magazine and newsletter
elements. You could also expand the definition of the book element to include information
about the publisher, price, publication date, and number of pages.

Stylus Studio User Guide

Getting Started with Stylus Studio

Defining an XML Schema Using the Diagram Tab

Getting Started
This section provides a quick tour of the main features of the Diagram tab of the XML
Schema Editor and shows you how to define a simple XML Schema. For complete
documentation about how to use the XML Schema Editor, see Creating an XML Schema
in Stylus Studio on page 568.
The topics in this section provide step-by-step instructions for defining the
bookstoreDiagram.xsd XML Schema document. You should perform the steps in each
topic in the order of the topics.
This section includes the following topics:

Introduction to the XML Schema Editor Diagram Tab on page 67

Editing Tools of the XML Schema Diagram Tab on page 76

Description of Sample XML Schema on page 81

Defining a complexType in a Sample XML Schema in the Diagram View on

page 81

Defining Elements of the Sample complexType in the Diagram View on page 90

To get started, you will need to start Stylus Studio if you have not already. See Starting
Stylus Studio on page 8.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Introduction to the XML Schema Editor Diagram Tab

The recommended way to define an XML Schema in Stylus Studio is to start with the
Diagram tab of the XML Schema Editor, which is shown in Figure 50.

Figure 50. Diagram Tab of the XML Schema Editor

When you use the Diagram tab to define an XML Schema, you can create XML Schema
nodes directly on the XML Schema diagram pane using tools on the tool bar or from the
XML Schema > Diagram and shortcut menus. You can also type in the text pane, which
appears under the Diagram tab. The text pane displays the XML Schema syntax Stylus
Studio creates for you as you work in the diagram pane.
Stylus Studio ensures that the XML Schema you create is valid. For example, any nodes
you define are created in the required order in the XML document that contains the XML
Schema definition, regardless of the order in which you create them.

Stylus Studio User Guide

Getting Started with Stylus Studio

The Diagram tab, shown in Figure 50, consists of three main areas:

Diagram Pane on page 68

Text Pane on page 73

Definition Browser on page 75

This section describes these areas and how to work with them.

Diagram Pane
The diagram pane contains graphical representations of the elements, attributes, and other
nodes that make up your XML Schema.

Figure 51. Schema Diagram Pane

Nodes
Each node displayed in the diagram pane is represented by its own symbol; tool tips,
which are displayed when you hover over a node in the diagram, identify the nodes type

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

(element, attribute, sequence, and so on). The symbols used in the diagram are
summarized in Table 1.
Table 1. Symbols Used in the XML Schema Diagram
Symbol

Represents
schema (xsd:schema)
annotation (xsd:annotation)
documentation (xsd:documentation)
element (xsd:element)
attribute (xsd:attribute)
attributeGroup (xsd:attributeGroup)
simpleType (xsd:simpleType)
complexType (xsd:complexType)
choice (xsd:choice)
sequence (xsd:sequence)
key (xsd:key)
key reference (xsd:keyref)
unique (xsd:unique)
group (xsd:group)
simpleContent (xsd:simpleContent)
complexContent (xsd:complexContent)
restriction (xsd:restriction)
extension (xsd:extension)
union (xsd:union)
list (xsd:list)

Stylus Studio User Guide

Getting Started with Stylus Studio

Nodes can be expanded and collapsed using the plus and minus symbols, respectively, that
appear on the right side of the node. In Figure 54 for example, the PurchaseOrderType
complexType has been expanded. The shipTo element has not.
Displaying Properties
To streamline the diagram, most nodes are displayed with their properties hidden by
default. Exceptions include element, extension, and restriction nodes, for which the type
is displayed, as shown in the productName element in Figure 52.

Figure 52. Most Nodes Appear with Properties Hidden

You can change the display for classes of nodes (all elements, for example) using the
Diagram Properties dialog box, shown in Figure 53. (In addition, the Properties window

displays all the properties for any node you select.)

Figure 53. Schema Diagram Properties Dialog Box

For each node property, you can choose to

Show the property

Show the property only if it is not empty

Hide the node

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

If all of a nodes properties have the same show/hide setting, that value is displayed in the
Inline Visibility in Diagram field. If no value is displayed in the Inline Visibility in Diagram
field, it means that two or more properties have different show/hide settings.
To display the Diagram Properties dialog box:

Select Diagram > Properties from the Stylus Studio menu

Select Properties from the diagram shortcut menu

Tip You can also change schema diagram properties on the Diagram page of the Options
dialog box Tools > Options > Module Settings > XML Schema Editor > Schema
Details.

To change node properties display:

Display the Diagram Properties dialog box, or the Schema Details page of the
Options dialog box.

Select the node whose properties display you want to change.

To hide all properties, click the Hide All button. To restore defaults, click the Restore
Defaults button.

Tip

Click OK.

Background color
Background color is used as another visual cue for information about the XML Schema:

A tan, or light brown, color identifies global nodes these are elements, types, and so
on, that are defined as children of the schema (xsd:schema). In Figure 54, the
purchaseOrder element is an example of a globally defined node.

Stylus Studio User Guide

Getting Started with Stylus Studio

A light yellow background identifies local instances of globally defined types. In

Figure 54, the PurchaseOrderType complexType is a local instance of that type.

Figure 54. Background Colors Show Global and Local Types

Displaying documentation
By default, text associated with documentation elements (xsd:documentation) is hidden.
You can expand documentation elements in the diagram by clicking the Show
Documenation ( ) button, or by selecting Diagram > Show Documentation from the
Stylus Studio menu. When you do, the text associated with all documentation elements
defined in the XML Schema appears, as shown in Figure 55.

Figure 55. Show Documentation with the Click of a Button

Moving around the diagram

There are several ways to move around the diagram pane:

To move from node to node in the diagram, press the arrow keys.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

You can use the scroll bars to explore the diagram; the zoom slider lets you change
the magnification.
Click Go to Definition (
) on the shortcut menu to display a new page that shows
just the type definition.
Click Display Definition (
) on the shortcut menu to jump to the place in the XML
Schema where the type is defined.

Text Pane
The text pane appears directly beneath the XML Schema diagram pane. It displays the
XML Schema code represented by the nodes you create in the diagram. The default font
is Courier New, but you can change it to whatever font you want by clicking the Change
Font button (
).
Stylus Studio synchronizes the diagram and text views of the XML Schema any changes
you make in the diagram are reflected in the text pane, and vice versa. Synchronization
information is displayed in the bar that separates the diagram and text panes. Current
status is displayed on the right. When the two views are synchronized, Stylus Studio
displays this graphic:
. When Stylus Studio detects a change, such as a change to
the text, it displays a message and changes the status graphic, as shown in Figure 56.

Figure 56. Synchronization Status is Monitored and Displayed

Stylus Studio User Guide

Getting Started with Stylus Studio

Stylus Studio also flags any XML Schema errors in the text pane lines that contain errors
are identified with a red dot, and the type and location of the error is displayed in the status
area at the top of the text pane, as shown here:

Figure 57. Text Pane Highlights XML Schema Errors

When you click the error message, Stylus Studio jumps to that part of the XML Schema
containing the error. When you correct one error, information about the next error
detected by Stylus Studio (if any) is displayed in the status area.
You can use the splitter to resize the text pane to view more or less text, or you can hide
it entirely using the controls on the splitters right side.

Figure 58. Splitter Controls Change Size of Text and Diagram Panes

Stylus Studio supports back-mapping between the text pane and the XML Schema
diagram pane if you click a node in the diagram, Stylus Studio scrolls the text pane to
display the line of XML Schema that defines the node you clicked. A blue triangle is
displayed to the left of the exact line of code.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Definition Browser
The definition browser is a drop-down list that displays all the child nodes of the schema
node. It is located at the top of the Diagram tab.

Figure 59. Definition Browser

When you select a node from the definition browser, Stylus Studio displays a new page in
the XML Schema diagram pane that shows the definition of the node you select. In
addition, the definition browser displays information about that node.

Figure 60. Information About the Selected Node

To return to the page you were viewing previously, press the back (

) button.

Note When you display a node using the definition browser, the focus of the text pane does not

change. Clicking the node jumps you to that part of the XML Schema where the node is
defined.

Stylus Studio User Guide

Getting Started with Stylus Studio

Editing Tools of the XML Schema Diagram Tab

Many of the operations you perform in the Diagram tab can be performed in a number of
ways. This section briefly describes menu and tool bar use, and introduces additional
features for defining XML Schema.
This section covers the following topics:

Menus and Tool Bars on page 76

In-place Editing on page 77

Drag-and-Drop on page 77

QuickEdit on page 78

Refactoring on page 79

Menus and Tool Bars

The complete set of available operations is defined by the menu system. The tool bar
provides a subset of frequently performed operations. The top-level menu (XMLSchema
> Diagram), the shortcut menus, and the tool bar are context sensitive only operations
that are permitted given the current context are available. For example, if you want to add
an element to a sequence, you can

Select XML Schema > Diagram > Add > Element from the main menu

Select Add > Element from the sequence shortcut menu

Click the Add button

on the tool bar and select Element from the drop-down list
it displays
Each of these actions lets you add a new node, in this case, an element, to your XML
Schema definition.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

In-place Editing
In-place editing allows you to change node names and properties directly in the diagram.
For example, say you want to change the value of the Mixed property of the
PurchaseOrderType complexType. Just double-click the property. Stylus Studio opens the
property for editing, as shown in Figure 61.

Figure 61. In-Place Editing

Similarly, if you double-click a node name, Stylus Studio places the property in edit
mode, allowing you to type a new name.
Tip To display all of a nodes properties in the diagram, see Displaying Properties on

page 70.

Drag-and-Drop
An alternative to using the menu and the tool bar is to use drag-and-drop, which lets you
add an existing node to another nodes definition. For example, say you wanted to add an
existing element to a sequence. You can do this by dragging the element icon to the
sequence icon, as shown in Figure 62.

Figure 62. Using Drag-and-Drop to Define a Node

Use drag-and-drop any time you want to define a node using a node already defined in
your XML Schema.
Tip When you drag and drop, you remove the element from its current context. If you want

to make a copy an element, press and hold the CTRL key when you perform the drag
operation.
Typical targets of drag-and-drop operations include the following nodes

Stylus Studio User Guide

Getting Started with Stylus Studio

schema
sequence
choice

all

list
annotation
restriction
union

Typical sources for drag-and-drop operations include the following nodes

simpleType
element
annotation

Tip Any node you drag to the schema node is created as a child of the schema node.

QuickEdit
QuickEdit is a feature of the Diagram tab that streamlines common editing operations. For
example, you can use QuickEdit to

Change a sequence to a choice or to an all

Specify a restriction for a simpleType

Create sequence, choice, any, and all element definitions

For example, the following structure was created by selecting QuickEdit > Add Elements
Choice from the complexTypes shortcut menu.

Figure 63. QuickEdit Creates Complex Definitions With a Click

QuickEdit appears on the top-level and shortcut menus in those contexts in which it is
available, and it is also available on the tool bar by pressing the QuickEdit button .

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Refactoring
Refactoring is a process that allows you to copy globally defined nodes from one XML
Schema and paste them in a new XML Schema. The difference between refactoring and
a simple copy is that refactoring includes both the node you select and all its
dependencies. Consider the following example: here is how the purchaseOrder node
appears when it is copied from purchaseOrder.xsd and pasted into a new XML Schema
document:

Figure 64. Simple Copy/Paste of a Node

Stylus Studio User Guide

Getting Started with Stylus Studio

As you can see, the copy action copies only the selected node to the clipboard. When the
same node is copied using refactoring and pasted into another XML Schema document,
the node, and all its dependencies copied as well.

Figure 65. Refactoring Copy/Paste of a Node

Not all of the diagram or text are displayed in this illustration, but it is clear that more than
just the purchaseOrder node was copied to the clipboard. For example, the
purchaseOrders type, PurchaseOrderType complexType has been copied, as well as
PurchaseOrderTypes element and sequence nodes, such as shipTo, billTo, and items.
If you were to scroll up either the text pane or the diagram pane, you would also see, for
example, the complete definitions for other global complexTypes such as SKU and
USAddress.
To refactor a node:

Note

Right-click the node you want to refactor.

Select Refactoring > Copy from the nodes shortcut menu.

If the node is not globally defined, refactoring is not available.
The node and all its dependencies are copied to the clipboard.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

To paste the node in the target XML Schema document, select Refactoring > Paste
from the shortcut menu.

Description of Sample XML Schema

Suppose you want to define an XML Schema that defines book, magazine, and newsletter
elements. The type of each of these elements is PublicationType. The XML Schema
defines the PublicationType complexType. An element that is a PublicationType has the
following description:

The genre attribute specifies the style of the publication. That is, whether it is a book,
magazine, or newsletter.

There is always exactly one title element.

The subtitle element is optional.

There must be at least one author element and there can be more. Each author
element contains one first-name element and one last-name element.

Of the following three elements, exactly one must always be present:

ISBNnumber
PUBnumber
LOCnumber

The elements must be in the order specified in this list.

The following topics in this section describe how to define this XML Schema using the
Diagram tab of the XML Schema Editor.

Defining a complexType in a Sample XML Schema in the Diagram

View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
The steps for defining the PublicationType complexType described in Description of
Sample XML Schema on page 81 are presented in the following topics:

Defining the Name of a Sample complexType in the Diagram View on page 82

Adding an Attribute to a Sample complexType in the Diagram View on page 84

Adding Elements to a Sample complexType in the Diagram View on page 85

Adding Optional Elements to a Sample complexType in the Diagram View on

page 86

Stylus Studio User Guide

Getting Started with Stylus Studio

Adding an Element That Contains Subelements to a complexType in the Diagram

View on page 86
Choosing the Element to Include in a Sample complexType in the Diagram View
on page 88

Defining the Name of a Sample complexType in the Diagram View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
To define a complexType in a sample XML Schema:

From the Stylus Studio menu bar, select File > New > XML Schema.
Stylus Studio displays the XML Schema Editor. Maximize the XML Schema Editor
window. If the Project window is visible, you can close it.

At the bottom of the XML Schema editor, click the Diagram tab.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Stylus Studio displays the Diagram view for the new schema.

Figure 66. The XMLSchema Editor Diagram Tab

Right-click the schema node in the XML Schema diagram pane and select Add >
ComplexType from the shortcut menu.
Alternatives: This action is also available from the XMLSchema > Grid Editing menu.

Stylus Studio User Guide

Getting Started with Stylus Studio

Stylus Studio displays a representation for the new node in the diagram. The
complexType properties appear in the Properties window. The new complexType has
a default name of ComplexType-0.

Figure 67. New complexType

Type PublicationType in the Name property in the Properties window and press
Enter.
Stylus Studio updates the diagram and the XML Schema in the text pane.

Click Save

In the Save As dialog box, in the URL field, type bookstoreDiagram.xsd, and click
Save. You can save it in the examples directory of the Stylus Studio installation
directory or in a directory of your choice.

Adding an Attribute to a Sample complexType in the Diagram View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
To add the genre attribute to the PublicationType complexType:
1.

Right-click the PublicationType node.

In the shortcut menu that appears, select Add > Attribute.

Stylus Studio displays a node for the new attribute (untitled).

Figure 68. Adding an Attribute in the Diagram Tab

In the Properties window, type genre as the name of the new attribute and press Enter.

In the Properties window, click the Type field.

Stylus Studio displays a drop-down list of built-in types.
Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Scroll down to xsd:string and click it, or type xsd:string and press Enter.
The diagram should now look like the one shown in Figure 69.

Figure 69. The Finished genre Attribute

You can toggle the display of attributes by clicking the small triangle at the bottom of
the complexType node.

Tip

Click Save

Adding Elements to a Sample complexType in the Diagram View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
The elements belonging to this complexType must occur in a specific order. Before
defining the first element, you need to create a sequence node to define this requirement
in the XML Schema.
To add the title element to the PublicationType complexType:
1.

Right-click the PublicationType node.

In the shortcut menu that appears, select Add > Sequence.

The sequence node is added to bookstoreDiagram.xsd. The sequence modifier
indicates that if an instance document contains the sequence nodes child elements
(the elements you will add next), they must be in the order in which they are defined.

Type title and press Enter.

Right-click the sequence node

In the shortcut menu that appears, select Add > Element.

A child element is added to the PublicationType node.

In the Properties window, click the Name field and enter title.

In the Properties window, click the Type field.

Stylus Studio displays a drop-down list of built-in types.

Scroll down to xsd:string and click it, or type xsd:string and press Enter.

Stylus Studio User Guide

Getting Started with Stylus Studio

According to the XML Schema requirements described earlier, the title element can
occur only once. By default, the default value for the Min Occur. (minimum occurrences)
and Max Occur. (maximum occurrences) properties is 1. You want exactly one instance of
the title element in PublicationType, so you can accept these defaults.

Adding Optional Elements to a Sample complexType in the Diagram View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
To add the optional subtitle element to the PublicationType complexType:
1.

Right-click the sequence node

In the shortcut menu that appears, select Add > Element.

Below the title element, Stylus Studio displays a rectangle for the new element
definition.

Rename the new element subtitle.

Give the new element a data type of xsd:string.

Give the new element a minimum occurrences value of 0.

You can accept the default of 1 for the Max Occur. property.

Click Save
.
At this point, the XML Schema diagram should look like Figure 70:

Figure 70. PublicationType complexType

Adding an Element That Contains Subelements to a complexType in the

Diagram View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
The sample schema requirements (see Description of Sample XML Schema on
page 81) state that the PublicationType complexType must include at least one author

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

element. Further, an author element must include a first-name element and a last-name
element.
Each element that can contain one or more subelements is a complexType. Consequently,
to add the author element to the PublicationType complexType, you must first define the
AuthorType complexType. You can then add an element that is of AuthorType to the
PublicationType complexType.
To define the AuthorType complexType:
1.

Right-click the schema node in the XML Schema diagram pane and select Add >
Complex Type from the shortcut menu.
Alternatives: This action is also available from the XMLSchema > Grid Editing menu.
Stylus Studio displays a representation for the new node in the diagram. The
complexType properties appear in the Properties window.

Type AuthorType in the Name property in the Properties window and press Enter.
Stylus Studio updates the diagram and the XML Schema in the text pane.

Right-click the AuthorType node in the diagram.

In the shortcut menu that appears, select Add > Sequence.

Stylus Studio displays the sequence node
.

Right-click the sequence node.

In the shortcut menu that appears, select Add > Element.

Type first-name in the Name property in the Properties window and press Enter.

Change the Type property to xsd:string and press Enter.

Repeat Step 5 through Step 8 to add a new element to the sequence, using last-name
as the name of the new element.

Now you can add the author element to the PublicationType complexType:
1.

Right-click the sequence node belonging to the PublicationType node.

In the shortcut menu that appears, select Add > Element.

Stylus Studio displays a representation for the new node in the diagram. The
complexType properties appear in the Properties window.

Type author in the Name property in the Properties window and press Enter.
Stylus Studio updates the diagram and the XML Schema in the text pane.

Stylus Studio User Guide

Getting Started with Stylus Studio

Click the Type field in the Properties window. Stylus Studio displays a drop-down
list of built-in types plus any types you have defined, such as the AuthorType you
defined in the previous procedure.

Select AuthorType from the drop-down list.

A plus sign appears on the right side of the author element. You can click the plus
sign to display the definition of the AuthorType complexType, which was just added
to the author element.

Tip

Click the Max Occur. field.

In the drop-down list that appears, click unbounded.

When you give an element an unbounded maximum number of occurrences, Stylus
Studio renders the node using two outlines, to indicate that multiple occurrences of
this element are allowed.

Tip

Click Save
.
At this point, the XML Schema diagram should look like Figure 71:

Figure 71. author Element with AuthorType complexType

Choosing the Element to Include in a Sample complexType in the

Diagram View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
In the sample XML Schema, you want PublicationType elements to contain an
ISBNnumber, PUBnumber, or LOCnumber element.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

To specify this:
1.

Right-click the sequence node belonging to the PublicationType node.

In the shortcut menu that appears, select Add > Sqeuence.

Stylus Studio displays a representation for the new sequence node in the diagram.
Sequence properties appear in the Properties window.
We added the sequence node in error the specification requires that this node be a
choice node. The QuickEdit feature makes it easy to correct errors such as this.

Right-click the new sequence node. In the shortcut menu that appears, select
QuickEdit > Switch to Choice.
Stylus Studio changes the sequence node to the choice node ( ).

Right-click the new choice node.

In the shortcut menu that appears, select Add > Element.

In the Properties window, change the Name to ISBNnumber and press Enter.

In the Properties window, change the Type xsd:int and press Enter.

Repeat Step 4 through Step 7 twice: once to add the PUBnumber element, and once to
add the LOCnumber element.

Click Save

Stylus Studio User Guide

Getting Started with Stylus Studio

The definition of the PublicationType complexType is now complete and should look like
Figure 72:

Figure 72. PublicationType complexType Fully Defined

Defining Elements of the Sample complexType in the Diagram

View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 81.
In the final step of defining bookstoreDiagram.xsd, you define elements that are of the
PublicationType complexTypes you defined earlier book, magazine, and newsletter
elements.
To define the book, magazine, and newsletter elements in the sample XML Schema:

Right-click the schema node in the diagram.

In the shortcut menu that appears, select Add > Element.

Stylus Studio User Guide

Defining an XML Schema Using the Diagram Tab Getting Started

Stylus Studio displays a node for the new element in the XML Schema diagram pane.
The properties for the new element appear in the Properties window.
3.

Type book as the name of the new element and press Enter.

In the Properties window, click the Data Type field. Stylus Studio displays a dropdown list of built-in types plus any types you have defined.

Click PublicationType.

Repeat Step 1 through Step 5 twice: once to add the magazine element, and once to
add the newsletter element.

Click Save
.
The bookstoreDiagram.xsd document is now complete.

Select XMLSchema > Validate Document from the menu to validate the XML Schema
document you created.
The validation message appears in the Output window, as shown in Figure 73.

Figure 73. Validation of bookstoreDiagram.xsd

Stylus Studio User Guide

Getting Started with Stylus Studio

Opening Files in Stylus Studio

This section describes the types of files Stylus Studio recognizes, how to add new file
types to Stylus Studio, and how to open files using the Stylus Studio File Explorer and
other methods. This section covers the following topics:

Types of Files Recognized by Stylus Studio on page 92

Using the File Explorer on page 94

Dragging and Dropping Files in the Stylus Studio on page 97

Other Ways to Open Files in Stylus Studio on page 98

Adding File Types to Stylus Studio on page 99

Tip You can set an option so that when you open Stylus Studio, Stylus Studio automatically

opens any files that were open the last time you closed Stylus Studio. See Options Application Settings on page 1321.

Types of Files Recognized by Stylus Studio

Stylus Studio recognizes over ten types of files by default. Each file is associated with a
Stylus Studio module, or editor, appropriate for its type, as shown in the following table.
Table 2. File Extensions and Associated Modules

File Name Extension

Stylus Studio Module

.conv

Custom XML Conversion Editor

.dff

XML Diff Viewer

.dtd

DTD Schema Editor

.java

Java Debugger

.pipeline

XML Pipline

.prj

Project framework

.report

XML Publisher

.sef

EDI to XML Conversion

.wscc, .wsc

Web Service Call Composer

.wsdl

Web Service Description Language

Stylus Studio User Guide

Opening Files in Stylus Studio

Table 2. File Extensions and Associated Modules
File Name Extension

Stylus Studio Module

.xml

XML Editor

.xquery

XQuery Editor

.xsd

XML Schema Editor

.xsl, .xslt

XSLT Stylesheet Editor

You can add your own file types to this list, specify the module you want them opened in,
and, optionally, specify Stylus Studio as the default application for viewing and editing
files of that type. See Adding File Types to Stylus Studio on page 99.

Opening Unknown File Types

When you try to open a file of a type that is not recognized by Stylus Studio, Stylus Studio
displays the Choose Module for dialog box, which allows you to specify the module or
editor you want to use to open the file.

Figure 74. Choose Module Dialog Box

When you respond to this dialog box, you can optionally indicate whether you want all
files of that type to be associated with the Stylus Studio module you select in the future.
File types you associate with a Stylus Studio module are added to the File Types page of
the Options dialog box. You can remove or change the module association at any time.
See Adding File Types to Stylus Studio on page 99 for more information.

Opening Files Stored on Third-Party File Systems

Stylus Studio provides access XML documents stored on third-party file systems like
Raining Data TigerLogic XML Data Management Server (TigerLogic XDMS).
Stylus Studio User Guide

Getting Started with Stylus Studio

See Integrating with Third-Party File Systems on page 1163 for more information.

Modifications to Open Files

If a file that is open in Stylus Studio is modified (changed, and saved) outside Stylus
Studio, Stylus Studio alerts you that the file has been changed and gives you the chance
to reload it.

Using the File Explorer

The Stylus Studio File Explorer is a dockable window that provides easy access to any
file system accessible from the computer on which you are running Stylus Studio. You
can use the File Explorer to quickly add files to Stylus Studio and open files in Stylus
Studio, as well as to perform typical file management tasks (like renaming and deleting
files, for example).

Figure 75. Stylus Studio File Explorer

By default, the File Explorer window appears on the right side of the Stylus Studio
window, but you can drag it anywhere on your desktop. You can close/open the File
Explorer window from the View menu.

Stylus Studio User Guide

Opening Files in Stylus Studio

How to Use the File Explorer to Open Files

There are several ways to open files using the File Explorer:

Double-click the file

Right-click the file and select Open or Open With from the shortcut menu
Open With allows you to select the module you want to use to open the file.

Tip

Drag and drop the file. See Dragging and Dropping Files in the Stylus Studio on
page 97.

When you open a file by double-clicking or using the Open shortcut menu, Stylus Studio
opens the file in the module associated with the file type (the XML Editor for .xml files,
for example). If the file type is not currently registered with Stylus Studio, you can register
the file at this time using the Choose Module for dialog box. See Types of Files
Recognized by Stylus Studio on page 92 for more information about file type/module
associations in Stylus Studio.

Other Features of the File Explorer

The tool bar in the File Explorer window has several features that can help you navigate
the file systems associated with your computer and work with individual documents.

Figure 76. File Explorer Tool Bar

Stylus Studio User Guide

Getting Started with Stylus Studio

These features are summarized in the following table.

Table 3. File Explorer Tools
Tool
New Folder
Read Document
Structure

Description
Creates a new folder as a child of the folder with current focus. The
default folder name is New Folder.
Displays the structure of XML documents in tree form. You can
drag exposed nodes onto the document tab area to open the
document associated with that node. If you drag a node into an
existing XQuery or XSLT document, Stylus Studio creates the
document function with the XPath expression for that node. For
example, if you drag the title element from books.xml into an
XQuery document, Stylus Studio builds the following function:
doc("file:///c:/Program Files/Stylus Studio X14 XML
Enterprise Suite/examples/simpleMappings/
books.xml")/books/book/title

Refresh

Refreshes the File Explorer window.

Reset Filters

Resets the File Explorer filter from its current content to the
wildcard (*.*).

Stylus File Types

Changes the File Explorer filter to display only file types associated
with Stylus Studio: .xml, .xsd, .dtd, .java, .conv, and others.

Working with the File Explorer Filter

By default, the File Explorer window uses a wildcard filter to display all file types (*.*).

Figure 77. File Explorer Filter

You can

Type your own filter (*.txt, for example). If you want to use multiple filters, separate
them with a semicolon (*.txt; *.html, for example).

Use the Stylus File Types

button to change the filter to display only file types
associated with Stylus Studio (.xml, .xsd, .dtd, .java, .conv, and others)
Stylus Studio remembers the filters you create and adds them to the drop-down list.
96

Stylus Studio User Guide

Opening Files in Stylus Studio

Dragging and Dropping Files in the Stylus Studio

You can open a file in Stylus Studio by dragging the file from the File Explorer (or other
file system browsers, like Windows Explorer) and dropping it inside Stylus Studio. How
Stylus Studio behaves depends on where you drop the file, as summarized in Table 4.
Table 4. How Stylus Studio Handles Dragged-and-Dropped Files
If You Drop the File Here

Stylus Studio Does This

On the document editor area

(when no documents are open)

Opens the document editor associated with the type of file

you selected. See Types of Files Recognized by Stylus
Studio on page 92. If the file type is not currently
registered with Stylus Studio, you can register the file at
this time using the Choose Module for dialog box. See
Opening Unknown File Types on page 93.

On the document editor tab area

Opens the document editor associated with the type of file

In an active document

Adds the files URL to the end of the document.

On another file in the File

Explorer

Performs the operation associated with the target file and

opens the resulting document in its own editor. For
example, you might use this operation to convert a text file
to XML by dropping the .txt file on a converter file
(.conv).

In a project in the Project

window

Adds the file to the project. If the file type is not currently
registered with Stylus Studio, you can register the file at
this time using the Choose Module for dialog box. See
Opening Unknown File Types on page 93.

Stylus Studio User Guide

Getting Started with Stylus Studio

Other Ways to Open Files in Stylus Studio

In addition to the File Explorer and drag-and-drop, you can also open files in Stylus
Studio from the following places:

The Open dialog box (displayed when you select File > Open from the menu, for
example). By default, Stylus Studio opens the file in the editor associated with files
of the type you select (see Types of Files Recognized by Stylus Studio on page 92).
If you want, you can choose a different editor you might want to open an XSLT
stylesheet in the XML Editor, for example when opening files from the Open dialog
box.
To specify a different module, click the down arrow to the right of the Open button
and select the module you want to use from the drop-down list as shown in Figure 78.

Figure 78. Choose the Module to Use When Opening a File

Project window either double-click the file, or select Open or Open With from the
files shortcut menu.
Other file system browsers (like Windows Explorer, for example) for files
recognized by Stylus Studio, just double-click the file. See Opening Unknown File
Types on page 93.

Stylus Studio User Guide

Opening Files in Stylus Studio

Adding File Types to Stylus Studio

You use the procedure described in this section to associate a file type (.txt, for example)
with a specific Stylus Studio module or editor. Once you do this, any time you open a file
of that type from within Stylus Studio (using the File Explorer, for example), that file is
opened in the editor you specify.
You can optionally specify that you want to use Stylus Studio as the default editor for files
of this type, regardless of where the file is opened (from a file browser like Total
Commander, for example).
Note You do not need to specify the usual extensions, such as xml, xsl, and java. Use the

procedure described in this section for file name extensions peculiar to your application
or environment.
To add a file type to Stylus Studio:
1.

From the Stylus Studio menu bar, select Tools > Options.
Stylus Studio displays the Options dialog box.

Under General, click File Types.

The File Types page appears.

Figure 79. Associating File Types with Stylus Studio Editors

Stylus Studio User Guide

Getting Started with Stylus Studio

To add a new file type/module association, click the Add

Alternative: Double-click the Type field.

button.

Type the new extension, including the period, and press Enter.
Stylus Studio adds the file type and selects a default module in the Module field.

Optionally, select a different module using the drop-down list in the Module field.

If you want to always use Stylus Studio to open files of this type, change the value in
the Open with Stylus Studio field to True.

To add another file type, repeat Step 3 through Step 6.

When you are done, click OK.

Deleting File Types

To delete a file type:
1.

Click the file type you want to delete.

Click the Delete

Click OK.

button.

Working with Projects

A project in Stylus Studio is a group of files related to a given XML application. A project
might include XML, XML Schema, and XQuery files, as well as OASIS catalogs, for
example. A project can contain subprojects, and subprojects can contain subprojects. The
Stylus Studio project framework allows you to name projects (project files are saved with
a .prj extension), and it provides several tools for managing the projects you create.
Projects are simply a convenience for organizing files a file does not have to belong to
a project in order for you to edit it in Stylus Studio. For example, Stylus Studio includes
all sample application files in the examples project. You can find the examples.prj file in
the examples directory of your Stylus Studio installation directory.
This section discusses the following topics:

Displaying the Project Window on page 101

Creating Projects and Subprojects on page 103

Saving Projects on page 103

100

Stylus Studio User Guide

Working with Projects

Opening Projects on page 103

Adding Files to Projects on page 104
Copying Projects on page 105
Rearranging the Files in a Project on page 106
Removing Files from Projects on page 106
Closing and Deleting Projects on page 106
Setting a Project Classpath on page 107
Using Stylus Studio with Source Control Applications on page 109

Displaying the Project Window

When you open Stylus Studio for the first time, Stylus Studio displays the Project window
with the examples project. (The File Explorer window is displayed on the right.)

Figure 80. Project Window with Default Project DIsplayed

There are several ways to toggle the display of the Project window. You might want to
close the Project window in order to gain more space in the editor you are working with,
for example.

Stylus Studio User Guide

101

Getting Started with Stylus Studio

To toggle Project window display:

From the Stylus Studio menu, select View > Project Window.
In the Stylus Studio tool bar, click Toggle Project Window
.

Tip The Project window is dockable you can move it anywhere on your desktop.

To hide Project window:

Click the X in the upper right corner of the Project window.

Tip When you hide the Project window, any open files remain open.

Displaying Path Names

You can control whether the Project window displays absolute or relative path names for
files in projects. The default display is relative names.
To toggle the way path names appear:
1.

Display the Project window.

In the Project window, right-click to display the pop-up menu.

Click Show Full URL Info.

Other Documents
Stylus Studio displays documents that are not associated with a project in the Other
Documents folder, which appears after the last folder or document in the currently
displayed project. In addition, when you remove a file from a project, it is placed in the
Other Documents folder.

Figure 81. Other Documents Folder

You can add these documents to a project at any time. See Adding Files to Projects on
page 104.
102

Stylus Studio User Guide

Working with Projects

Creating Projects and Subprojects

You can create projects and organize any project into multiple levels of subprojects. You
can add files to projects and save the project under a name you specify.
To create a project, select Project > New Project from the menu:

Stylus Studio displays the new project in the Project window. The Project window
displays information for only one project at a time.
To create a subproject:
1.

Right-click the project name, and click New Project Folder in the pop-up menu.
Stylus Studio displays a default subproject folder name (NewFolder1, for example).

Type a new subproject name.

Press Enter.

There are several ways to add files to your projects and subprojects. See Adding Files to
Projects on page 104.

Saving Projects
To save a project, select Project > Save Project.

The first time you save a project, Stylus Studio prompts you to specify a name for your
project. Stylus Studio appends .prj to the name you specify. It does not matter whether
or not you specify the .prj extension. Stylus Studio does not allow a project to have any
other file name extension.
When you save a project, references to the files part of the project are saved relative to the
path of the project file. This allows you to move or share projects easily.

Opening Projects
You can have only one project open at one time. If you have a project open and you open
a second project, Stylus Studio closes the first project and then opens the second project.
If the Project window is not visible when you open a project, Stylus Studio automatically
displays the Project window.

Stylus Studio User Guide

103

Getting Started with Stylus Studio

To open a project:
1.

From the Stylus Studio menu bar, select Project > Open Project.

Navigate to and select your project file. For example, you can open examples.prj in
the examples directory of your Stylus Studio installation directory. The examples
project contains the files for all Stylus Studio sample applications.

Click the Open button.

Recently Opened Projects

Projects that were recently opened are displayed at the bottom of the Project drop-down
menu. Click the project you want to open.

Figure 82. Recently Opened Projects Are Listed on the Project Menu

Adding Files to Projects

The easiest way to add a file to a Stylus Studio project is to drag the file from the File
Explorer or another file browser (like Total Commander, for example) into the desired
project folder. You can drag-and-drop multiple files at a time.
If the file type is unknown to Stylus Studio, the Choose Module for dialog box appears,
which allows you to associate the file with a Stylus Studio module or editor. See Opening
Unknown File Types on page 93 for more information.

104

Stylus Studio User Guide

Working with Projects

Other Ways to Add Files to Projects

The following procedures describe other ways to add files to a project. Note that these
procedures vary based on whether or not the file is already open in Stylus Studio.
When Files are Open in Stylus Studio
To add an open file to a project:
1.

Open the project to which you want to add the file.

Click the window (the Web Service Call Composer, for example) that contains the file
you want to add.

In the Stylus Studio tool bar, click Add Document to Project

.
Alternative: Select Project > Add Document from the Stylus Studio menu bar.

When Files are Closed

To add a closed file to a project:
1.

Open the project to which you want to add the file.

In the Stylus Studio tool bar, click Add File to Project

.
Alternative: Select Project > Add File from the Stylus Studio menu bar.
The Open dialog box appears.

Navigate to the file you want to add and click the Open button.

Copying Projects
To copy a project:
1.

Open the project you want to copy.

From the Stylus Studio menu bar, select Project > Save Project As.
The Save As dialog box appears.

Navigate to the location for the project copy.

In the URL: field, type the name of the new project.

Click the Save button.

Stylus Studio User Guide

105

Getting Started with Stylus Studio

Rearranging the Files in a Project

The order in which files are displayed in the Project window has no effect on the project.
You might want to place related files near each other, or place more frequently used
project files toward the top of the project tree.
To rearrange files in a project:
1.

If the Project window is not visible, click Toggle Project Window

Studio tool bar.

In the Project window, click the file you want to move.

Drag it to its new location.

in the Stylus

Removing Files from Projects

When you remove a file from a project, it is added to the Other Documents folder in the
Project window.
To remove a file from a project:
1.

If the Project window is not visible, click Toggle Project Window

Studio tool bar.

in the Stylus

In the Project window, click the path for the file you want to remove.

From the Stylus Studio menu bar, select Project > Remove File from Project.
Alternative: Press the Delete key.

Closing and Deleting Projects

Closing
To close a project, open another project or create a new project.
Tip Toggling or closing the Project window does not close the project.

106

Stylus Studio User Guide

Working with Projects

Deleting
To delete a project, remove its .prj file from the file system.

Setting a Project Classpath

You can set a classpath at the project level. When Stylus Studio compiles or runs Java
code, it always checks the project for a locally defined classpath.

Specifying Multiple Classpaths

You use the Project Classpath dialog box to specify one or more classpaths for a project.
If multiple classpaths have been defined, Stylus Studio searches them in the order in
which they are listed in the Project Classpath dialog box. You can use the up and down
arrows at the top of this dialog box to change the classpath order.

Figure 83. Use Arrow Buttons to Change the Order of Classpaths

How to Set a Project Classpath

To set a classpath for a project:
1.

Open the Project Window if it is not already displayed.

Right-click the project node.

The project shortcut menu appears.
Alternative: Select Project > Set Classpath from the Stylus Studio menu.

Select Set Project Classpath.

Stylus Studio User Guide

107

Getting Started with Stylus Studio

The Project Classpath dialog box appears.

Figure 84. Project Classpath Dialog Box

Click the browse folders (

) button.
A new entry field appears in the Locations list box. Two buttons appear to the right
of the entry field.

To add a JAR file to the classpath, click the browse jar files button (
Stylus Studio displays the Browse for Jar Files dialog box.

Figure 85. Browse for Jar Files Dialog Box

To add a folder to the classpath, click the browse folders button (

108

Stylus Studio User Guide

Working with Projects

Stylus Studio displays the Browse for Folder dialog box.

Figure 86. Browse for Folder Dialog Box

When you have located the JAR file or folder you want to add to the classpath, click
OK.

Optionally, add other JAR files or folders to the classpath by repeating Step 5 and
Step 6.

Using Stylus Studio with Source Control Applications

Stylus Studio supports the Microsoft Source Code Control Interface, allowing you to use
Stylus Studio with any source code control system that supports the same interface used
by Microsoft Visual Studio or Microsoft Visual Studio .NET.
Stylus Studios source control support allows you to

Add a file to source control

Remove a file from source control

Get the latest version of a source-controlled file

Check out a file

Check in a file

Un-check out a file

Show the source control history of a file

Show differences between versions of a file

Stylus Studio User Guide

109

Getting Started with Stylus Studio

In this section
This section covers the following topics:

Tested Source Control Applications on page 110

Prerequisites on page 110

Using Stylus Studio with Microsoft Visual SourceSafe on page 111

Using Stylus Studio with ClearCase on page 113

Using Stylus Studio with Zeus CVS on page 116

Specifying Advanced Source Control Properties on page 117

Tested Source Control Applications

Integration with the following source control applications has been tested:

Microsoft Visual SourceSafe

Clearcase/Attache

CVS

Prerequisites
To use Stylus Studios source control features, you must have already installed the client
software for your source control application, as shown in Table 5.
Table 5. Working with Source Control Clients
When Data Is In

You Need to Install

SourceSafe repository

SourceSafe client or SourceOffSite

ClearCase

Attache client

CVS

Zeus-CVS product

In addition, files must belong to a Stylus Studio project before you can use them with a
source control application.

Recursive Selection
When you build a project using files from a source control application, Stylus Studio gives
you the option of recursively importing all projects that are subordinate to the project
folder you select. This option, Recursively import all subprojects, appears on the Build
Project from SCC dialog box, which appears when you start the New Project Wizard.
110

Stylus Studio User Guide

Working with Projects

Selecting the Recursively import all subprojects option has the effect of selecting all the
siblings of the selected file or directory, as well as any descendants of the selected item
and its siblings. Stylus Studio creates a project that contains all files that Stylus Studio can
open (for example, .xml, xslt, and .xsd files) and that are in the directory hierarchy of the
file or directory you select.
For example, suppose you check Recursively import all subprojects, and you select
c:\work\myproject\documentation.xml. Stylus Studio creates a project that contains all
Stylus Studio-editable files in c:\work\myproject and its subdirectories.
If you do not check Recursively import all subprojects, only the file you select is added
to the new Stylus Studio project you create. You cannot select a directory if you do not
select this option.

Using Stylus Studio with Microsoft Visual SourceSafe

To use Stylus Studio to operate on files that are under SourceSafe source control:
1.

From the Stylus Studio menu bar, select Project > New Project Wizard.
The Project Wizards dialog box appears.

Figure 87. Project Wizards Dialog Box

Stylus Studio User Guide

111

Getting Started with Stylus Studio

Click Project from SCC, and click the OK button.

The Build Project From SCC dialog box appears.

Figure 88. Build Project From SCC Dialog Box

Select Microsoft Visual Sourcesafe from the Provider to use drop-down list.

If you want to use Stylus Studio to access more than one file in a directory hierarchy,
click the check box for Recursively import all subprojects. See Recursive
Selection on page 110 if you need help with this step.
Depending on your installation, you might need to specify other properties. See
Specifying Advanced Source Control Properties on page 117.

Click the OK button.

The Visual SourceSafe Login dialog box appears:

Figure 89. Visual SourceSafe Login Dialog Box

112

Specify the username and password; optionally, use the Browse... button to access a
database other than the default database displayed in the Database field.

Click OK.

Stylus Studio User Guide

Working with Projects

The Create Local Project from SourceSafe dialog box appears.

Figure 90. Create Local Project from SourceSafe Dialog Box

Select the folder in which you want to create the new project.

Click OK.
The project is created in Stylus Studio. A message displays the names of any files that
were not added to the project because their extensions are not associated with a Stylus
Studio editor.

Using Stylus Studio with ClearCase

To use Stylus Studio to operate on files that are under ClearCase source control:
1.

Use Attache to copy the files you want to work on from a ClearCase view to the local
file system.
If you move these files from this directory after you create the project, you must
specify the new directory that contains the files in the Local Project Path field of the
Source Control Properties dialog box. To access this dialog box, select
SourceControl > Source Control Properties from the Stylus Studio menu bar.

Note

From the Stylus Studio menu bar, select Project > New Project Wizard.

Stylus Studio User Guide

113

Getting Started with Stylus Studio

The Project Wizards dialog box appears.

Figure 91. Project Wizards Dialog Box

Click Project from SCC, and click the OK button.

The Build Project From SCC dialog box appears.

Figure 92. Build Project From SCC Dialog Box

114

Select Clearcase from the Provider to use drop-down list.

Click the OK button.

Stylus Studio User Guide

Working with Projects

The Browse for Folder dialog box appears.

Figure 93. Browse for Folder Dialog Box

Navigate to and select the file or directory you want to operate on, or one of the files
or directories in the topmost level of the directory hierarchy that you want to access,
and click the OK button.
Stylus Studio creates a new project that contains the file you selected, or all files that
are editable by Stylus Studio and that were in the directory hierarchy of the file you
selected. The default name of the project is Projectn. To rename the project, select
Project > Save Project As from the Stylus Studio menu bar.

Adding Files After the Project is Created

After you create the project, you can add additional ClearCase files to it. If the file is
already in ClearCase, it must be a sibling of the original file you selected, or it must be a
descendant of one of its siblings. If the file you want to add is not in the directory
hierarchy of the original file, you must create a new Stylus Studio project and specify a
directory in the source control hierarchy that contains all the files you want to be in your
Stylus Studio project.
If you want to add a file that is not already in ClearCase, open the file in Stylus Studio and
then click Add To Source Control
in the Stylus Studio tool bar.

Stylus Studio User Guide

115

Getting Started with Stylus Studio

Using Stylus Studio with Zeus CVS

Stylus Studio supports the latest version of the Zeus CVS Provider, and with some
additional configuration needed in the SourceControl > Properties dialog box.
To use Stylus Studio to operate on files that are under Zeus CVS source control:
1.

From the Stylus Studio menu bar, select Project > New Project Wizard.
The Project Wizards dialog box appears.

Click Project from SCC, and click the OK button.

The Build Project From SCC dialog box appears.

Select Zeus SCC-CVS from the Provider to use drop-down list.

Click the check box for Recursively import all subprojects.

Click Advanced. Several new fields appear.

In the User Name field, type the user name you want to use to log in to the CVS server.

In the Project Name field, type the name of a module in the source control hierarchy.
This should be the name of a directory that contains all files that you want to open in
Stylus Studio.

In the Auxiliary Path field, type the contents of the CVSROOT environment variable that
you use to access the CVS server.
For example, suppose you are required to enter the following commands in a DOS
console or UNIX shell:
cvs.exe -d:pserver:[email protected]:/cvsroot/projectname login
Password: *****
cvs.exe -d:pserver:[email protected]:/cvsroot/projectname co module

The value you should enter in the Auxiliary Path field would be:
:pserver:[email protected]:/cvsroot/projectname

116

In the Working Dir field, type the name of a local directory.

Stylus Studio User Guide

Working with Projects

10.

Click the OK button.

Stylus Studio downloads the selected files and places them in the directory you
specified in the Working Dir field. If you move these files from this directory, you
must specify the new directory that contains the files in the Local Project Path field
of the Source Control Properties dialog box. To open this dialog box, select
SourceControl > Source Control Properties from the Stylus Studio menu bar.

All files that can be opened in Stylus Studio are now in the new Stylus Studio project. The
default name of the project is Projectn. To rename the project, select File > Project > Save
Project As from the Stylus Studio menu bar.
The cvs.exe file must be in your PATH environment variable.

Note

Specifying Advanced Source Control Properties

The Advanced button in the Build Project From SCC dialog box displays several
additional fields.

Figure 94. Advanced Source Control Settings

User Name is the name of the source control user. Stylus Studio uses this name to

establish a connection with the source control server.

Project Name is the name of the source control repository you want to access. The
syntax of the project name depends on the source control provider you want to
connect with. For example, SourceSafe uses $/Name/Name, ClearCase uses the name
of the view, and CVS uses the name of the module. Some source control providers
change this description to something more suitable to their model. For example,
ClearCase changes it to ClearCase Attache.

Stylus Studio User Guide

117

Getting Started with Stylus Studio

Auxiliary Path contains source control provider-specific information. This field

allows you to enter any other information required to find your source control server.
For example, if you are using SourceSafe, you would specify the directory of the
SourceSafe client here. If you are using CVS, you would specify the contents of the
CVSROOT environment variable.
Working Dir is the local directory into which you copied the files under source control
that you want to access. It is the local counterpart for the source control repository.
For example, suppose you copied the contents of the SourceSafe repository
$/Company/OneProject to the local directory c:\work\myproject. Your local files
would map to the source control hierarchy as shown in Table 6:

Table 6. Local/Repository File Mappings

Local File

Repository File

c:\work\myproject\documentation.xml

$/Company/OneProject/documentation.xml

c:\work\myproject\subdir\root.java

$/Company/OneProject/subdir/root.java

c:\work\anotherproject\root.java

$/Company/anotherproject/root.java

Customizing Tool Bars

Stylus Studio allows you to customize the appearance, location, and content of tool bars,
and even to create tool bars of your own. This section covers the following topics:

Tool Bar Groups on page 118

Showing/Hiding Tool Bar Groups on page 119

Changing Tool Bar Appearance on page 120

Tool Bar Groups

Tool bars are organized by functional group within Stylus Studio (Default, Edit, Source
Control, and so on). Customizations available for these groups include

Show/hide

Look, feel, and size

Group position
Tip Tool bars are docking windows you can drag them anywhere on your desktop.

118

Stylus Studio User Guide

Customizing Tool Bars

You control all these customizations from the Toolbars tab of the Customize dialog box.

Figure 95. Toolbars Tab of Customize Dialog Box

To display the Customize dialog box, select Tools > Customize from the menu.

Showing/Hiding Tool Bar Groups

Tool bar groups are displayed by default. Use this procedure to hide/re-display them.
Tip Consider maximizing Stylus Studio on your desktop in order to view as much of the tool

bar as possible when making changes.

To hide/show a toolbar group:
1.

Display the Customize dialog box (Tools > Customize).

In the Toolbars group box, deselect the check box of the group you want to hide.
The tool bar is removed from the Stylus Studio window.

To re-display a hidden tool bar group, follow Step 1 and Step 2 and reselect the check
box,

Stylus Studio User Guide

119

Getting Started with Stylus Studio

Changing Tool Bar Appearance

Changes you can make to the tool bars appearance include

Whether or not to show tooltips when the mouse pointer is placed over a tool bar
button

Whether tool bar buttons are rendered in a size larger than the default
Note Appearance settings affect all tool bars. You cannot control the appearance of individual

tool bar groups.

To modify toolbar appearance:
1.

Display the Customize dialog box (Tools > Customize).

Click Show Tooltips to toggle the display of tooltips when the pointer is placed over
a tool bar button.

Click Large Buttons to toggle the size of the tool bar buttons.

Optionally, click the Reset button to restore default settings.

Click the OK button.

Specifying Stylus Studio Options

Stylus Studio allows you to set a variety of options for Stylus Studio modules, and it
provides the ability to define custom tools to run different editors and processors. This
section covers the following topics:

Setting Module Options on page 120

Registering Custom Tools on page 122

Setting Module Options

Stylus Studio allows you to set a variety of options for the Stylus Studio modules.
To change module options:

120

From the Stylus Studio menu bar, select Tools > Options.

In the Options dialog box that appears, expand Module Settings to display a list of
choices.

Stylus Studio User Guide

Specifying Stylus Studio Options

XML Diff
You use the Engine and Presentation pages to define settings used by the XML Diff tool.
See Diffing Folders and XML Documents on page 176 for more information.

XML Editor
Click XML Settings to specify the following:

Refresh interval for Sense:X

Number of errors after which you want Stylus Studio to stop validation, and whether
or not you want Stylus Studio to display a message when validation is complete
Click Custom Validation Engines to specify an alternate validation engine. See Custom
XML Validation Engines on page 1170 for more information.

XSLT Editor
Module settings for the XSLT Editor let you specify external XSLT processors, settings
used by the Mapper tab, and general editor behavior.
Click External XSLT to specify default values for external XSLT processors. Note that
Stylus Studios back-mapping and debugging features are not supported for all XSLT
processors. The XSLT processors that support back-mapping and debugging are
identified on the Processor tab of the Scenario Properties dialog box.
In a scenario, you can specify that you want to use an external XSLT processor. If you use
a particular XSLT processor frequently, specify default values here. Then, in the scenario
properties, you just need to specify which external XSLT processor you want to use. If
you specify default values and you then specify different values in a scenarios properties,
the scenario properties override the defaults. You can specify the following external XSLT
options:

Default custom processor command line

Default additional path for custom processor

Default additional classpath for custom processor

Click Mapper to specify how xsl:for-each instructions should be rendered on the Mapper
canvas, and to specify element creation for unlinked nodes. See Mapping Source and
Target Document Nodes on page 526 for more information on using the XSLT Mapper.

Stylus Studio User Guide

121

Getting Started with Stylus Studio

Click XSLT Settings to specify the following:

Whether Stylus Studio displays the Scenario Properties dialog box when you create
a new stylesheet

Whether Stylus Studio saves scenario meta information in stylesheets

Whether Stylus Studio detects infinite loops

Maximum recursion level

Allocated stack size

Java
To modify Java settings, see Configuring Java Components on page 133.

Registering Custom Tools

Stylus Studio allows you to register custom tools to run alternative editors, processors,
preprocessors, or postprocessors. For example, you can register a custom tool that
configures Internet Explorer to display the document you are working on.
After you register a custom tool, Stylus Studio adds an entry to its Tools menu select
Tools and then your tool. The order in which the tool names appear in the Custom Tools
options page is the order in which the tool names appear in the Stylus Studio Tools menu.
You can register custom tools from within Stylus Studio or from the command line.

Using Stylus Studio

To register a custom tool in Stylus Studio:

122

From the Stylus Studio menu bar, select Tools > Options.
Stylus Studio displays the Options dialog box.

Click Custom Tools to display the Custom Tools page.

Stylus Studio User Guide

Specifying Stylus Studio Options

In the Custom Tools page, click Define New Tool

.
Stylus Studio displays an entry field for the tool name.

Figure 96. Defining a Custom Tool

Enter the name as you want it to appear in the Stylus Studio Tools menu.

In the Command field, specify or select the absolute path for the command that runs
your tool. This must be a .exe, .bat, or .cmd file.

In the Arguments field, specify any arguments your tool requires. You can click
to display a drop-down list that includes File Path, File Dir, File Name, File Extension,
and Classpath.

In the Initial Directory field, type the absolute path for the directory that contains any
files or directories needed by your custom tool.

In the Path field, type any paths that need to be defined and that are not already
defined in your PATH environment variable.

If you want Stylus Studio to prompt for arguments before it runs your tool, click
Prompt for Arguments.

10.

If you want Stylus Studio to display output from your custom tool in its Output
Window, select Use Output Window.

Stylus Studio User Guide

123

Getting Started with Stylus Studio

11.

If you want Stylus Studio to save all open documents before running this tool, select
Save All documents before execution.

12.

Click the OK button.

Using the Command Line

To register a custom tool using the command line:

The format for the command line is:

struzzo /newCustomTool "Tool n:=Tooln; Args= value; Command=value;
Description=value; Initial Directory=value; Path=value; PromptArgs=value;
RedirectOutput=value; DoSaveAll=value"

Example:
struzzo /newCustomTool "Tool 0:=Tool 0;Description=Avalon Uploader;
Command=AVRPTLDR.exe;Args= ${FilePath}"

Arguments for the newCustomTool function are described in the following table:
Table 7. Properties for Registering Custom Tools
Name

Description

Tool n:

The full syntax for this property is Tool n:=Tool n, where n is some
number. The number, n, specifies the order in the Tools menu in
which the custom tool you are registering appears. You might use 0
for the first tool you register, 1 for the second, and so on. Valid
values are numbers starting with 0.
The first part (Tools n:=) is used to create a key in the Windows
registry. The second part (Tools n) is used as a prefix for other
entries in the registry key that correspond to this tool. The two
values should always be the same (Tools 1:=Tools 1, for example).

124

Args

Command line arguments for the tool you are registering.

Command

The absolute path for the command that runs your tool. This must be
a .exe, .bat, or .cmd file.

Description

The tool name as you want it to appear on the Stylus Studio Tools
menu.

Stylus Studio User Guide

Defining Keyboard Shortcuts

Table 7. Properties for Registering Custom Tools
Name

Description

Initial Directory

The working directory for the tool. This is the absolute path for the
directory that contains any files or directories needed by your
custom tool.

Path

Any paths that need to be defined and that are not already defined in
your PATH environment variable.

PromptArgs

Whether you want Stylus Studio to display the Parameters dialog

box each time this tool is run. Valid values are 0 (do not display the
Parameters dialog box) and 1 (display the Parameters dialog
box).

RedirectOutput

Whether you want the output directed to the Stylus Studio Output
window. Valid values are 0 (do not redirect) and 1 (redirect).

DoSaveAll

Whether you want Stylus Studio to save all open documents before
running this tool. Valid values are 0 (do not save) and 1 (save all).

Defining Keyboard Shortcuts

You can define a keyboard shortcut for many of the tasks you perform with Stylus Studio.
If you find that you repeatedly perform the same action, define a shortcut to speed your
work. You can use a keyboard shortcut right after you define it.

How to Define a Keyboard Shortcut

To define a keyboard shortcut for a Stylus Studio task:

From the Stylus Studio menu bar, select Tools > Keyboard.

Stylus Studio User Guide

125

Getting Started with Stylus Studio

The Shortcut Keys dialog box appears.

Figure 97. Defining Shortcut Keys

Tip

126

In the Select a macro: field, select the macro for which you want to define a shortcut.
When you select a macro, Stylus Studio displays a description of what that macro
does.

Stylus Studio User Guide

Defining Keyboard Shortcuts

Click Create Shortcut.

The Assign Shortcut dialog box appears.

Figure 98. Assigning a Shortcut Key

Press the key or keys that you want to be the shortcut. For example, Ctrl+E, F7, Alt+P.
The Assign Shortcut dialog box displays a message indicating whether or not that
key combination is currently in use.

If the shortcut key is not already in use, click the OK button. Otherwise, try another
shortcut key.
Stylus Studio closes the Assign Shortcut dialog box.

Click OK in the Shortcut Keys dialog box.

Deleting a Keyboard Shortcut

To delete a shortcut:

From the Stylus Studio menu bar, select Tools > Keyboard. The Shortcut Keys dialog
box appears.

In the Select a macro: field, select the macro you want to delete a shortcut for.

In the Assigned shortcuts field, click the shortcut you want to remove.

Click Remove.

Click OK in the Shortcut Keys dialog box.

Stylus Studio User Guide

127

Getting Started with Stylus Studio

Using Stylus Studio from the Command Line

Stylus Studio provides several command line utilities that allow you to perform Stylus
Studio operations, such as starting Stylus Studio and executing XML Diff. Command line
utilities are provided as a convenience for use during development and testing.
Available command line utilities, and where to find more information on them, are
described in the following table.
Table 8. Stylus Studio Command Line Utilities
Utility Name

Description

Where to Find More Information

struzzo

Invokes Stylus Studio

Invoking Stylus Studio from the Command

Line on page 128

StylusDiff

Diffs two XML documents

Running the Diff Tool from the Command

Line on page 204

StylusValidator

Validates XML

Validating XML from the Command Line

on page 129

You can also execute DataDirect XML Converters (componentst that let you convert
non-XML like EDI and CSV to XML, and vice versa) from the command line. To learn
more about the DataDirect XML Converters for Java and .NET, see the DataDirect
XML Converters documentation at
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

Command Line Executables Location

The executables for Stylus Studio command line utilities are located in the \bin directory
where you installed Stylus Studio.

Invoking Stylus Studio from the Command Line

You use the Struzzo utility to invoke Stylus Studio from the command line and open a
particular file. Stylus Studio recognizes the file extension and opens the file in the editor
associated with that file type. If Stylus Studio is already running, the same instance is used
to open the file specified in the file parameter.
You can optionally use the stylesheet
stylesheet or XQuery you specify.

128

or XQuery

parameter to create a scenario with the

Stylus Studio User Guide

Using Stylus Studio from the Command Line

The Struzzo utility takes the following format:

Struzzo file [stylesheet or XQuery]

Table 9 describes the parameters for the Struzzo command.

Table 9. Struzzo Command Line Parameters
Parameter

Description

file

The path of the document you want to open in Stylus Studio. This document
is used as the source document in a scenario when you provide the
stylesheet or XQuery parameter.

[stylesheet or
XQuery]

The path of the stylesheet or XQuery you want to use to create a scenario.

Validating XML from the Command Line

You use the StylusValidator utility to validate XML from the command line.
StylusValidator uses the built-in Stylus Studio XML validator. All output from this
utility goes to stdout.
The StylusValidator utility takes the following format:
StylusValidator [-q] [-noval] [-schema] filename

Table 10 describes the parameters for the StylusValidator command.

Table 10. StylusValidator Command Line Parameters
Parameter

Description

[-q]

Quiet mode errors are not printed to stdout.

[-noval]

Checks only for well-formedness. Does not check for errors.

[-schema file]

Validates the XML document against the XML Schema specified in the file
parameter.

filename

The path of the XML document you want to validate.

Stylus Studio User Guide

129

Getting Started with Stylus Studio

Managing Stylus Studio Performance

Stylus Studio uses the TEMP directory to store temporary files such as the translation in
UNICODE of the current XML or XSLT document. File systems are usually quite fast
when handling files that are in the range of a few hundred megabytes. Stylus Studio
performance should be smooth and quick when the TEMP windows environment variable
points to a location where

There is a minimum of 1 gigabyte of free space.

The host disk is reasonably fast.

Stylus Studio is regularly tested against files that are up to 120 MB. How well your
installation of Stylus Studio can create, open, and manipulate such large files, or even
larger files, depends on

Available physical memory

Dimension of the page file

Current load of the machine

Troubleshooting Performance
Table 11, Performance Symptoms, summarizes performance symptoms you might
experience and where to find information on addressing them.
Table 11. Performance Symptoms
Symptom

See

XML editing is slow

Changing the Schema Refresh Interval on page 130

Checking for Modified Files on page 131

Errors or crashes during XSLT

processing

Changing the Recursion Level or Allocated Stack Size on

page 132

Stylus Studio is slow to start

Automatically Opening the Last Open Files on page 132

Changing the Schema Refresh Interval

As you edit an XML document, Stylus Studio displays a pop-up menu that lists the
elements and element attributes you can create. Stylus Studio retrieves this information
from the documents schema. The frequency with which Stylus Studio retrieves this

130

Stylus Studio User Guide

Managing Stylus Studio Performance

information can affect XML editing performance. The default refresh interval is 10
seconds.
If XML editing performance is slow, increase the refresh interval that Stylus Studio uses
to refresh the schema information.
To change the refresh interval:
1.

From the Stylus Studio menu bar, select Tools > Options.
The Options dialog box appears.

Click Module Settings > XML Editor > XML Settings.

The XML Settings page of the Options dialog box appears.

In the Refresh interval field, type a larger number.

If the schema used by your document is almost never modified, you can safely
increase the interval to as much as 10,000 seconds.

Tip

Click OK.

Checking for Modified Files

When you are working with files that Stylus Studio must open through network
connections that might be slow, you might not want Stylus Studio to automatically check
for modified files. Turning off this option can improve XML editing performance.
To turn off checking for modified files:
1.

From the Stylus Studio menu bar, select Tools > Options.
The Options dialog box appears.

Click Application Settings if it is not already selected.

The Application Settings page of the Options dialog box appears.

If the Automatically check for externally modified files is selected, deselect it.
Alternatively, you can select Disable check on hidden files, which allows Stylus
Studio to skip these files. Hidden files are files that are in the Stylus Studio project or
the Other Documents folder but are not currently open in Stylus Studio.

Click OK.

Stylus Studio User Guide

131

Getting Started with Stylus Studio

Changing the Recursion Level or Allocated Stack Size

If you are getting errors or crashes when you use the internal Stylus Studio XSLT
processor, there are two options you can change to fix this.

The Maximum recursion level is the number of levels Stylus Studio allows you to
recurse on a template invocation.

The Allocated stack size is the amount of memory allocated to the XSLT processing
thread stack.
To change the recursion level or the allocated stack size:
1.

From the Stylus Studio menu bar, select Tools > Options.
The Options dialog box appears.

Click Module Settings > XSLT Editor > XSLT Settings.

The XSLT Settings page of the Options dialog box appears.

Adjust the Maximum recursion level and the Allocated stack size as needed. For
information about how Stylus Studio uses these settings see Options - Module
Settings - XSLT Editor - XSLT Settings on page 1366.

Click OK.

Automatically Opening the Last Open Files

When you start Stylus Studio, it automatically opens any files that were open the last time
you closed it. This feature can affect performance if many files were open when you last
closed Stylus Studio.
If Stylus Studio is taking a long time to start, you can do one of the following:

Close most or all files before you shut down Stylus Studio.

Turn off the option that automatically opens the files that were open the last time you
closed Stylus Studio.
To prevent Stylus Studio from automatically opening documents:

132

From the Stylus Studio menu bar, select Tools > Options.
The Options dialog box appears.

Click Application Settings if it is not already selected.

Stylus Studio User Guide

Configuring Java Components

The Application Settings page of the Options dialog box appears.

If Open last documents automatically when Stylus Studio starts is selected, deselect
it. For information about how Stylus Studio uses this settings see Options Application Settings on page 1321.

Click OK.

Configuring Java Components

Several modules in Stylus Studio are written using Java, and therefore require either Java
runtime or Java compiler components to be installed on your computer. These Java
components, the Java Runtime Environment (JRE) and the Java Development Kit (JDK),
are available from Sun Microsystems and are installed separately from Stylus Studio.
You can install these components either before or after you install Stylus Studio. When
you start Stylus Studio, it attempts to identify the location of the Java runtime libraries and
compiler automatically.
This section identifies the Stylus Studio modules that require Java runtime and Java
compiler components, where you can download these Java components, and how to force
Stylus Studio to detect new or changed Java components.
This section covers the following topics:

Stylus Studio Modules That Require Java

Verifying the Current Java Virtual Machine

Downloading Java Components

Modifying Java Component Settings

Stylus Studio Modules That Require Java

The following modules in Stylus Studio require that Java runtime and/or Java compiler
components are installed on the machine on which you have installed Stylus Studio:

Saxon XSLT and XQuery engines

Built-n Java XSLT processor

FOP

Web Service Call Composer Axis client

DataDirect XML Converters accessed via URL

Sense:X in the Java editor

Stylus Studio User Guide

133

Getting Started with Stylus Studio

Rather than trying to determine in advance which Stylus Studio modules you might use
in your XML application development, consider installing the JDK or JRE on your
machine.

Settings for Java Debugging

See Debugging Java Files on page 561 for more information on this topic.

Verifying the Current Java Virtual Machine

The Java Virtual Machine (JVM) interprets runtime commands and compiler instructions;
it is part of the Java installation. You can check to see the current version of the JVM
installation by selecting Help > About from the Stylus Studio menu:

Figure 99. Verifying the Current JVM Installation

The Java Virtual Machine field displays information about the JVM installed on your
machine.

Downloading Java Components

Java runtime and compiler components are available for download from Sun
Microsystems; they are packaged in the Java 2 Platform Standard Edition (J2SE).
Either of the following versions is compatible with Stylus Studio X14:

J2SE 1.4.2 ( download it here: http://www.java.sun.com/j2se/1.4.2/download.html)

J2SE 5.0 (download it here: http://www.java.sun.com/j2se/1.5.0/download.jsp)

134

Stylus Studio User Guide

Configuring Java Components

Modifying Java Component Settings

Properties for JVM and JDK components are displayed on the Java Virtual Machine page
of the Options dialog box, shown in Figure 100. When you start Stylus Studio, it
automatically detects the Java Virtual Machine (JVM) and compiler components installed
on your machine and sets the properties for these components accordingly.

Figure 100. Reset Java Properties in the Options Dialog Box

Once these properties have values, Stylus Studio uses them until you either

Use the auto detect feature to change them. You might want use auto detect if you
have been using Stylus Studio with the J2SE 1.4.2 and later install the J2SE 5.0, for
example.

Change them manually. You can manually specify that Stylus Studio use a different
jvm.dll or javac.exe, for example.

How Auto Detect Works

The auto detect feature prompts Stylus Studio to fetch the settings from the registry setting
Current Version under the key HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime
Environment to find the version, and then adds the version number to that same location
to get the settings.

Stylus Studio User Guide

135

Getting Started with Stylus Studio

Note that if you manually change your settings to use another local version of the JDK, it
may fail to load properly unless you also point the Current Version setting to match. This
is because the JVM itself might try to load DLLs from the location of the current version
instead of the location you specify.

About JVM Parameters

As a rule, you should never change the default values in the Parameter fields for the JVM
or the External JVM. This option exists to accommodate unusual configurations. In such
situations, Stylus Studio Technical Support might instruct you to change this value.

About JDK Parameters

The -g parameter instructs the compiler to add debugging information to the generated
.class file; it is set by default.

How to Modify Java Component Properties

To modify Java component properties:

136

Start Stylus Studio if it is not already running, and select Tools > Options from the
menu.
The Options dialog box appears.

Select General > Application Settings > Java Virtual Machine.

If you want Stylus Studio to update Java component properties to the latest installed
version on you machine, click the Auto detect button.
Otherwise, make the changes manually.

Click OK.

If you made changes to any JVM properties, you need to restart Stylus Studio for
those changes to take effect.

Stylus Studio User Guide

Chapter 2

Editing and Querying XML

Stylus Studio makes it easy to create, edit, and query XML documents. Depending on the
structure of the data in your XML document, you can choose to work with raw XML text,
a DOM tree diagram, or a grid representation. Any changes you make in one view are
immediately visible in every other view. You can easily create an XML Schema or DTD
based on the content of your XML document if it is not already associated with a schema.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Editor video.
You can see other Stylus Studio video demonstrations here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

Creating XML Documents on page 138

Using Document Wizards to Create XML on page 139

Updating XML Documents on page 141

Using the Text Editor on page 143

Updating DOM Tree Structures on page 157

Using the Grid Tab on page 161

Diffing Folders and XML Documents on page 176

Using Schemas with XML Documents on page 207

Converting XML to Its Canonical Form on page 210

Querying XML Documents Using XPath on page 210

Printing XML Documents on page 210

Saving XML Documents on page 211

Stylus Studio User Guide

137

Editing and Querying XML

Creating XML Documents

You can create XML documents in Stylus Studio manually, using the XML Editor, or
automatically, using document wizards, the Stylus Studio Custom XML Conversions
module, DataDirect XML Converters, and other features.

Using the XML Editor

To create an XML document using the XML Editor, select File > New > XML Document
from the Stylus Studio menu.
Stylus Studio displays a new, untitled document in the XML Editor. The document
contains only the XML declaration:
<?xml version="1.0"?>

The XML Editor provides several views of an XML document, each on its own tab Text,
Tree, Grid, and Schema. See Updating an XML Document Getting Started on page 10
for an overview of these XML editing tools. See Updating XML Documents on
page 141 for more detailed information.

Other Ways to Create XML

You can also create XML using

Document wizards that convert HTML, DTD, and XML Schema to XML. See Using
Document Wizards to Create XML on page 139, later in this section.

DataDirect XML Converters, which convert CSV, fixed-width, EDI, and other flat file
formats to XML. See How XML Converters are Used in Stylus Studio on page 214.

Custom XML conversions that you build using Stylus Studios Custom XML
Conversion module. See Custom XML Conversions on page 221.
DataDirect XML Converters and the Stylus Studio Custom XML Conversions
module are available only in Stylus Studio XML Enterprise Suite.

138

Stylus Studio User Guide

Using Document Wizards to Create XML

Stylus Studio provides several document wizards that automatically create XML
documents from XML Schema, DTD, and HTML. This section describes how to work
with these document wizards; it covers the following topics:

How to Use a Document Wizard on page 139

Creating XML from XML Schema on page 139

Creating XML from DTD on page 140

Creating XML from HTML on page 140

How to Use a Document Wizard

Most document wizards operate in the same general fashion:
1.

Select the document wizard you want to use.

Specify the file from which you want to create an XML document (an HTML file or
an XML Schema, for example).

Specify additional settings that will affect the resulting XML document (the root
node, for example).

Run the wizard.

Converted files are opened as new, untitled XML documents in the XML Editor.

All document wizards are listed in the Document Wizards dialog box. Select File >
Document Wizards to display this dialog box.

Creating XML from XML Schema

When you use the XML Schema to XML document wizard, you specify the XML Schema
from which you want to create an XML document, as well as its root node, and whether
or not you want to generate comments in the XML.
Note If the XML Schema contains an element defined using a built-in type, the instance of that

element in the XML document is created using the minimum value of the range specified
for that type. For example, if the XML Schema contains a <part> element defined as
type=xs:integer, the <part> element in the resulting XML document appears as
<part>-9223372036854775808</part>.

Stylus Studio User Guide

139

Editing and Querying XML

Creating XML from DTD

In addition to XML Schema, you can use a DTD to create an XML file. When you use the
DTD to XML document wizard, you specify the DTD from which you want to create an
XML document in the DTD File field. Next, specify the element that you want to be the
root element in the new XML document, and whether or not you want expand each
element only once (this results in a smaller XML document file).

Creating XML from HTML

You can create an XML document from an HTML file using the HTML to XML
document wizard. Simply specify the HTML file you want converted to XML and run the
document wizard.
Tip Stylus Studio also has a document wizard that converts HTML to XSLT. See

<hyperlink>Creating a Stylesheet from HTML on page 415.

140

Stylus Studio User Guide

Updating XML Documents

The XML editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
Stylus Studio provides Text, Tree, and Grid views for updating any XML document you
open. The view you choose for editing depends on how structured your data is and your
personal preferences. This section describes how to choose an XML document view to
work with and other features related to editing XML.
This section discusses the following topics:

Choosing a View on page 141

Saving Your Work on page 142

Ensuring Well-Formedness on page 142

Reverting to Saved Version on page 142

Updating Java Server Pages as XML Documents on page 143

Choosing a View
You can add and modify the data and structure of an XML document in any view. When
you switch to a different view, any changes you made appear in the new view. To move
from view to view, click the Text, Tree, or Grid tab at the bottom of the document you are
working with.
To add contents to an empty XML document, consider the structure of the data you plan
to add. The Grid view is most useful for creating very structured data that includes
multiple instances of the same elements. The Tree view makes it easy to add many
different elements. In order to use it, however, the XML must be well-formed.
Each view of the document allows you to query the contents of the document. See
Querying XML Documents Using XPath on page 210.
Watch it! You can view a video demonstration of the Grid tab by clicking the
television icon or by clicking this link: watch the XML Grid Editor video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.

Stylus Studio User Guide

141

Editing and Querying XML

For More Information

To learn more about a specific XML view, see one of the following sections:

Using the Text Editor on page 143

Updating DOM Tree Structures on page 157

Using the Grid Tab on page 161

Saving Your Work

The procedure for saving your work is the same regardless of which view you use to edit
XML make sure your work is in the active window, and then select File > Save from the
in the Stylus Studio tool bar.
Stylus Studio menu bar, or click Save

Ensuring Well-Formedness
To ensure that your XML document is well formed, click the Tree tab at the bottom
of the XML editor window.

If the document is well formed, Stylus Studio displays the tree representation. If the
document is not well formed, Stylus Studio displays a message that indicates the reason
the document is not well formed and the location of the error or omission. Correct the
document, and click the Tree tab.
If you are already viewing the Tree representation of your document, the document is well
formed. When you edit the Tree view, the XML that Stylus Studio generates is always
well formed.

Reverting to Saved Version

You might make some changes to an XML document and then decide that you do not want
to save them. In the Stylus Studio tool bar, click Reload
. Stylus Studio displays a
message that warns you that you will lose any changes, and prompts you to confirm that
you want to reload the version of the document that is in the file system. After you
confirm, Stylus Studio displays the last saved version of the document.

142

Stylus Studio User Guide

Using the Text Editor

Updating Java Server Pages as XML Documents

To open a .jsp file as an XML document:
1.

In the File Explorer, navigate to the JSP file you want to open.

Right click the file name, and select Open With from the shortcut menu.

Click XML Editor.

Using the Text Editor

You use the Text tab of the XML editor to edit XML text. The Text tab provides the usual
tools you expect to find in a text editor. These tools are described in this section.

Figure 101. Text Tab in the XML Editor

This section covers the following topics:

<hyperlink>Text Editing Features on page 144

<hyperlink>Use of Colors in the Text Tab on page 149

Stylus Studio User Guide

143

Editing and Querying XML

<hyperlink>Using the Spell Checker on page 151

<hyperlink>Moving Around in XML Documents on page 155

Text Editing Features

This section describes some of the more common text editing tools and features in Stylus
Studio.

Simple Text Editing

Select the text you want to edit and then do any of the following:

Click the right mouse button to display a pop-up menu of edit commands.

Click the appropriate button in the Stylus Studio tool bar.

Press the standard control keys to copy, cut, paste, undo, or redo.
You can select a portion of text and move it to a new location by dragging it. You can drag
text from one document to another. You can drag text from documents outside Stylus
Studio to a document in Stylus Studio.

Code Folding
Code folding is the ability to collapse three or more lines of code in XML-based editors.
For example, this code segment:
<author>
<first-name>Joe</first-name>
<last-name>Bob</last-name>
<award>Trenton Literary Review Honorable Mention</award>
</author>

when collapsed, appears as this:

Code folding allows you to simplify the visual presentation of XML-based code; folding
does not affect the underlying code.
In editors in which code folding is supported, Stylus Studio displays a tree control in the
gutter to the left of editing canvas; this is the same area of the editor used to display line
numbers, debugging symbols, and back mapping symbols. By default, all code is
displayed.
144

Stylus Studio User Guide

Using the Text Editor

What You Can Fold

In XML-based editors, you can fold

Internal DTD

Comments

CDATA

XML elements
In the XQuery Source editor, you can fold

Comments

Expressions delimited by curly braces ( { and } )

XML elements
How to Fold Code
To unfold a segment of code, click the [-] symbol associated with that code.

When you fold code, Stylus Studio displays a boxed ellipsis symbol at the end of the line
of code you have folded, as shown here:

Figure 102. Example of Folded Code

If you place the pointer in the ellipsis symbol, Stylus Studio displays a tool tip that shows
you the collapsed code. The amount of code that appears in the tool tip depends on the
area on your desktop you have given the Stylus Studio application.
Tip You can unfold a folded segment by double-clicking the tool tip.

Sense:X Speeds Editing

As you type, Sense:X prompts you with the possible tags that you can insert at a given
location based on the XML Schema associated with the document you are editing. As
soon as you type a tags open bracket, Stylus Studio displays a scrollable list of the
Stylus Studio User Guide

145

Editing and Querying XML

elements that are allowed at that location of the document. As shown in Figure 103, there
are two entries for book, for example:

Figure 103. Choose Element Name or Element Fragment

If you choose the first book item (

), Stylus Studio completes the <book tag for you.
If you choose the second book item (
), Stylus Studio completes the entire XML
fragment for you, including all attributes and default values described in the associated
XML Schema, as shown in Figure 104:

Figure 104. Complete XML Fragment Inserted Using Sense:X

Use the arrow key to move the selection, and press Enter to insert the value you want.

Indent
Indent XML tags to show the hierarchy relationships. Click Indent XML Tags
Studio indents all text in the active XML document window.

. Stylus

Note After you click the Indent XML Tags button, you cannot automatically undo or redo any

changes you have been making. After you make more changes, you can press Ctrl+Z and
Ctrl+Y to automatically undo and redo those changes until you click Indent XML tags
again.

146

Stylus Studio User Guide

Using the Text Editor

Line Wrap
Stylus Studio automatically wraps lines whose length exceeds 16k characters. You can
turn off this feature by selecting Disable from the Line wrap field on the Editor General
page of the Options dialog box (Tools > Options).
You can override line wrap settings by selecting Edit > Wrap Lines from the Stylus Studio
menu or by clicking the wrap lines button on the tool bar( ).
When line wrapping is on, Stylus Studio wraps lines to fit in the available window; the
place at which the line wraps moves as the width of the window changes. Green arrows,
as shown in Figure 105, indentify lines that have wrapped.

Figure 105. Green Arrows Identify Lines That Have Wrapped

Spell Checking
By default, Stylus Studio spell checks text as you type using an internal spell checker.
Words the spell checker believes are misspelled (or repeated) are underlined with a
squiggly line, as shown in Figure 106.

Figure 106. Typographical Errors Are Highlighted by the Spell Checker

For more information, see <hyperlink>Using the Spell Checker on page 151.

Stylus Studio User Guide

147

Editing and Querying XML

Font
You can change the font of the text display in Stylus Studio. This change affects only the
Stylus Studio display. Beyond personal preference, you might choose to change the font
for localization purposes the available fonts are the fonts that can display the characters
in your XML file. For example, in a Japanese file, only two or three font names appear.
Click Font Change
to display a list of fonts.

Comments
Select the text that you want to be a comment. In the Stylus Studio tool bar, click
Comment/Uncomment Selection
. To remove comment tags, select the commented
text, and click Comment/Uncomment Selection.
Tip To select an entire line, click the gray area to the left of the line you want to select.

Bookmarks
You can set bookmarks in the XML display. Bookmarks allow you to jump to important
lines in your file. See Using Bookmarks on page 556.

Search/Replace
Search for and replace text you specify. Click Find
You can also enable Find by pressing Ctrl + F.

or Replace

in the tool bar.

Figure 107. Find Dialog Box

When you enable Find, Stylus Studio displays the word in which the cursor is located
whether the cursor is within the word or immediately adjacent to it in the Find what field

148

Stylus Studio User Guide

Using the Text Editor

of the Find dialog box. Similarly, any text you have selected whole, partial, or multiple
words is displayed in the Find what field.
Tip You can scroll through a list of the other words you have searched for by clicking the
down arrow when the Find what field is active.

Note that in addition to specifying case, you can also indicate whether or not you want to
use regular expressions in the Find what field and Replace with field. This allows you, for
example, to search for a line and replace it with multiple lines, as shown in the following
example.

Figure 108. Replacing Text Using Regular Expressions

See Sample Regular Expressions on page 258 for examples of regular expressions and
to learn about other sources of information.

Use of Colors in the Text Tab

Stylus Studio text editors use colors to distinguish the types of data in XML documents.
The default colors for the XML Editor are described in the Table 12.
Table 12. Text Colors in Stylus Studio
Color

Type of Data

White

Document background

Royal blue

Markup

Black

XML declaration and text node contents

Pale blue

Schema definition

Stylus Studio User Guide

149

Editing and Querying XML

Table 12. Text Colors in Stylus Studio
Color

Type of Data

Purple

Element names defined in the DTD

Red

Attribute names

Dark blue

Attribute values

Orange

Element names not defined in the DTD

How to Change Colors

You can set colors for the text editors associated with different document types (XML,
XQuery, XSLT, and so on) individually.
To change colors:

150

Select Tools > Options to display the Options dialog box.

Click Editor Format.

Select the editor type from the Editor drop-down list.

Set the font, size, and color for different document categories as desired.

Click OK to close the Options dialog box.

Stylus Studio User Guide

Using the Text Editor

Using the Spell Checker

You can use the Stylus Studio Spell Checker with all of Stylus Studios text-based editors
(like editors for XQuery and XSLT, for example) to both actively and passively check
your documents for typographical errors such as misspellings and repeated words.

Figure 109. Stylus Studios Spell Checker

Default Spell Checking

The Spell Checker is on by default for most editors. This means that when you open a
document in a Stylus Studio text editor, and as you type in that document, Stylus Studio
checks the document for typographical errors. Words that the Spell Checker identifies as
possibly containing a typographical error are underlined with a red squiggle, like the
word Worx shown in Figure 106.
Tip You can right-click a word with a squiggle and select Spell Checker Suggestions for to

display a list of suggestions for the word identified by the Spell Checker.

Manual Spell Checking

At any time, you can manually spell check a document by selecting Tools > Check
Spelling from the Stylus Studio menu. When you do this, Stylus Studio starts the Spell
Checker, which reads through the current document. When it finds a possible
typographical error, Stylus Studio displays the Spelling dialog box, as shown in
Figure 109.
Using the Spelling dialog box, you can
Stylus Studio User Guide

151

Editing and Querying XML

Ignore the current occurrence of the word the Spell Checker has selected
Ignore all occurrences of the word
Replace the current occurence of the word
Replace all occurrences of the word
Add new words to the dictionary
Edit existing dictionary content

Specifying Spell Checker Settings

You specify Spell Checker settings using the Spell Checking page of the Options dialog
box.

Figure 110. Options for the Spell Checker

Spell Checker settings include

Words to skip based on certain characteristics you might decide to skip e-mail
addresses and URLs, for example. Skipped words are not considered by the Spell
Checker.

Characteristics in words that you wish to ignore you might not care about case or
accents marks for spelling purposes. In this case, two words that share the same
spelling, except for the characteristic you specify, are considered to be equivalent
(mme and meme (accent), or BMW and bmw (case), for example).

152

Stylus Studio User Guide

Using the Text Editor

The type of dictionary you want the Spell Checker to use when providing alternatives
to the typographical errors it locates. Settings range from Abriged to Unabridged and
show the fewest to the most alternatives, respectively. The Abridged setting results in
fewer alternative suggestions for misspelled words than Standard (the default) or
Unabridged, for example, but it requires less time to spell check a given document.
The layout of the keyboard you are using. The Spell Checker uses this information to
offer meaningful suggestions to words you might have mistyped.

How to Spell Check a Document

To spell check document:
1.

Select Tools > Check Spelling from the menu.

Stylus Studio starts checking the document for typographical errors. If it finds a
typographical error, it displays the Spelling dialog box.
If You Want To

Then

Replace the misspelled word with the word

suggested by the Spell Checker

Click Replace. Click Replace All to

replace all occurrences of that word.
You can also replace the misspelled word
with another word selected from the
Alternatives list box, or with a word you
type in the Replace with field.

Ignore the misspelled word

Click Ignore. Click Ignore All to ignore

all occurrences of that word.

Add the misspelled word to the personal

dictionary

Click Add.

Edit the personal dictionary

Click Edit. See <hyperlink>Using the

Personal Dictionary on page 154 for more
information.

Once you select an action, the Spell Checker continues checking the document.
When you have addressed all identified errors in the document (either by replacing,
correcting, or ignoring them), the Spell Checker stops.

Stylus Studio User Guide

153

Editing and Querying XML

Using the Personal Dictionary

The Stylus Studio Spell Checker comes with its own dictionary. You can create a personal
dictionary and fill it with your own entries. Personal dictionaries are used in conjuction
with the Spell Checker dictionary across all Stylus Studio editors.
To add entries to the personal dictionary, you can

Type entries individually

Import lists formatted as .txt files

Automatically add entries while you check the document

The personal dictionary is stored in the c:\Documents
Application Data\Stylus Studio directory.

and Settings\username\

Warning Do not modify the files in this directory by hand. Use the Personal Dictionary Editor

dialog box to make any changes to the personal dictionary.

To add a word to the personal dictionary:
1.

Start the Spell Checker and display the Personal Dictionary Editor dialog box (click
Edit on the Spelling dialog box).

Enter a word in the New Word field.

Click the Add button.

The word appears in the Words in Personal Dictionary list box.

Click the Close button.

Tip You can also add any word identified as a misspelling to the personal dictionary by
pressing the Add button on the Spelling dialog box.

To import lists into the personal dictionary:

Note Lists you import into the personal dictionary must be unformatted .txt files, with each

entry on its own line. Do not use tab- or comma-separated files.

154

Start the Spell Checker and display the Personal Dictionary Editor dialog box (click
Edit on the Spelling dialog box).

Click the Import button.

The Open dialog box appears.

Select the .txt file you want to import into the personal dictionary and click Open.
The words in the list you import appear in the Words in Personal Dictionary list box.
Stylus Studio User Guide

Using the Text Editor

Click the Close button.

To export the personal dictionary to a .txt file:

Start the Spell Checker and display the Personal Dictionary Editor dialog box (click
Edit on the Spelling dialog box).

Click the Export button.

The Save As dialog box appears.

Navigate to the directory in which you want to save the copy of the personal
dictionary.

Enter a name in the File name field.

Click Save.
The contents of the personal dictionary is saved to the text file.

Click the Close button.

Moving Around in XML Documents

Stylus Studio provides several tools for easily moving around in an XML document.

Line Numbers
To go to a particular line, click Go to a specified location
in the Stylus Studio tool
bar. Stylus Studio displays the Go To dialog box. Type the number of the line you want to
go to and click OK. The cursor moves to the line you specified.
Stylus Studio displays line numbers and column numbers in the lower right corner of the
Stylus Studio window. If you want, you can set a Stylus Studio option that displays line
numbers to the left of each line in the editor you are using.
To do this, from the Stylus Studio menu bar, select Tools > Options. In the Options page
that appears, click Editor General. In the Editor field, select the editor in which you want
to display line numbers. Select the Show Line Numbers check box.

Stylus Studio User Guide

155

Editing and Querying XML

Bookmarks
To quickly focus on a particular line, insert a bookmark for that line. You can insert any
number of bookmarks. You can insert bookmarks in any document that you can open in
Stylus Studio.
To insert a bookmark, click in the line that you want to have a bookmark. Then click
Toggle Bookmark
in the Stylus Studio tool bar. Stylus Studio inserts a turquoise box
with rounded corners to the left of the line that has the bookmark. To move from
or Previous Bookmark
. See
bookmark to bookmark, click Next Bookmark
Using Bookmarks on page 556.

Tags
To move to the closing tag for an element, click in the tag name for the element. In the
. Stylus Studio moves the cursor to
Stylus Studio tool bar, click Go to Matching Tag
the closing tag for the element you clicked.

Find
In any view of an XML document, and in the XSLT Source view of a stylesheet, you can
in the Stylus Studio tool bar. In the Find dialog box that appears, specify
click Find
the string you want to search for and click Find Next. Stylus Studio highlights the first
occurrence of the string you entered. In the Text view, you can specify that you want
Stylus Studio to highlight all instances.
Depending on which view you are examining, Stylus Studio allows you to specify
constraints on the search. The constraints you can specify include the following:

Match whole word only

Match case

Find a regular expression

Search inside only element tags, only element values, only attribute names, and/or
only attribute values
To learn more about regular expression syntax, visit
http://www.boost.org/libs/regex/doc/syntax.html.

156

Stylus Studio User Guide

Updating DOM Tree Structures

To update the DOM tree for an XML document, click the Tree tab at the bottom of the
window that contains the document.

Figure 111. Tree Tab in XML Editor

While you are editing, if the display does not appear to correctly represent the current tree,
in the main tool bar. If you want to perform a certain action
click Reload Document
and Stylus Studio has grayed out the button for that action, try clicking Refresh first.
To save your file, select File > Save from the Stylus Studio menu bar or click Save in the
Stylus Studio tool bar.
This section discusses the following topics:

Displaying All Nodes in the Tree View on page 158

Adding a Node in the Tree View on page 158

Deleting a Node in the Tree View on page 159

Moving a Node in the Tree View on page 159

Changing the Name or Value of a Node in the Tree View on page 159
Stylus Studio User Guide

157

Editing and Querying XML

Obtaining the XPath for a Node on page 160

Displaying All Nodes in the Tree View

To expand a tree so that you can see all the nodes in the tree, click the root node and then
press the asterisk (*) key in the numeric key pad. To expand any particular node, click that
node and press * in the numeric key pad.
The default tree view of your document does not include nodes that contain only blank
spaces, line feeds, or tabs. To toggle between the default view and a view that does display
all nodes, click White Space
in the Stylus Studio tool bar. This view is most helpful
when you are operating on the DOM and need to know the exact structure of the tree.

Adding a Node in the Tree View

Along the left side of the window that contains your DOM tree, there are buttons that
represent the types of nodes you can add to your document. The procedure for adding a
node is similar for all types of nodes.
To add an element:

158

Click the element that you want to be the parent of the new element, or click an
element that you want to be a sibling of the new element.

To add a child element, click New Element

. To add a sibling element, hold down
the Shift key and click New Element.
Alternative: To add a child element, press Ctrl+E. To add a sibling element, press
Ctrl+Shift+E.
If your XML document specifies a DTD, Stylus Studio displays a list of the elements
that you can add at that location. If your document is associated with an XML Schema
or does not specify a DTD, Stylus Studio prompts you to specify the name of the new
element.

Double-click the element you want to add, or type the name of the new element and
press Enter. If you added a child node, Stylus Studio adds it as the last child.

If the new element contains data, type a value for the new element and press Enter.

Stylus Studio User Guide

Updating DOM Tree Structures

Deleting a Node in the Tree View

Along the left side of the window that contains your DOM tree, there are buttons that
represent the types of nodes you can add to your document. The procedure for deleting a
node is similar for all types of nodes.
To delete a node:
1.

Click the node you want to delete.

Click Delete Node

Moving a Node in the Tree View

Along the left side of the window that contains your DOM tree, there are buttons that
represent the types of nodes you can add to your document. The procedure for moving a
node is similar for all types of nodes.
To move a node:
1.

Click the node you want to move.

Click the up and down arrows at the top of the document window to move the node
up or down the tree.
Alternative: Drag the node to its new location.

Changing the Name or Value of a Node in the Tree View

Along the left side of the window that contains your DOM tree, there are buttons that
represent the types of nodes you can add to your document. The procedure for renaming
a node is similar for all types of nodes.
To rename a node:
1.

Click the node you want to rename.

Click Change Name

. If your document specifies a DTD, Stylus Studio displays
a list of the possible names. If your document does not specify a DTD, Stylus Studio
opens an edit field.

Double-click the new name, or type the new name and press Enter.

Stylus Studio User Guide

159

Editing and Querying XML

To change the value of a node:

Click the node whose value you want to change.

Click Change Value

Type the new value and press Enter.

. Stylus Studio displays an update field.

Obtaining the XPath for a Node

To obtain the XPath expression that returns a particular node:

160

In the XML editor, click the Tree tab.

Right-click the node for which you want the XPath expression.

In the shortcut menu that appears, click Copy XPath Query to Clipboard.

Press Ctrl+V to paste the XPath expression where you want it.

Stylus Studio User Guide

Using the Grid Tab

The XML Editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
The Grid view of an XML document is useful for structured data it is a convenient way
to view and work with documents that contain multiple instances of the same type of
element.

Figure 112. Grid View of books.xml

This section describes the features of the Grid tab and how to use it to edit XML
documents. This section covers the following topics:

Layout of the Grid Tab on page 162

Features of the Grid Tab on page 162

Moving Around the Grid Tab on page 166

Working with Rows on page 168

Working with Columns on page 170

Stylus Studio User Guide

161

Editing and Querying XML

Working with Tables on page 172

Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Grid Editor video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.

Layout of the Grid Tab

The Grid tab consists of a tool bar and a display area. The tool bar has buttons to perform
actions and operations on both the grid itself and on the underlying XML document
represented in the grid. An example of the former is the ability to show the child elements
of the documents root element; they are hidden by default. An example of the latter is the
ability to add a new instance of an element or to change a value. These operations are also
accessible from the XML > Grid Editing menu, as well as from the grid shortcut menu
(right-click on the grid).
The tool bar also includes a query field, which allows you to enter an XPath expression to
query the XML document. Results are displayed in the Query Output window, which
appears when you run the query if it is not already displayed. See Querying XML
Documents Using XPath on page 210 for more information on this feature.
The display area shows the XML document, both its structure and content, rendered in a
tabular, or grid format.

Features of the Grid Tab

This section describes the features of the Grid tab. It covers the following topics:

Expanding and Collapsing Nodes on page 163

Collapsing Empty Nodes on page 163

Renaming Nodes on page 165

Resizing Columns on page 165

Showing Row Tag Names on page 166

162

Stylus Studio User Guide

Using the Grid Tab

Expanding and Collapsing Nodes

When you first display a document in the Grid tab, the document is collapsed so that it
shows just the root element (here it is <books>) and its name attribute (My books), as shown
in Figure 113.

Figure 113. Default Display Document Elements Are Collapsed

A plus sign displayed to the left of the node name indicates that this node has child nodes.
You can click the plus sign to display a subgrid that displays the child nodes, as shown in
Figure 114.

Figure 114. Click Plus Signs to Expand Collapsed Tables

You can continue to drill down in this fashion to view all values.
To expand a node, click the plus sign (

Collapsing Empty Nodes

Some nodes in a document are simply containers they have no content of their own. An
example of a container node is the <authors> element in books.xml. The <authors>

Stylus Studio User Guide

163

Editing and Querying XML

element is simply a container for one or more <author> elements, as shown in this excerpt
of books.xml:
<authors>
<author>David A. Chappel</author>
<author>Tyler Jewell</author>
</authors>

To streamline the display, Stylus Studio hides the tables that represent container nodes.
Information about container nodes is displayed in the child nodes header. Figure 115
shows the default display for the author element. Notice that the header,
book/authors/author, contains information about the container node, authors.

Figure 115. Table Headers Show Full Path

If you want, however, you can display the tables associated with container nodes, as
shown in Figure 116.

Figure 116. Container Nodes Are Hidden by Default

164

Stylus Studio User Guide

Using the Grid Tab

The table associated with the authors node now appears in the grid; it is empty (it has no
rows) because it is a container. The elements it contains are displayed in their own table,
authors/author.
To display container nodes, click Simplified View (

This action is also available from the XML > Grid Editing menu and from the grid shortcut
menu.

Renaming Nodes
You can rename container nodes directly in the grid.
To rename a node:
1.

Double-click the header that represents the node you want to rename.
The node name is selected.

Type the name you want to use for the node.

Press Enter (or click elsewhere in the grid or grid background).

Resizing Columns
When you expand a node, Stylus Studio displays it in uniform columns. You can resize
columns to any width you prefer by dragging the handle on the right side of the column
header, as shown in Figure 117.

Figure 117. Resize Columns by Dragging the Right Handle

To resize a column, drag the handle on the right side of the column header.

Stylus Studio User Guide

165

Editing and Querying XML

Showing Row Tag Names

In the grid view of a structured XML document, each child element of a node corresponds
to a row in a table. For example, the <books> node of books.xml contains nine child
elements; each row is an instance of the <book> element. To preserve space in the grid, the
tag names of child elements are not displayed as a separate column in the table. Rather,
as shown in Figure 114, this information is displayed in the table header itself.
If you want, you can display the tag name for child elements in their own columns, as
shown in Figure 118.

Figure 118. Displaying the Roots Child Element

To toggle the display of child element names, click Toggle Row Tag Name (

This action is also available from the XML > Grid Editing menu.

Moving Around the Grid Tab

You can move around the grid using the mouse (click where you want to go) and the
keyboard. Keyboard navigation is presented in the following table.
Table 13. Keyboard Navigation in the Grid

166

Key

Action

Up/Down arrow keys

Moves the row highlight in the direction of the arrow key you press.

Left/Right arrow keys

Moves the focus from one cell to the next, in the direction of the
arrow key you press.

Page Up

Moves the row highlight to the root nodes attribute.

Stylus Studio User Guide

Using the Grid Tab

Table 13. Keyboard Navigation in the Grid
Key

Action

Page Down

Moves the row highlight to the last row in the document.

Tab

Moves the focus forward to the next cell in the row; moves to the
first cell of the next row when you hit the last cell in a row.

Shift + Tab

Moves the focus backward to the previous cell in the row; moves to
the last cell of the previous row when you hit the first cell in a row.

Selecting Items in the Grid

When you select a cell in a table:

The row is selected; you can perform row-oriented actions like changing the rows
order in the table. You can also select a row by clicking the plus sign to the left side
of the row.

The column is selected; you can perform column-oriented actions like adding a new
column or renaming an existing one.

The cell gets focus.

Tip Pressing Enter places a selected cell in Edit mode.

How Grid Changes Affect the XML Document

When you make a change to the document structure or content on the Grid tab, those
changes are reflected immediately in the underlying XML document. You can see your
changes affect the document on the Text tab.
Consider the following excerpt from books.xml.
<authors>
<author>David A. Chappel</author>
<author>Tyler Jewell</author>
</authors>

Stylus Studio User Guide

167

Editing and Querying XML

If you move the rows in the authors table, for example, as shown in Figure 119,

Figure 119. Moving a Row Affects XML

the underlying XML changes accordingly:

<authors>
<author>Tyler Jewell</author>
<author>David A. Chappel</author>
</authors>

Types of Changes that Affect the Document

The following changes, all of which can be made using Grid tab, affect the underlying
XML document:

Adding, deleting, reordering rows

Adding, deleting, reordering, and renaming columns

Adding, deleting, reordering, and sorting tables

Changing element and attribute values

Renaming container elements

Changes you make affect the current instance only. For example, in the example shown in
Figure 119, only that instance of the nested table is affected. If you add a column to
books/book, however, every instance of books/book gets that new column.

Working with Rows

Stylus Studio provides several features to help you work with table rows in the Grid tab.
Changes you make to tables in the Grid tab, such as adding a new row or modifying a
value, are reflected in the underlying XML document.
This section covers the following topics:

Reordering Rows on page 169

Adding and Deleting Rows on page 169

168

Stylus Studio User Guide

Using the Grid Tab

Reordering Rows
You can move rows up and down within the same table. Changes you make to row order
affect the element order in the underlying XML document.
To move a row:
1.

Select the row you want to move.

Click the Move Up ( ) or Move Down ( ) button to move the row to the desired
location in the table. These actions are also available from the XML > Grid Editing
menu and from the grid shortcut menu.

Adding and Deleting Rows

You can add and delete rows in a table. Changes you make to the table in this way affect
the number of instances of the element in the table. When you add a row, you can insert
it in the table above or below the currently selected row.
Tip You can move rows up and down within a table.

To add a row:
1.

Select the row next to which you want to insert a new row.

Click the Insert Row Before ( ) or Insert Row After ( ) button to add the new row
to the table. These actions are also available from the XML > Grid Editing menu and
from the grid shortcut menu.
The row is added to the table.

To delete a row:
1.

Select the row you want to delete.

Click Delete ( ). This action is also available from the XML > Grid Editing menu
and from the grid shortcut menu.
The row is deleted from the table.

Stylus Studio User Guide

169

Editing and Querying XML

Working with Columns

Stylus Studio provides several features to help you work with table columns in the Grid
tab. Changes you make to tables in the Grid tab, such as adding a new column or
reordering existing columns, are reflected in the underlying XML document.
This section covers the following topics:

Selecting a Column on page 170

Adding Columns on page 170

Deleting Columns on page 171

Reordering Columns on page 171

Renaming Columns on page 172

Changing a Value on page 172

Selecting a Column
Column operations can be performed when you select any cell in a column. When a cell
(and, therefore, its column) is selected, it is highlighted with a yellow outline. As shown
in Figure 120, the <title> column is selected the cell containing Java Message Service
is the one that is highlighted.

Figure 120. Selected Cells are Highlighted in Yellow

To select a column, click any cell in the column you wish to select.

Adding Columns
You can add two types of columns to tables in the Grid tab attribute columns and element
columns. The procedure for adding both types of columns is the same. When you add a
column, it is inserted immediately after the last column of its type. You can move columns
after you create them.

170

Stylus Studio User Guide

Using the Grid Tab

To add a column:
1.

Select the row in which you want to add a column.

Click Add Attribute Column ( ) or Add Element Column ( ). These actions are
also available from the XML > Grid Editing menu and from the grid shortcut menu.
The column is added to the table.

If you want, move the column to a new location in the row. See Reordering
Columns on page 171.

Deleting Columns
To delete a column:
1.

Select a cell in the column you want to delete.

A yellow border appears around the cell you select.

Click Delete Column ( ). This action is also available from the XML > Grid Editing
menu and from the grid shortcut menu.
The column is deleted from the table.

Reordering Columns
You can reorder columns in the grid by dragging them to the position you desire.
To reorder a column:
1.

Place the pointer on the left handle in the column header.

Press and hold mouse button one.

The cursor changes shape, as shown here.

Figure 121. Moving a Column

Drag the column to the location in the row you want.

Release the mouse button.

The column is placed in the new location within the row.

Stylus Studio User Guide

171

Editing and Querying XML

Renaming Columns
You can rename columns in the grid. This has the effect of renaming the corresponding
attribute or element name in the underlying XML document.
Note You cannot rename the root element from the Grid tab.

To rename a column:
1.

Select a cell in the column you want to rename.

A yellow border appears around the cell you select.

Click Rename Column ( ). This action is also available from the XML > Grid Editing
menu and from the column shortcut menu.
The column is renamed.

Changing a Value
You can change element and attribute values.
To change a value:
1.

Double-click the cell whose value you want to change.

The cell field becomes editable, as shown here.

Figure 122. Changing a Value

Edit the value as required.

Press Enter.

Working with Tables

Stylus Studio provides several features to help you work with tables in the Grid tab.
Changes you make to tables in the Grid tab, such as adding a nested table, are reflected in
the underlying XML document.
This section covers the following topics:

Adding a Nested Table on page 173

Moving a Nested Table on page 174

Deleting a Table on page 174

172

Stylus Studio User Guide

Using the Grid Tab

Sorting a Table on page 175

Copying a Table as Tab-Delimited Text on page 175

Adding a Nested Table

You add nested tables to a document in the Grid tab using the Add Nested Table dialog
box, shown in Figure 123. This dialog box allows you to specify the path to the root for
the new table, a row element name, and the number of rows.

Figure 123. Add Table Dialog Box

A nested table is created as a child of the current element. The nested table shown in
Figure 124, myTable, was created as a child of the <book> element.

Figure 124. Default Nested Table

Nested tables are created with two default rows, which use the element name you provide
in the Row Element Name field of the Add Nested Table dialog box. Rows get a default

Stylus Studio User Guide

173

Editing and Querying XML

text value of Row n text, where n is an incrementing value starting with 1. You specify the
number of rows using the Number of rows field.
To add a nested table:
1.

Select the element to which you want to add a nested table.

Click Add Nested Table ( ). This action is also available from the XML > Grid
Editing menu and from the grid shortcut menu.
The Add Nested Table dialog box appears.

Optionally, specify the path to the root. If you leave this field blank, the nested table
is created as a child of the current element.

Enter a row element name.

Optionally, change the number of default rows.

Click OK.
The nested table is added to the document and appears in the grid.

Moving a Nested Table

You can change the order of nested tables within a row.
To move a nested table:
1.

Select the heading of the nested table you want to move.

Click the Move Up ( ) or Move Down ( ) button to move the table to the desired
location. These actions are also available from the XML > Grid Editing menu and from
the grid shortcut menu.

Deleting a Table
To delete a table:

174

Select the heading of the table you want to delete.

Click Delete ( ). This action is also available from the XML > Grid Editing menu
and from the grid shortcut menu.
The table is deleted from the document.

Stylus Studio User Guide

Using the Grid Tab

Sorting a Table
You can sort tables on any column in ascending or descending order.
To sort a table:

Tip

Select a cell in the column on which you want to sort the table.

Click the Sort Ascending ( ) or Sort Descending ( ) button to sort the table rows
in ascending or descending order, respectively. These actions are also available from
the XML > Grid Editing menu and from the grid shortcut menu.
You can also display sort options by right-clicking the column heading.
The table rows are sorted based on the order you select.

Copying a Table as Tab-Delimited Text

You can copy a tab-delimited text version of a table to the clipboard. This makes it
possible to paste document contents from the grid into spreadsheets and other editors that
can manage tab-delimited files. Figure 125 shows books/book in books.xml pasted into
Microsoft Excel, for example.

Figure 125. Pasting a Table into a Spreadsheet

Note that when you use this feature, the entire table is copied column headings (element
and attribute names) are not distinguished from cell contents (element and attribute
values) in the spreadsheet.

Stylus Studio User Guide

175

Editing and Querying XML

To copy a tab-delimited table to the clipboard:
1.

Select the heading of the table you want to copy.

Select XML > Grid Editing > Copy as Tab-Delimited from the menu. This action is also
available from the grid shortcut menu.

Diffing Folders and XML Documents

XML differencning is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
During application development, it can be useful to be able to compare two or more XML
documents, or to compare the contents of two folders, in order to identify the type and
number of differences between them. The process of comparing one document (or folder)
with another is referred to as diffing. Stylus Studio provides utilities for diffing folders and
documents.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Diff video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

Overview on page 177

Diffing Folders on page 182

The XML Diff Viewer on page 186

Diffing a Pair of XML Documents on page 193

Diffing Multiple Documents on page 195

Modifying Default Diff Settings on page 200

Running the Diff Tool from the Command Line on page 204

176

Stylus Studio User Guide

Diffing Folders and XML Documents

Overview
Stylus Studios Diff tool lets you easily compare two or more versions of the same
document in the XML Diff Viewer (as shown in Figure 126), or the contents of two
folders (as shown in Figure 130).

Figure 126. Example of Diffed Documents in the XML Diff Viewer

Customizable color-coding lets you quickly determine how one document differs from
another green, for example, identifies objects (such as elements and attributes) that are
present in the target document, but which do not exist in the source document. When you
hover the pointer over symbols displayed in the side bars of the source and target
document windows, Stylus Studio displays a tool tip that indicates the specific nature of
the change.
This section covers the following topics:

Sources and Targets on page 178

The Diff Configuration File on page 178

What Diffs Are Calculated? on page 178

Tuning the Diffing Algorithm on page 179

When Does the Diff Run? on page 180

Stylus Studio User Guide

177

Editing and Querying XML

Running the Diff Manually on page 181

Symbols and Background Colors on page 181

Sources and Targets

When you use Stylus Studio to diff documents (or folders), you select a source and a
target. Stylus Studio considers the source document or folder to be the baseline, or current
standard; the target document or folder is assumed to be some other version (it might be
older or newer, for example) of the source. The Stylus Studio Diff tool illustrates how this
other version, the target, differs from the source (or sources) you have selected.
Tip You can open source and target documents in the XML Editor from the XML Diff Viewer

right click on the XML Diff Viewer background and select the document you want to
edit from the short-cut menu of source and target documents displayed by Stylus Studio.
This feature is context-sensitive if you right-click on a node that has been removed, the
target document will not be listed, for example.

The Diff Configuration File

You can save the information associated with a given XML diff session in a diff
configuration file. Diff configuration files make it easy to perform a diff on the same set
of XML documents over time. Examples of the information saved with the diff
configuration file include the URLs of the source and target documents, and any settings
made on the XML Diff menu or tool bar. Diff configuration files are created with a .dff
extension.
Changes made to the source and target documents are detected by Stylus Studio the next
time you open the diff configuration file, allowing you to diff the files at that time.
(Whether or not the diff is run automatically when you open the diff configuration file
depends on Autorun Diff settings on the Engine page of the Options dialog box. See
When Does the Diff Run? on page 180 for more information.)

What Diffs Are Calculated?

This section describes how Stylus Studio diffs XML documents and folders.
Documents The Stylus Studio Diff engine compares source and target documents in
their entirety. If you want, you can use the Engine page of the Options dialog box to
exclude certain items from the diff calculation. These items include:

Comments

Text
178

Stylus Studio User Guide

Diffing Folders and XML Documents

Entities
Attributes
Processing instructions

You can also specify whether or not you want Stylus Studio to:

Use URIs to compare namespaces

Expand entity references

Ignore text formatting characters (new lines, carriage returns, and tabs)
See Modifying Default Diff Settings on page 200 to learn how to set these and other diff
options.
Folders Options for diffing XML documents do not affect how Stylus Studio diffs
folders. When diffing folders, Stylus Studio compares one folders contents with another.
See Diffing Folders on page 182for more information on this topic.

Tuning the Diffing Algorithm

The purpose of any diffing tool is to identify the list of logical operations required to
change the source document into the target document. Examples of logical operations
include additions, revisions, and deletions. Even diffs between simple XML documents
can yield a long list, sometimes with redundant operations. Ideally, the list of operations
should be reduced to make it as economical as possible; that is, the list should be able to
answer the question, What are the fewest number of changes required to turn the source
into the target?
Calculating such a list can be time-consuming and resource intensive, and these costs
might not be worth the benefits to a given user. For this reason, Stylus Studio provides
settings that let you tune the diffing algorithm used by the XML Diff engine. Tuning
settings are displayed in the Performance group box on the Engine page of the Options
dialog box.

Figure 127. Performance Settings Let You Tune the Diffing Algorithm

Stylus Studio User Guide

179

Editing and Querying XML

You can

Select a tuning that optimizes the algorithm to provide the most economical set of
changes possible (Optimize change description). As described earlier, this
calculation, though it yields the best results, can be costly in terms of time and
processing resources.

Select a tuning that optimizes the algorithm to provide the set of changes in the
shortest time possible (Optimize calculation time).

Let Stylus Studio decide (Autodetect). By default, Stylus Studio tries to provide the
most economical set of changes possible, but if it determines that processing
resources are limited or that the calculation will take too much time, it reverts to the
algorithm tuning that is optimized for speed.
Handling Large Documents
The Optimize for large documents with few changes setting helps speed the diffing of
large (greater than 1MB) documents. This setting can be used in conjunction with any of
the algorithm tuning settings and is on by default.

When Does the Diff Run?

Stylus Studio runs the diff automatically, as soon as you specify the target document or
folder. Whether or not subsequent changes cause Stylus Studio to automatically
recalculate the diff is determined by the Autorun Diff settings on the Engine page of the
Options dialog box. Changes that can make a diff recalculation necessary include adding
new source and target documents, changing the underlying source and target documents
themselves, or to changes to certain Engine settings.
Options That Affect When the Diff Runs
These settings, on the Engine page of the Options dialog box, determine when and
whether Stylus Studio automatically recalculates the diff.

On changes Certain types of changes to the diff configuration file require Stylus
Studio to recalculate the diff. These changes include:

Adding a new source document

Changing the target document

Changing the Use URI to compare namespaces setting

Changing the Expand entity references setting

180

Stylus Studio User Guide

Diffing Folders and XML Documents

If the On changes setting is on, Stylus Studio automatically runs the diff when any of
these changes occurs.
If files modified If you make and save changes to a source or target document, Stylus
Studio automatically runs the diff if this setting is on.

Note These settings do not affect the diffing of folders.

See Modifying Default Diff Settings on page 200to learn more about setting these and
other Diff options.

Running the Diff Manually

You can run the diff manually by clicking the Calculate diff button (
). Stylus Studio
activates this button when it detects the need to recalculate the diff, and the On changes
or If files modified settings are off. These settings, as described in When Does the Diff
Run? on page 180, cause Stylus Studio to run the diff automatically.
You can also run the diff from the command line. See Running the Diff Tool from the
Command Line on page 204.

Symbols and Background Colors

Stylus Studio uses symbols and background colors to alert you to differences in diffed
documents and folders. The following table summarizes the symbols and default
background colors, and the types of changes they represent.
Table 14. Default Colors Used for Diffing Files and Folders
Symbol

Stylus Studio User Guide

Background Color

Identifies

Light green

Added items; appears in the target document and

identifies an item that is present in the target but
absent from the source

Light red

Removed items; appears in the source document and

identifies an item that is present in the source but
absent from the target.

Light yellow

Changed items; can appear in both source and target

documents.

Light gray

Collapsed item containing changes (such as an added,

changed, or removed node).

181

Editing and Querying XML

You can change the background colors on the Presentation page of the Options dialog
box.
Combined Symbols
As described in Table 14, Default Colors Used for Diffing Files and Folders,, Stylus
Studio displays a turquoise block ( ) when a node that you have collapsed contains
changes. Sometimes, the node itself has changes. In this case, Stylus Studio combines two
symbols one indicating the change of a child within the collapsed node, and one to the
node itself. Consider the following illustration:

Figure 128. Sample of a Collapsed Node with Changes

Here, the city node displays a combined symbol the turquoise box indicates that a
change exists within the collapsed node; the minus sign indicates that the city node is not
present in the source document. Expanding the city node makes the scope and nature of
the changes explicit:

Figure 129. Expanded Node with Changes

Tip Hover the mouse point over these symbols to display tool tips that describe the nature of

the change.
Additional Symbols for Diffing Multiple Sources
Stylus Studio uses other symbols in the target document window when you diff multiple
source documents. See Symbols Used in the Target Document Window on page 196.

Diffing Folders
Stylus Studio allows you to diff two folders. As shown in Figure 130, the Diff Folders
dialog box displays the contents of each folder; symbols and colors, described in

182

Stylus Studio User Guide

Diffing Folders and XML Documents

Symbols and Background Colors on page 181, identify the types of changes in the
respective folders.

Splitter

Filter for file type

Figure 130. The Diff Folders Dialog Box After a Diff

This section covers the following topics:

Features on page 183

How to Diff Folders on page 184

How to Diff Documents from the Diff Folders Dialog Box on page 186

Features
The Diff Folders dialog box has several features that make it easy to diff folders and the
XML documents they contain:

A splitter lets you change the width of the source and target folder windows. This can
be especially useful if you are working with a folder that has nested directories.

A file type filter limits the display to files with a .xml extension; if you choose, you
can display (and diff) all file types, as shown in Figure 130.

An Abort button, shown here, appears at the bottom of the Diff Folders dialog box if
the operation you are performing (loading or diffing a directory with a large number

Stylus Studio User Guide

183

Editing and Querying XML

of files, for example) is taking more time than usual. Clicking the Abort button
cancels the operation.

Figure 131. Abort Button Lets You Cancel Long Load Operations

This feature is also part of the XML Diff Viewer.

Tip

The Diff Files button allows you to perform a diff of XML documents in the source
and target folders. See How to Diff Documents from the Diff Folders Dialog Box
on page 186for more information on this topic.

How to Diff Folders

To diff folders:
1.

Select Tools > Show Differences In > Folders from the Stylus Studio menu.
The Diff Folders dialog box appears.

Choose Folder buttons

184

Stylus Studio User Guide

Diffing Folders and XML Documents

Click the Choose Source Folder button (

).
The Select Source Folder dialog box appears.

Expand the Desktop tree and navigate to the folder you want to use as the source
folder for the diff.

Click Open.
The folder is displayed in the Source folder window of the Diff Folders dialog box.

Repeat Step 2 through Step 4 for the target folder.

Stylus Studio performs the diff as soon as you select the target folder for comparison.

Optionally, use the Show files of type drop-down list to filter the display to show only
those files of the type you specify. (By default, Stylus Studio shows XML files files
with a .xml extension.)

Stylus Studio User Guide

185

Editing and Querying XML

How to Diff Documents from the Diff Folders Dialog Box

You can diff XML documents in the source and target folders directly from the Diff
Folders dialog box.
To diff two files from the Diff Folders dialog box:
1.

Click the file you want to diff.

The document is shown as selected in both the Source folder and Target folder
windows. In this illustration, the document authors_new.xml was selected.

Notice that, even though the file names are different, Stylus Studio is able to infer that
authors_new.xml and authors_mods.xml are actually the same document.

Tip

If you select a document that cannot be diffed, you will not see the selection in the
opposite window.
2.

Click the Diff Files button.

Stylus Studio displays the XML Diff Viewer window.

For more information on diffing documents, see Diffing a Pair of XML Documents on
page 193.

The XML Diff Viewer

This section describes the XML Diff Viewer and its features, including the different views
available for comparing documents, the XML Diff Viewer tool bar, and tools for loading
documents.
This section covers the following topics:

Split View - Tree on page 187

Split View - Text on page 188

Merged View on page 189

186

Stylus Studio User Guide

Diffing Folders and XML Documents

View Symbols and Colors on page 190

The XML Diff Viewer Tool Bar on page 190
Tools for Working with Documents on page 193

Split View - Tree

You use the XML Diff Viewer to compare two or more XML documents. By default, the
XML Diff Viewer displays the diffed documents on the Split View - Tree tab. This view,
shown in Figure 132, shows the documents side-by-side using a tree/node representation.

Figure 132. XML Diff Viewer Split View - Tree

In split views (there is also a split view that shows documents in XML), source documents
are displayed on the left, the target document on the right. A splitter between the two
panes allows you to change the width of the source and target document panes by
dragging the splitter to the left and right.

Stylus Studio User Guide

187

Editing and Querying XML

Split View - Text

The Split View - Text tab also shows source and target documents side-by-side in plain
XML.

Figure 133. XML Diff Viewer Split View - Text

188

Stylus Studio User Guide

Diffing Folders and XML Documents

Merged View
If you prefer, you can select the Merged View tab, which folds the nodes from the source
and target documents into a single window, as shown in Figure 134.

Figure 134. XML Diff Viewer Merged View

The merged view displays changed items in pairs the item from the target document
appears first, the item from the source document is shown second, as shown in Figure 135.

Figure 135. Close-up of Merged View

In this example, the line through the <au_lname> element in the source document,
Hennings, indicates that it has changed to White in the target document.

Stylus Studio User Guide

189

Editing and Querying XML

View Symbols and Colors

All views use the same symbols and color schemes to identify the types of changes
detected by the Stylus Studio diff calculation by default, green for added items, yellow
for changed items, and red for removed items. In addition, the text font and size are
controlled by the settings for the XML Editor on the Editor Format page of the Options
dialog box.
See Symbols and Background Colors on page 181 for more information on this topic,
and to learn how you can assign custom colors to the results of standard differencing
operations.

The XML Diff Viewer Tool Bar

The XML Diff Viewer tool bar, shown in Figure 136, provides tools to help you

Manually start the diff calculation

Navigate source and target documents

Change default display and diff settings

Show or ignore differences in document items such as text nodes and attributes

Figure 136. The XML Diff Tool Bar

The following table identifies the individual tools and tells you where to find more
information.
Table 15. XML Diff Tool Bar Buttons
Tool Button

Description
Calculates the differences in the documents you have selected. This button is
active only when Stylus Studio detects the need to calculate differences. This
button is disabled if you have selected On changes and If files modified
settings. See Engine Settings on page 202.
Skips to the next (previous) diff in the currently selected document. You
must select a line in the document to enable these buttons.

190

Stylus Studio User Guide

Diffing Folders and XML Documents

Table 15. XML Diff Tool Bar Buttons
Tool Button

Description
By default, Stylus Studio displays collapsed documents when the diff is run.
You can override this setting using the tool bar button, or you can change it
permanently on the Options. page. See Engine Settings on page 202.
By default, Stylus Studio collapses any unchanged blocks to simplify the
display. You can override this setting using the tool bar button, or you can
change it permanently on the Options. page. See Engine Settings on
page 202.
By default, Stylus Studio uses URIs to compare namespaces when diffing
documents. You can override this setting using the tool bar button, or you can
change it permanently on the Options. page. See Engine Settings on
page 202.
Note that changing this setting requires documents to be diffed again.
By default, Stylus Studio expands entity references when diffing documents.
You can override this setting using the tool bar button, or you can change it
permanently on the Options. page. See Engine Settings on page 202.
Note that changing this setting requires documents to be diffed again.
By default, Stylus Studio considers text formatting characters (new lines,
carriage returns, tabs) when diffing documents. You can override this setting
using the tool bar button, or you can change it permanently on the Options.
page. See Engine Settings on page 202.
By default Stylus Studio shows differences in comments. You can override
this setting using the tool bar button, or you can change it permanently on the
Options. page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of
comment differences.
By default Stylus Studio shows differences in text blocks. You can override
this setting using the tool bar button, or you can change it permanently on the
Options. page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of text
block differences.

Stylus Studio User Guide

191

Editing and Querying XML

Table 15. XML Diff Tool Bar Buttons
Tool Button

Description
By default Stylus Studio shows differences in attributes. You can override
this setting using the tool bar button, or you can change it permanently on the
Options. page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of
attribute differences.
By default Stylus Studio shows differences in processing instructions. You
can override this setting using the tool bar button, or you can change it
permanently on the Options page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of
processing instruction differences.
By default Stylus Studio shows differences in entities. You can override this
setting using the tool bar button, or you can change it permanently on the
Options page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of
entity differences.
By default Stylus Studio shows differences in entity references. You can
override this setting using the tool bar button, or you can change it
permanently on the Options page. See Engine Settings on page 202.
Note that this feature affects only the display, and not the calculation, of
entity differences.
Allows you to change the font of documents displayed in the XML Diff
Viewer.

192

Stylus Studio User Guide

Diffing Folders and XML Documents

Tools for Working with Documents

The XML Diff Viewer provides several tools for working with source and target
documents:

Add/Remove document buttons. When you click the add or set document button,
Stylus Studio displays the Open dialog box. The add button for source documents
displays a green plus sign on it (
) to alert you to the fact that you can add multiple
source documents when diffing XML documents. You can specify only a single target
document, however.
You use the remove button, the folder with the red minus sign on it (
), to remove
the current source document from the XML diff calculation.
If Stylus Studio determines that the load or diff operation for a given XML document
will take more than a moment, it displays a message and an Abort button at the
bottom of the XML Diff Viewer window. You can click the Abort button to terminate
the operation at any time. The message and the button are removed from the XML
Diff Viewer window once the operation is complete or cancelled.

Tip

Drop-down list. You use the drop-down list to change the current document in the
XML Diff Viewer. When you change the current doc in a multi-document diff, the
target document display specifically, the symbols and colors used to identify
documents typically changes, as well. See Symbols Used in the Target Document
Window on page 196 for more information.

Removing a Target Document

You cannot remove a target document. You can specify a different target document by
clicking the set target button (
) again. This replaces the current target document with
the document you select.

Diffing a Pair of XML Documents

This section describes how to use Stylus Studio to diff a pair of XML documents.
Before continuing with this section, you should read Overview on page 177, which
describes basic information about the Stylus Studio Diff tool, and The XML Diff
Viewer on page 186, which describes features of the XML Diff Viewer and how to use
them.

Stylus Studio User Guide

193

Editing and Querying XML

How to Diff a Pair of Documents

To diff a pair of documents:
1.

Select Tools > Options > Show Differences > Files from the Stylus Studio menu.
Stylus Studio displays the XML Diff Viewer.

In the source document window, click the add button (

document.
Stylus Studio displays the Open dialog box.

You can drag and drop a file into the entry field to load the document in the XML Diff
Viewer.

Tip

194

) to add the source

Navigate to the document you want to load in the XML Diff Viewer.

Click Open.

Repeat Step 2 through Step 4 for the target document, using the set button for the
target document window (
).
By default, Stylus Studio runs the diff calculation automatically when you select the
target document. If the default On changes setting has changed, you need to run the
diff calculation manually by clicking the Calculate diff button (
).

Stylus Studio User Guide

Diffing Folders and XML Documents

Diffing Multiple Documents

This section describes how to use Stylus Studio to diff multiple XML documents.
Before continuing with this section, you should read Overview on page 177, which
describes basic information about the Stylus Studio Diff tool, and The XML Diff
Viewer on page 186, which describes features of the XML Diff Viewer and how to use
them.
This section covers the following topics:

Document Focus on page 195

Symbols Used in the Target Document Window on page 196

Document Focus
Diffing multiple XML documents is much the same as diffing a pair of documents you
specify the source documents (one at a time), a target document, and Stylus Studio
calculates the diff.
Note When you diff multiple source documents against the target, Stylus Studio considers the

target document to be the baseline, and the XML Diff Viewer shows how the source
documents vary from the target.

Stylus Studio User Guide

195

Editing and Querying XML

ge
t.x
m
l
ta
r

so
ur
ce
3.
xm
l

so
ur
ce
2.
xm
l

so
ur
ce
1.
xm

When you diff multiple documents, however, only one source document can have focus
at a time. Consider the following illustration, which shows three source documents
(source1.xml, source2.xml, and source3.xml) and a target document (target.xml).

Figure 137. Example of Document Focus

In this example, the source1.xml document currently has focus. You set the focus on a
given source document by selecting that document from the drop-down list at the top of
the source document window.
When a source document has focus:

Diffs are displayed for that document only, even if you have selected the Merged View
tab for display.

Clicking the remove document button (

) removes that document from the XML
diff calculation.

Symbols Used in the Target Document Window

When diffing multiple documents, Stylus Studio uses an additional set of symbols in the
target document window. These symbols, which are displayed in the side bar of the XML
Diff Viewer window alongside the standard set of symbols described in Symbols and
Background Colors on page 181, indicate the ways in which the change identified in the

196

Stylus Studio User Guide

Diffing Folders and XML Documents

current source document differs from changes to the same node in other source
documents.
Change relative
to current target
and current source
Change in current source
relative to other source
documents

Figure 138. Example of Symbols Used When Diffing Multiple Documents

As shown in Figure 138, symbols in the column closest to the document tree identify the
changes relative to the currently selected source. Here, the edit symbol ( ) indicates that
the value in the target document, White, differs from that in the currently selected source
(which happens to be Black in this example).
The first column of symbols characterize changes in the currently selected source relative
to other source documents. Here, for example, the red exclamation point ( ) indicates
that there are conflicting modifications in other source documents that is, other source
documents contain a value other than Black. As shown in Figure 139, when you click on
a symbol in the first column, Stylus Studio displays

A message describing the precise nature of the change

A menu that identifies the documents in which the change occurs.

Figure 139. Easily Navigate to Changed Nodes in Other Source Documents

Clicking on a document in this menu changes the current focus to that source document,
allowing you to easily navigate to the same node in a different document.

Stylus Studio User Guide

197

Editing and Querying XML

The additional symbols used by Stylus Studio when diffing multiple documents are
described in Table 16.
Table 16. Symbols Used to Specify Changes in Source Documents
Symbol

Description

Meaning

Yellow circle

Modified in other documents The object in the target and

the current source document are the same, but another source
document is different.

Red exclamation
point

Conflicting modification in other documents The object in

the current source differs from that in the target document.
Other source documents differ from both the current source
and target.

Yellow diamond

Same modification in other documents The source

documents all differ from the target document in the same
way.

Yellow equal sign

Unchanged in other documents The current source

document differs from the target, but other source documents
are the same as the target.

so
ur
ce
1.
xm

Consider the example in Figure 140, which illustrates diffing three documents. In this
example, the node in question is circled in red.

l
ge
t.x
m

<abc>

so
ur
ce
3.
xm
l

<xyz>

ta
r

so
ur
ce
2.
xm

<abc>

<123>

Figure 140. Diffing Three Documents

198

Stylus Studio User Guide

Diffing Folders and XML Documents

Notice that:

source1.xml currently

has focus.
source1.xml and the target document node have the same value (<abc>)
The node in question varies in both of the remaining source documents (it is <abc> in
one and <abc> in the other).

Table 17 shows the symbols that might appear based on changing values to the node in
question. The example illustrated in Figure 140 is shown in the first row. As values in the
source documents change, Stylus Studio changes the diff symbol accordingly.
Table 17. Symbols Used to Specify Changes in Source Documents
Symbol

target.xml

source1.xml

source2.xml

source3.xml

<abc>

<xyz>

<123>

<abc>

<xyz>

<jkl>

<mno>

<abc>

<xyz>

<abc>

<xyz>

<abc>

Note Changing the target-source pairing, that is, changing the current source document, affects

the symbols that are displayed.

How to Diff Multiple Documents

To diff multiple documents:
1.

Select Tools > Options > Show Differences > Files from the Stylus Studio menu.
Stylus Studio displays the XML Diff Viewer.

In the source document window, click the add button (

document.
Stylus Studio displays the Open dialog box.

) to add the first source

You can drag and drop a file into the entry field to load the document in the XML Diff
Viewer.

Tip

Navigate to the document you want to load in the XML Diff Viewer.

Click Open.

Repeat Step 2 through Step 4 for additional source documents.

Stylus Studio User Guide

199

Editing and Querying XML

Modifying Default Diff Settings

Default settings for the behavior of the Diff engine and the appearance of diffed
documents and folders are on the Engine and Presentation pages, respectively, of the
Options dialog box. The Engine page, shown here, has settings that determine the
conditions under which Stylus Studio runs the diff automatically, which items in a
document (comments and text, for example) you want the diff engine to ignore, and
settings that allow you to choose diffing algorithm tunings optimized for change
description or time, for example.

Figure 141. Engine Options Page for XML Diff

200

Stylus Studio User Guide

Diffing Folders and XML Documents

Settings on the Engine page are reflected in the Diff editor tool bar, and in the XML Diff
menu, shown here.

Figure 142. XML Diff Menu

Tip You can override Engine page settings using the Diff editor tool bar or the XML Diff menu.
Overrides do not change the settings on the Engine page.

This section covers the following topics:

Opening the Options Dialog Box on page 201

Engine Settings on page 202

Presentation Options on page 204

Opening the Options Dialog Box

To open the Options dialog box:
1.

Click Tools > Options on the Stylus Studio menu.

The Options dialog box appears.

If necessary, expand the tree for Module Settings > XML Diff.

Stylus Studio User Guide

201

Editing and Querying XML

Click the page that contains the settings you want to modify.

To save a changed setting, click OK. Click Cancel to revert to close the dialog box and
revert to the previous settings.

Engine Settings
This section describes the settings that affect the behavior and performance of the Diff
engine.
General
The fields in the General group box affect the initial display of diffed documents and the
conditions, if any, under which Stylus Studio runs the diff automatically.

Automatically expand all diffs By default, Stylus Studio collapses the display of the
diffed documents. If you select this option, all nodes containing diffs are expanded
when the diff is run.

Collapse unchanged blocks By default, Stylus Studio collapses any block that does
not contain any changes to save space in the XML Diff Viewer window. These blocks
are displayed as <unchanged> in the document tree. You might prefer to have the entire
document structure visible, to provide context for changed nodes, for example.

Autorun diff By default, Stylus Studio runs the diff operation if you make a change
to one of the settings on the Engine page of the Options dialog box. You can also
specify that Stylus Studio run the diff operation when the source or target documents
change. If you select If files modified, Stylus Studio runs the diff operation when you
save a source or target file. If neither of these options is selected, you must run the diff
manually. See When Does the Diff Run? on page 180 for more information on this
topic.
Engine Options
The fields in the Engine Options group box affect how Stylus Studio diffs source and
target documents.

Use URI to compare namespaces Controls whether or not URIs are used to
compare namespaces in source and target documents.

Expand entity references Controls whether or not entity references, which in some
cases can include files external to the source or target document, are expanded by the
Stylus Studio diff engine for purposes of comparing one block with another.

202

Stylus Studio User Guide

Diffing Folders and XML Documents

Ignore text formatting characters Controls whether or not text formatting

characters (new line, carriage return, and tab) are ignored when comparing source and
target documents. This option is off by default.
Show differences in Provides granular control of what items in XML documents
are diffed. There are separate settings for comments, text, entities, attributes, and
processing instructions.

Performance
Diffing large, numerous, or complex documents can be time-consuming. Stylus Studio
provides controls that let you choose algorithm tunings that have been optimized for
change description or calculation time.

Autodetect Stylus Studio determines which algorithm tuning to use based on the
number, content, complexity, and size of the source and target documents. Stylus
Studio first tries to use the tuning that is optimized for change description; if it
determines that processing resources are limited, it reverts to the algorithm tuning
optimized for speed. This setting is on by default.

Optimize change description Provides the most economical set of changes

possible. This calculation, though it yields the best results, can be costly in terms of
time and processing resources.

Optimize calculation time Provides the set of changes in the shortest time possible.

Optimize for large documents with few changes Helps speed the diffing of large
(greater than 1MB) documents by folding similar blocks before comparing nodes.
This setting can be used in conjunction with any of the algorithm tuning settings and
is on by default.
Tip The default setting, Autodetect and Optimize for large documents with few changes,

yields the best results when time and processing resources are not considerations.

Stylus Studio User Guide

203

Editing and Querying XML

Presentation Options
Presentation options allow you to modify the settings for the background colors Stylus
Studio uses to identify the types of changes detected in diffed documents and folders

Figure 143. You Can Change Colors Used to Identify Document Changes

You can change the background colors for the following:

Added items

Removed items (that is, items that are present in the target, but are not present in the
source, for example)

Changed items (the same element or attribute, but a different name, for example)

Collapsed items with changes

Running the Diff Tool from the Command Line

In addition to using the Diff tool from the Stylus Studio user interface, Stylus Studio also
provides a commandl line utility, StylusDiff.exe. This command line utility allows you
to perform many of the same functions, and to use many of the same options, as the
graphical Diff tool.

204

Stylus Studio User Guide

Diffing Folders and XML Documents

Restrictions
The following restrictions exist for using StylusDiff.exe:

You cannot use StylusDiff.exe to diff folders

StylusDiff.exe can diff only one pair of documents at a time

Usage
The StylusDiff.exe utility has the following usage:
StylusDiff -source <sourceURI> -target <targetURI>
[-expandPrefixes/collapsePrefixes] [-expandERs/collapseERs]
[-comments/nocomments] [-attributes/noattributes] [-text/notext] [-pi/nopi]
[-er/noer] [-entities/noentities] [-formatting/noformatting] [-fold/nofold]
[-auto/best/fast]

Table 18 describes the usage for the StylusDiff command. For a complete description of
these and other options that affect the XML Diff engine, see Engine Settings on
page 202.
Table 18. StylusDiff Command Line Parameters
Parameter

Description

-source <sourceURI>

The path of the XML document you want to use as the source
document in the diff. Required.

-target <targetURI>

The path of the XML document you want to use as the target
document in the diff. Required.

-output <outputURI>

Saves the differences between the source and target files, if

any, to the file you specify. Output files are saved with a .dff
extension. Optional.

-expandPrefixes
-collapsePrefixes

Whether you want the XML Diff engine to use the URI
(-expandPrefixes) or ignore the URI (-collapsePrefixes)
when comparing namespaces. The default is
-collapsePrefixes.

-expandERs
-collapseERs

Whether you want the XML Diff engine to compare entity

references (-collapseERs) or values referenced by entity
references (-expandERs). The default is -expandERs.

Stylus Studio User Guide

205

Editing and Querying XML

Table 18. StylusDiff Command Line Parameters

206

Parameter

Description

-comments
-noComments

Whether you want the XML Diff engine to compare comments

(-commments) or to ignore comments (-noComments). The
default is -comments.

-attributes
-noAttributes

Whether you want the XML Diff engine to compare attributes

(-attributes) or to ignore attributes (-noAttributes). The
default is -attributes.

-text
-noText

Whether you want the XML Diff engine to compare text

(-text) or to ignore text (-noText). The default is -text.

-pi
-noPI

Whether you want the XML Diff engine to compare

processing instructions (-pi) or to ignore processing
instructions (-noPI). The default is -pi.

-er
-noER

Whether you want the XML Diff engine to compare entity

references (-er) or to ignore entity references (-noER). The
default is -er.

-entities
-noEntities

Whether you want the XML Diff engine to compare entities

(-entities) or to ignore entities (-noEntities). The default
is -entities.

-formatting
-noFormatting

Whether you want the XML Diff engine to compare formatting

characters (-formatting) or to ignore formatting characters
(-noFormatting) when comparing text nodes. The default is
-formatting.

-fold
-noFold

Whether you want the XML Diff engine to fold similar blocks
before diffing (-foldUnchangedBlocks) or to expand and diff
nodes (-diffUnchangedBlocks). The default is
-foldUnchangedBlocks.

-auto
-best
-fast

Controls that let you choose between diffing algorithm tunings

that have been optimized for time (-fast) and thoroughness (best). A third choice, -auto, lets Stylus Studio determine
which tuning to use. The default is -auto.

Stylus Studio User Guide

Using Schemas with XML Documents

Stylus Studio allows you to associate one or more schemas with each XML document. A
schema can be a DTD or an XML Schema.
There are several ways to associate a schema with an XML document:

To associate an external schema with a document, ensure that an XML document is

active. Then, from the Stylus Studio menu bar, select XML > Associate XML with
Schema.

To define an internal DTD, specify it in the XML editor Text tab or Schema tab.

To have Stylus Studio generate a schema, in the XML editor, click the Schema tab. If
the XML document has some contents, Stylus Studio prompts you to indicate whether
you want Stylus Studio to generate a schema from the contents. See Having Stylus
Studio Generate a Schema on page 208.
This section discusses the following topics:

Associating an External Schema With a Document on page 207

Having Stylus Studio Generate a Schema on page 208

Validating XML Documents on page 208

Updating a Documents Schema on page 209

Removing the Association Between a Document and a Schema on page 209

Associating an External Schema With a Document

To associate an external schema with an XML document:
1.

Open the XML document you want to associate with a schema. See Opening Files
in Stylus Studio on page 92.

From the Stylus Studio menu bar, select XML > Associate XML with Schema.

In the Open dialog box that appears, navigate to and select the schema you want to
associate.

Click Open. The selected schema is now associated with the document.

209

Editing and Querying XML

Converting XML to Its Canonical Form

By default, Stylus Studio creates XML that conforms to the W3C XML 1.0
recommendation. You can also convert any XML document to its canonical form. When
you convert XML to its canonical form, the resulting document conforms to the W3C
Canonical XML 1.0 recommendation.
Tip Although you can undo conversion to canonical form, consider using Save As to create

a copy of the XML document prior to conversion.

To convert an XML document to its canonical form:
1.

Open the XML document you want to convert to canonical XML.

Select Edit > Make Canonical XML from the Stylus Studio menu.
Alternative: Click the Make Canonical XML button (
) on the tool bar.
The XML document is converted to its canonical form.

You can undo this operation (Edit > Undo) if necessary.

Querying XML Documents Using XPath

You can use the XML Path Language (XPath) to query XML documents to obtain a subset
of the information in that document. You can also query XML Schema and XSLT,
provided you open the XSLT using the XML Editor. (You cannot query DTD schema
because it is not XML.)
In Stylus Studio, you query XML documents using the XPath Query Editor. To learn more
about XPath and how to use the XPath Query Editor, see Writing XPath Expressions on
page 691.

Printing XML Documents

You can print the raw XML text view of your document. You cannot print the other views
of your document.
To print a document:

210

In your XML document, click the Text tab.

In the Stylus Studio tool bar, click Print

or press Ctrl+P.

Stylus Studio User Guide

Saving XML Documents

To preview your document before you print it, select File > Print Preview from the
Stylus Studio menu bar.
To specify print options for your document before you print it, select File > Print
Setup from the Stylus Studio menu bar.

Saving XML Documents

When you save a document, Stylus Studio saves it in the encoding that is specified in the
initial XML processing instruction.
To save an XML document:
1.

Ensure that the window that contains your XML document is the active window.

From the Stylus Studio menu bar, select File > Save.
Alternatives: Press Ctrl+S or click Save
in the Stylus Studio tool bar.

Options for Saving Documents

The Application Settings page of the Options dialog box contains two options that affect
when and how documents are saved in Stylus Studio. You can choose to have Stylus
Studio

Save modified documents every few minutes. This option is off by default, and has a
default setting of 10 minutes.

Create a backup copy of a document when it is saved.

More About Backup Files

Backup copies are created with a *.bak extension appended to the original document
name when saved to the Stylus Studio file system. For example, the backup copy of
books.xml would be books.xml.bak. If you are saving to an external file system (such as
Raining Data TigerLogic XDMS), the file system manages the backup file name.
Backup files are written to the same file system as the original document. They are not
displayed in the Project window, and they appear in the File Explorer window only if you
change the filter to display *.bak files.

Stylus Studio User Guide

211

Editing and Querying XML

Opening a Backup File

You can open a backup file

From the File Explorer window, by double-clicking the file name or selecting Open
or Open With from the files shortcut menu, for example

From the Project window, by selecting the file and then selecting either

Open Latest Backup from the files shortcut menu (right-click to display), or

Project > Open Documents Latest Backup from the Stylus Studio menu

212

Stylus Studio User Guide

Chapter 3

Converting Non-XML Files to XML

DataDirect XML Converters and custom XML conversions are available only
in Stylus Studio XML Enterprise Suite.
Stylus Studio uses DataDirect XML Converters to convert incoming streams of data
from native formats to outgoing streams of XML, and vice-versa. XML Converters
support standard file formats, including EDI, CSV, binary, and many others. XML
Converters also support the conversion of custom or proprietary formats that you specify
using a custom XML conversion definition.
This chapter describes how to use DataDirect XML Converters to convert standard and
proprietary files to XML in Stylus Studio, how to create your own custom XML
conversion definitions, and how to use files you convert on-the-fly elsewhere in Stylus
Studio as a source for XQuery and XSLT design, for example.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the Custom XML
Conversions module video.
You can read about other video demonstrations for the custom XML conversion definition
module here: http://www.stylusstudio.com/learn_convert_to_xml.html#converttoxml.
A complete list of all the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This chapter covers the following topics:

Introduction on page 214

Custom XML Conversions on page 221

Creating a Custom XML Conversion Definition on page 222

Stylus Studio User Guide

213

Converting Non-XML Files to XML

The Custom XML Conversion Definition Editor on page 225

Parts of an Input File on page 236
Working with Regions on page 238
Working with Fields on page 247
Controlling XML Output on page 255
Using Custom XML Conversion Definitions in Stylus Studio on page 266
The Converter URI Scheme on page 269
Working with EDI Conversions on page 276
Custom XML Conversion Definitions Properties Reference on page 280

Introduction
DataDirect XML Converters are high-performance Java and .NET components that
provide bi-directional, programmatic access to virtually any non-XML file including EDI,
flat files, and other legacy and proprietary formats. DataDirect XML Converters allow
developers to seamlessly stream any non-XML data as XML to industry-leading XML
processing components or to any application. They support StAX, SAX, XmlReader,
XmlWriter, DOM and I/O streaming interfaces, and can be embedded directly for
translation purposes, or as part of a chain of programs including XSLT and XQuery, or
even inside XML pipelines. DataDirect XML Converters maximize developer
productivity and provide a fast, scalable solution for converting between EDI and other
legacy formats and XML.

How XML Converters are Used in Stylus Studio

The DataDirect XML Converters conversion engine is used throughout Stylus Studio to
convert non-XML files to XML and vice-versa. You can access DataDirect XML
Converters:

When you open and save files

In the EDI to XML module (see Chapter 4 Converting EDI to XML for more
information on this module)

As XML pipeline ConvertToXML and ConvertFromXML nodes (see Chapter 14

Building XML Pipelines for more information)

Using the converter:URI scheme

214

Stylus Studio User Guide

Introduction

Example
When you open or save a file in Stylus Studio, you have the option of converting that file
to or from XML using DataDirect XML Converters, as shown in the following
illustration:

Figure 144. Open Using XML Converters Check Box

In the Open dialog box and elsewhere in Stylus Studio, you can choose an XML
Converter for a

Specific file format (like EDI, CSV, dBase, or RTF, for example). See Types of XML
Converters on page 216 for a complete list of standard files supported by the XML
Converters.

Custom file definition created using the Stylus Studio Custom XML Conversion
Definition Editor. You can create custom XML conversion definitions to handle
proprietary file formats or extensions to formats already supported by DataDirect
XML Converters.

XML Converters Run-Time Components

DataDirect XML Converters are also available as a standalone run-time component on
both Java and .NET platforms. DataDirect XML Converters are bundled with Stylus
Studio X14 XML Enterprise Suite.
This chapter describes how to use DataDirect XML Converters in Stylus Studio. To learn
about the DataDirect XML Converters standalone components for Java and .NET, see the
Stylus Studio User Guide

215

Converting Non-XML Files to XML

DataDirect XML Converters documentation at

http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

Other Ways to Convert Files to XML

In addition to using XML Converters, you can convert files to XML using Stylus Studio
document wizards Stylus Studio document wizards help you convert XML Schema,
DTD, and HTML to XML. See Using Document Wizards to Create XML on page 139
for more information.

Types of XML Converters

DataDirect XML Converters support numerous file formats, as shown in the following
table.
Table 19. Types of Files Handled by XML Converters

216

File Type

Description

Base-64

Converts any file, text or binary (such as an image), into a

XML document with a single element containing the Base-64
encoded content of the input file.

Binary

Similar to the Base-64 XML Converter, except with

hexadecimal output. Other options allow output in other
bases, such as decimal or octal or even binary.

Comma-separated
value (CSV)

Converter for comma-separated values (CSV) files. Supports

multiple encodings and options to tune the quote and escape
characters. Supports delimiters besides commas.

Custom

Custom or proprietary file formats described using a Stylus

Studio custom XML conversion definition.

dBase

Support for dBase II, III, III+, IV, and V formats.

Data Interchange
Format (DIF)

Data Interchange Format (DIF) is a spreadsheet-based file

format. There are also XML Converters for SDI and SYLK.

DotD

Support for Progress Softwares OpenEdge text dump file

format.

Stylus Studio User Guide

Introduction
Table 19. Types of Files Handled by XML Converters
File Type

Description

EDI

Automatically detects and parses ATIS, Cargo-IMP,

EANCOM, EDIFACT, Edig@s, HIPAA, HL7, NCPDP,
PADIS, TRADACOMS, and X12 EDI message types, with
options for custom message types and message extensions to
cover proprietary EDI-based formats.

JavaProps

Support for Java .properties file format, which are used for
program configuration, translation, and data storage.

JSON

Uses the algorithms on the JSON.org website to read from

XML and write to JSON (JavaScript Object Notation), and
vice-versa.

Line

Reads in text one line at a time, wrapping an element around

each line and escaping any embedded & or > or < symbols.

Pyx

Support for this line-oriented notation for expressing treeoriented data.

RTF

Converts rich-text format (RTF) into XML, and vice versa.

SDI

Super Data Interchange (SDI) is another popular spreadsheetbased file format. There are also XML Converters for DIF and
SYLK.

SYLK

SYLK (Symbolic Link) is another popular spreadsheet-based

file format. There are also XML Converters for DIF and SDI.

TAB

Tab-separated values format commonly associated with MS

Excel spreadsheets.

WinIni

Converter for Windows .ini configuration files.

WinWrite

Converter for Microsoft WinWrite files; renders XHTML.

Stylus Studio User Guide

217

Converting Non-XML Files to XML

XML Converters Can Be Configured

Each of the DataDirect XML Converters has numerous properties that allow you to
configure the converter to suit your needs, like those for the EDI XML Converters shown
here:

Figure 145. Select XML Converter Dialog Box

Some XML Converters, for example, let you specify the line separator character, escape
character, root element name, and other aspects of the output format.
See Chapter 4, XML Converters Properties, in the DataDirect XML Converters
Users Guide and Reference for more information. Documentation for DataDirect XML
Converters is available:

In the \doc folder for DataDirect XML Converters where you installed Stylus Studio
\components\XML Converters for .NET\doc, for example

On the DataDirect XML Converters web site:

http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp

218

Stylus Studio User Guide

Introduction

Using XML Converters to Open a Non-XML File as XML

To open a non-XML file as XML using XML Converters:
1.

Select File > Open from the Stylus Studio menu.

Stylus Studio displays the Open dialog box.

Navigate the file system that contains the file you want to open as XML. If necessary,
change the value in the Files of type field to filter the files that are displayed.

Select the Open using XML Converters check box.

Figure 146. Open Using XML Converters Check Box

Click the Open button.

Stylus Studio displays the Select XML Converter dialog box. (See Figure 145.)

Select the XML Converters you want to use to convert your non-XML file to XML.

Optionally, change the default values of the conversion properties to be used when
converting your file. See Chapter 4, XML Converters Properties, in the DataDirect
XML Converters Users Guide and Reference if you need help with this step:
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

Click OK.
Stylus Studio converts the file you specified in step 2 to XML using the DataDirect
XML Converters you selected in step 5. The file is displayed in a new instance of the
XML Editor.

Stylus Studio User Guide

219

Converting Non-XML Files to XML

Saving an XML File in Another Format

Most DataDirect XML Converters are bi-directional you can use them to convert native
file formats to XML, and vice versa. (Custom XML conversions you define using the
Stylus Studio Custom XML Conversion Definition Editor convert proprietary files to
XML only.) In order to save an XML file in another format, however, the XML file you
are saving needs to have an XML Schema consistent with that expected by the XML
Converters. There are a number of ways to achieve this in Stylus Studio:

Save back a previously converted file. Imagine using the CSV XML Converters to
convert bikes.txt to bikes.xml. You could modify the data in bikes.xml and save it
back using the CSV XML Converters. Stylus Studio could save the XML file as CSV
as long as you made no changes to the document structure (adding no new elements
or attributes, for example).

Use a Document Wizard to create an XML Schema from an EDI message type (ATIS,
Cargo-IMP, EANCOM, EDIFACT, Edig@s, HIPAA, HL7, NCPDP, PADIS,
TRADACOMS, or X12, for example), and use that XML Schema as the target
document in an XQuery or XSLT mapping. The XML document resulting from the
XQuery or XSLT transformation based on that XML Schema would conform to the
XML Schema expected by the EDI XML Converters.
For more information on Document Wizards, see Using Document Wizards to
Create XML on page 139. For more information about working with EDI files as
XML, see Working with EDI Conversions on page 276.

220

Stylus Studio User Guide

Custom XML Conversions

In Stylus Studio, you can create a custom XML conversion definition that allows the
DataDirect XML Converters engine to convert proprietary files and extensions to
standard formats to XML.
You create a custom XML conversion definition by selecting an input file and then using
the Custom XML Conversion Definition Editor, shown in Figure 147, to specify the
properties you want to use to convert that file and other files that share the same format.

Figure 147. Custom XML Conversion Definition Editor

The Custom XML Conversion Definition Editor displays information read from the input
file, as well a number of other properties you can specify (such as whether or not you want
element names based on the files first row, for example) that are used when the file is
converted from its native format to XML.

Stylus Studio User Guide

221

Converting Non-XML Files to XML

When to Create a Custom XML Conversion Definition

Consider creating a custom XML conversion definition any time

You need to convert a file that does not conform to one of the standard file types
already supported by DataDirect XML Converters

You want to exercise more control over the XML that is output by the conversion

Converting Non-Conforming EDI

The Custom XML Conversion Definition Editor lets you create custom conversion
definitions for many file types, including EDI. You can learn more about using the
Custom XML Conversion Definition Editor to convert custom EDI formats here:
Working with EDI Conversions on page 276.
However, Stylus Studio and XML Converters both support the Standard Exchange Format
(SEF), which allows you to defined extensions to EDI standards. The Stylus Studio EDI
to XML module allows you to easily create SEF files to manage conversion of custom
EDI formats. Its graphic user interface can simplify the process of converting nonconforming EDI to XML and vice versa. See Chapter 4 Converting EDI to XML for
more information.

Creating a Custom XML Conversion Definition

This section describes how to create and save a custom XML conversion definition (.conv
file) in Stylus Studio.

Choosing an Input File

The input file you specify when creating a custom XML conversion definition can be any
type. If you plan to use the custom XML conversion definition to convert other non-XML
files of this type, the input file should be representative of that broader class of files files
with the same extension (.txt, for example), encoding, numbers and types of regions, and
so on. You can always fine-tune the custom XML conversion definition to accommodate
characteristics that are not embodied in the input file, but as a general rule, use a file that
is as close to others of its type as possible.
Stylus Studios heuristics are also used to determine the field separator character being
used (if any), the delimiting character being used (if any), and so on. The assumptions

222

Stylus Studio User Guide

Creating a Custom XML Conversion Definition

Stylus Studio makes are reflected in the Properties window in the Custom XML
Conversions Editor once the input file is opened.

Specifying File Settings

Stylus Studio also allows you to specify the files

Encoding (Windows-1252 or ANSI, for example)

Layout (line-oriented or fixed-width, for example)

Unless you are certain of the files encoding and layout, consider leaving the default
settings as they are Stylus Studio will determine encoding and layout properties when
it reads the file.

How to Create a Custom XML Conversion Definition

To create a custom XML conversion definition (.conv file):
1.

Select File > New > Custom XML Conversion from the Stylus Studio menu.
The New Custom XML Conversion Definition dialog box appears.

Figure 148. New Custom XML Conversion Definition Dialog Box

Click the browse button ( ) and select the file you want to use to configure the
custom XML conversion definition settings. See Choosing an Input File on
page 222 if you need help with this step.

Stylus Studio User Guide

223

Converting Non-XML Files to XML

The Open dialog box appears. By default, the Files of Type field filter is set to display
.txt, .edi, .csv, .tab, .log, and .bin files.
The file you select should be representative of other files of this type that you wish to
convert to XML using the custom XML conversion definition you are creating.

Tip

Click the Open button.

Stylus Studio displays the file URL in the first field of the New Custom XML
Conversion Definition dialog box.

Optionally, change the default file encoding and layout settings. See Specifying File
Settings on page 223 if you need help with this step.

Click OK.
Stylus Studio displays the file you selected in the Custom XML Conversion Editor.

Examine the file and its properties as it was read into the Custom XML Conversion
Editor by Stylus Studio.

Modify the file layout, its regions, and its fields as needed. See Working with
Regions on page 238 and Working with Fields on page 247 if you need help with
this step.

Modify the properties that govern XML output as needed. See Controlling XML
Output on page 255 if you need help with this step.

Click the Preview Results button ( ).

Stylus Studio displays the Save As dialog box.

10.

Enter a name for the custom XML conversion definition and click Save.

11.

If the results are not what you expect, return to step 7 and to step 8. You might also
considering revisiting the input file, making fundamental changes there, and then
reloading it.

The steps in this process are described in greater detail in the following sections.
Tip Once you have created and saved a custom XML conversion definition, you can use it to

open other non-XML files of the same type, just as you would with any other DataDirect
XML Converter. See Using XML Converters to Open a Non-XML File as XML on
page 219 for more information.

224

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

You use the Custom XML Conversion Editor, shown in Figure 149, to build a custom
XML conversion definition. The Custom XML Conversion Editor appears when you
create a new custom XML conversion definition, or open an existing one (a .conv file).

Figure 149. Custom XML Conversion Editor

The input file is displayed in a document pane; properties that both describe the existing
file (encoding and size, for example) and define the XML output that will be generated
when converting this file (root and field element names, and whether or not you want the
XML to be indented, for example) are displayed in the Properties window. The schema
pane shows a representation of the XML Schema that will be output for the converted file.
Finally, in addition to current row and column position, note that the status bar also shows
the Unicode value of the current character.

Stylus Studio User Guide

225

Converting Non-XML Files to XML

This section describes the main features of the Custom XML Conversion Editor,
including how it interacts with the XML Converters engine. This section covers the
following topics:

Document Pane on page 226

Properties Window on page 233

Schema Pane on page 235

Document Pane
The document pane displays the input files layout, including spaces, field separators, and
control characters. The input files appearance in the document pane is determined, in
part, by its format.
This section covers the following topics:

Example .txt Files on page 226

Display of Delimiting and Control Characters on page 228

Field Names on page 229

Document Pane Display Features on page 230

Moving Around the Document on page 232

Example .txt Files

Stylus Studio uses slightly different displays for character-separated and fixed-width .txt
files. Consider this file, which uses commas as the field separator:
Make,Model,Year,Mileage
BMW,R1150RS,2004,14274
Kawasaki,GPz1100,1996,60234
Ducati,ST2,1997,24000
Moto Guzzi,LeMans,2001,12393
BMW,R1150R,2002,17439
Ducati,Monster,2000,15682
Aprilia,Futura,2001,17320

226

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

Figure 150 shows how this character-separated input file appears in the Custom XML
Conversion Editors document pane. By default, Stylus Studio aligns columns and fills the
empty cells of the shorter rows with a light blue to aid readability:

Figure 150. Character-Separated File with Aligned Fields

You can remove these spaces from the display and view the file in its native format by
clicking the Align Fields button ( ) on the tool bar, or by selecting
CustomXMLConversion > Align Fields on the menu. This results in the layout shown in
Figure 151.

Figure 151. Character-Separated File without Aligned Fields

Fixed-width files are displayed in a slightly different fashion. Consider this fixed-width
input file:
Deep-sea octopus
Bathypolypus arcticus http://www.dal.ca/~ceph/TCP/barctic.html
Blue-ringed octopus
Hapalochlaena lunulatahttp://www.dal.ca/~ceph/TCP/lunulata.html
Caribbean reef octopusOctopus briareus
http://www.dal.ca/~ceph/TCP/obriar.html
Giant octopus
Octopus dofleini
http://www.dal.ca/~ceph/TCP/giant.html
Common octopus
Octopus vulgaris
http://www.dal.ca/~ceph/TCP/Octopusvulgaris.html
Red octopus
Octopus rubescens
http://www.dal.ca/~ceph/TCP/redocto.html
Octopus Salutii
Octopus salutii
http://www.dal.ca/~ceph/TCP/Osalutii.html
Octopus Macropus
Octopus macropus
http://www.dal.ca/~ceph/TCP/Omacropus.html

Stylus Studio User Guide

227

Converting Non-XML Files to XML

In a fixed-width file, the empty cells represent actual values (spaces) in the input file. In
the second row of this input file, for example, there are three spaces between the first and
second columns:

Figure 152. Fixed-Width File

Display of Delimiting and Control Characters

Stylus Studio displays delimiting and control characters in a way that distinguishes them
from plain text values.

Delimiting characters, like the comma used in the example in Figure 150, are
displayed with a dark blue background. For files that include sub-fields or arrays (like
EDI, for example), the sub-field separator character is shown in a different shade of
blue. Sub-sub-fields delimiting characters are shown in a shade of purple.

Control characters (line feeds and carriage returns, for example) are shown using their
abbreviated ASCII value. A carriage return (0x0D) line feed (0x0A) is shown as
,
for example. ASCII abbreviations are aligned vertically, to preserve space, as shown
in this representation of the ASCII value for tab (0x09): .
Stylus Studio understands all Unicode characters,. When editing Line-Oriented
Region and Field Name values in the Properties window, you can enter mnemonic
values for the C1 and C0 control characters in the following ranges:

C0 control characters with a value from >= 0x00 to <= 0x1F

C1 control characters with a value from >=0x80 to <= 0x9F

For example, you could enter TAB or HT in the Field Separator field in the Properties
window, and Stylus Studio would correctly interpret that value. For a list of
commonly used control characters, see Specifying Control Characters on page 311.

Characters that are discarded from output (like line terminators such as CR and LF
and comment lines) are displayed against a gray background.

228

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

You can hide control characters by clicking the Toggle Control Characters button ( )
on the tool bar, or by selecting ConvertToXML > Toggle Control Characters from the
menu.

Field Names
User-defined field names values that Stylus Studio uses to create the element names in
converted XML are displayed in green, as shown here:

Figure 153. User-defined Field Names are Shown in Green

You can edit these names

In-place, by double-clicking the field name

In the Field Element Name field of the Properties window

If the field names are taken from a row within the file itself, Stylus Studio displays a blue
arrow in the document pane margin to indicate this.

Figure 154. Blue Arrow Indicates Field Names Taken from the File

See Naming Fields on page 247 to learn more about naming fields for XML output by
custom XML conversion definitions.

Stylus Studio User Guide

229

Converting Non-XML Files to XML

Document Pane Display Features

In addition to aligning fields in character-delimited files, the Custom XML Conversion
Editors document pane has several other features that aid readability.
Ruler
You can display a ruler that identifies each column:

Figure 155. Ruler Helps Identify Columns

To display the ruler, click the Toggle Ruler button (

) on the tool bar, or select
CustomXMLConversion > Toggle Ruler from the menu.
Displaying Pattern Matches
You can define match patterns using regular expressions to control which rows are
converted to XML and, optionally, the name to use for these rows. You can highlight rows
that match the patterns that you have defined, as shown here:

Figure 156. Matching Rows Are Displayed in Yellow

To highlight matching rows, click the Highlight Matching Rows button ( ) on the tool
bar, or select CustomXMLConversion > Highlight Matching Rows from the menu.
230

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

Matching rows are displayed in light yellow, with a green check in the panes margin. A
red X identifies rows that do not match the current pattern. Gray squares identify rows that
match a pattern other than the pattern defined for the row that currently has focus. See
Specifying Multiple Match Patterns on page 259 for more information on this feature.
Tip Only rows that match the same pattern that the current row matches are highlighted. Also,

tooltips appear when you hover the pointer over the match symbols. These tooltips
display the pattern that the row matches.
See Pattern Matching on page 257 to learn more about using regular expressions to
define match patterns.
Grid Lines
The document pane displays both vertical and horizontal lines by default; you can
hide/show them independently. In the example shown in Figure 157, horizontal lines are
hidden from the display:

Figure 157. You Can Hide Horizontal and Vertical Grid Lines

To hide horizontal and vertical grid lines, click the Toggle Horizontal Grid Lines ( )
and/or Toggle Vertical Grid Lines ( ) buttons on the tool bar, or select ConvertToXML >
Toggle Horizontal Grid Lines and/or Toggle Vertical Grid Lines from the menu.
Tip Hiding horizontal lines while displaying the ruler is an effective way to quickly scan

columns.
Fonts
By default, the input document is displayed using the Courier New font in 12pt. You can
change the display font to suit your personal preference using the Edit > Change Font and
Edit > Font Size menus.

Stylus Studio User Guide

231

Converting Non-XML Files to XML

Moving Around the Document

You can move the cursor around the document using

The Space bar on your keyboard

The directional arrows and Page Up, Page Down, Home, and End keys on your
keyboard

Your mouse (click on the character on which you want to place the cursor)

The Go To dialog box

Figure 158. Use the Go To Dialog Box to Navigate the Document

Using Go To
You use the Go To dialog box to jump to a specific location in the file you are using to
create your custom XML conversion definition. You can use it to move the cursor to a
specific

Position in the file

Region

Position or row within a region

Column within the current row

When you first display the Go To dialog box, values in the Go To fields reflect the cursors
current location within the file. The values in the Maximum fields display the maximum
values for each category (file size, number of regions, and so on) for the portion of the file
read into the Custom XML Conversion Editor Editor by Stylus Studio.

232

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

To display the Go To dialog box, select Edit > Go To from the menu.

Properties Window
The Properties window, like the one shown in Figure 159, displays information about the
input file, as well as settings that Stylus Studio will use convert files to XML.

Figure 159. Properties Window for a .txt File

Information in the Properties window includes

Information read or inferred from the input file when it is first opened in the Custom
XML Conversion Editor. Examples include the file name, file size, and number of
characters that were read. Some values, such as the type of encoding, can be edited.
Informational fields that cannot be edited are identified with a blue circle: .

Values you want the XML Converters engine to use when converting this input file
and other files of this type to XML. Output properties include the root element name,
the namespace and namespace prefix, and the field element name. These fields are
identified with a green arrow over a document icon:
.

Stylus Studio User Guide

233

Converting Non-XML Files to XML

How Properties are Organized

Properties displayed in the Properties window are organized in the following categories:

Input File read-only information read or inferred from the input file, and editable
properties that affect XML output. These properties affect the file as a whole when it
is converted to XML. Input file properties are identified by this icon:
.

XML Output URL properties that affect the XML document created by the custom
XML conversion definition, including the name you want to use for the root element,
and whether or not you want to indent the XML. Output URL properties are identified
by this icon:
.

Region Type read-only information inferred from the input file, and editable
properties that affect XML output. Examples include line terminating and escape
characters. These properties affect a contiguous portion of the file (that is, a given
line-oriented or fixed-width region) when it is converted to XML. Region properties
are identified by this icon: .

Row Element Name properties that affect which rows of the input file are output to
XML and how they are output, including the name you want to use for the row. Row
properties are identified with this icon:
.

Field Element Name read-only information read or inferred from the input file, and
editable properties that affect XML output. These properties affect only fields in a
given region of the file when it is converted to XML. Field properties are identified
by this icon:
.
Note Informational properties, that is, properties that do not affect XML output, are displayed
with the following icon: . These properties are displayed when you click the Toggle
Informational Properties button.

Properties for Fixed-Width and Line-Oriented Input Files

Fixed-width and line-oriented input files have different properties line-oriented
properties include the line terminator and field separator characters, and fixed-width files
have a row length, for example. See Custom XML Conversion Definitions Properties
Reference on page 280 to learn more about individual properties.

234

Stylus Studio User Guide

The Custom XML Conversion Definition Editor

Schema Pane
The schema pane displays a representation of the XML Schema for the XML document
that will be output when the input file is converted to XML.

Figure 160. Schema Pane Shows Output Schema Representation

You can double-click on a row element to display the Set Node and Match Pattern dialog
box, shown in Figure 161. This functionality provides an alternative to editing the row
name and specifying a match pattern in the Properties window. (To learn more about
patterns and how to use them in your custom XML conversion definitions, see Pattern
Matching on page 257.)

Figure 161. Set Node and Match Pattern Dialog Box

You can also edit schema node names directly in the schema pane just click twice to
place the node name in edit mode.
See Rows on page 237 to learn more about specifying conversion properties for rows.

Stylus Studio User Guide

235

Converting Non-XML Files to XML

Parts of an Input File

Input files displayed in the Custom XML Conversion Editors document pane consist of
regions, rows, and fields. Each section has its own set of properties. Some, like Region
Type, are read or inferred from the file; others, like Region Element Name, are values you
provide that affect the XML output.
This section covers the following topics:

Regions on page 236

Rows on page 237

Fields on page 238

Regions
A region is the largest organizational component in an input file. Regions are interpreted
by Stylus Studio when the input file is first read into the Custom XML Conversion Editor.
You can use the editor to define your own, as well.
An input file can contain one or more regions; every input file has at least one region that
starts at offset 0. Multiple regions are common in binary files, which often contain a fixedsize header and then one or more records containing the actual data. Regions are fixed in
size and cannot repeat.
In the Custom XML Conversion Editor, regions are numbered, starting with 1, followed
by the row number. For example, in an input file with two regions, you might see rows
labeled as follows: 1:1, 2:1, 2:2, 2:3, and so on, as shown here:

Figure 162. Rows in Regions Are Numbered Independently

236

Stylus Studio User Guide

Parts of an Input File

Region Types
Regions can be fixed-width or line-oriented. You can also set the Region Type property
to No-output. Regions that are marked as No-output are grayed out in the Custom XML
Conversion Editor, and they are not converted to XML.

Managing Regions
Stylus Studio provides tools that let you create new regions, and join one region with
another. You can also change a regions type, define different line terminators across
regions, and mark a region so that it is excluded from output. For information on these and
other topics, see Working with Regions on page 238.

Rows
A row is equivalent to a record, line, or tuple in the input file; a row is made up of fields.
An example of a row is an employee record; examples of fields in an employee record
include employee_id, last_name, first_name, and so on.
Every region can have one or more rows. (A region cannot be empty.) In addition, a region
can have multiple row types. Rows are selected for conversion to XML based on the
match patterns expressed in the Match Pattern field of the Properties window. See
Omitting Regions and Fields, and Rows on page 256 for more information.
Rows in a fixed-width region have the same width as the region itself; fields within each
row are defined by a fixed number of columns. Stylus Studio uses a default value of 80
characters for row length in fixed-width regions, but you can adjust this as required from
within the Custom XML Conversion Editor. See Adjusting Fixed-Width Regions on
page 241 for more information.
In a fixed-width region, you can

Explicitly specify the fields within a row

Adjust the size of the fields you specify

In a line-oriented region, fields are separated by a separator character or string. These
characters are inferred by Stylus Studio when it first reads the file, but you can change
these and other characters if needed.
See Working with Fields on page 247 for more information.

Stylus Studio User Guide

237

Converting Non-XML Files to XML

Fields
A field is one or more columns in a row that contains data. Each different row type has its
own independent set of fields. An example of a field in an employee record is
employee_id.
Stylus Studio supports many data types (string, Boolean, number, date, time, and so on)
and recognizes many different input formats (like different date formats, for example).
Properties vary based on data type the Base property, for example, is applicable only to
Number data types.
You can define your own fields in fixed-width input files. See Defining Fields on
page 250 for more information.

Component and Sub-Component Fields

Some file formats, including many EDI dialects, allow fields to be subdivided into arrays,
sub-fields, or composite fields. Collectively, these fields are referred to as component
fields in custom XML conversion definitions, and they are fully supported, both in terms
of recognition and output. You can name the container element using the Component
Element Name and Sub-Component Element Name properties.

Working with Regions

This section describes some of the features you can use to work with input file regions. It
covers the following topics:

Converting the Region Type on page 239

Adjusting Fixed-Width Regions on page 241

Defining and Joining Regions on page 243

Controlling Region Output on page 246

238

Stylus Studio User Guide

Working with Regions

Converting the Region Type

The Region Type field in the Properties window displays information about the type of
region Stylus Studio inferred when the file was first read. Its value is either Fixed-width,
Line-oriented, or No-output.
Tip Information about No-output regions is not displayed in the Properties window.

Regions with CR/LF control characters are interpreted as line-oriented regions. There
might be occasions, however, when you want to change the region type from line-oriented
to fixed-width, or vice versa. This section describes the tools you can use to change a
region from one type to another.
Consider the following file fixed-width file:
Make
BMW
Kawasaki
Ducati
MotoGuzzi
BMW
Ducati
Aprilia

Model
R1150RS
GPz1100
ST2
LeMans
R1150R
Monster
Futura

Year
2004
1996
1997
2001
2002
2000
2001

Mileage
14274
60234
24000
12393
17439
15682
17320

It is a simple .txt file with fields (Make, Model, and so on) that have been created using
spaces. Each new row was created using the Enter key in the text editor, resulting in
CR/LF control characters at the end of each line that cause Stylus Studio to interpret the
file as a single line-oriented region, like this:

Figure 163. Fields are Aligned by Default

For display purposes, we can remove the spaces Stylus Studio has inserted for readability
(the cells with the light blue shading) by clicking the Align Fields ( ) button. This

Stylus Studio User Guide

239

Converting Non-XML Files to XML

results in a display that resembles the source (Figure 164), but Stylus Studio still
considers the region to be line-oriented.

Figure 164. Turning Off Align Fields Can Aid Readability

When you convert a line-oriented region to a fixed-width region, Stylus Studio removes
spaces it added for readability and depicts only the spaces in the original input file used
to create the fields and the field values themselves, as show in Figure 165.

Figure 165. Line-Oriented Regions Converted to Fixed-Width

By default, Stylus Studio displays fixed-width files using an 80-character row. This
accounts for the input files appearance when it is first displayed as a fixed-width file if
you scan the document, you can see that all of the files original information, including
the CR/LF control characters has been retained, but that the formatting differs the
original input file had eight rows; now it has four rows of 80 characters.
Tip You can adjust the width of fixed-width regions. See Adjusting Fixed-Width Regions

on page 241.

240

Stylus Studio User Guide

Working with Regions

How to Convert a Region Type

To convert a region type:
1.

Place the cursor anywhere in the region you want to change.

Click the Convert to Fixed-Width Region ( ) or Convert to Line-Oriented Region

( ) button. These actions are also accessible from the CustomXMLConversion
menu and the shortcut menu in the Custom XML Conversion Editor.

If you have converted a line-oriented region to a fixed-width region, adjust the row
length as needed. See Adjusting Fixed-Width Regions on page 241.

Adjusting Fixed-Width Regions

If you specify the layout of the file you are converting as fixed-width, Stylus Studio uses
a default row length of 80 characters. (If you let Stylus Studio determine the file layout,
Stylus Studio will attempt to determine record length based on the line terminating
character, if any.) You might need to adjust the row length of a region if your input file
uses a different row length, or when converting a line-oriented region, like the one shown
in Figure 166, to fixed-width.

Figure 166. Line-Oriented Region

There are several ways to specify the row length for a fixed-width region:

Using the Row Length property simply change the default value, 80, to the value
that is appropriate for the current region and press Enter.

Dragging the document pane to the left or right move the pointer to the right border
of the document pane. When it changes shape, press and hold mouse button 1 and
drag the right border of the grid until the input files fields are aligned.

Holding the Shift key and pressing the right arrow (to add width) or the left arrow (to
decrease width).

Stylus Studio User Guide

241

Converting Non-XML Files to XML

Each of these methods lets you explicitly set the row length. Alternatively, you can specify
a Line Terminator character manually, as shown in Figure 167.

Figure 167. Manually Setting the Line Terminator Character

Specifying a Line Terminator character means that the rows in the region can be of
variable length, based on the where the specified Line Terminator character occurs in the
record.
Tip When you specify a Line Terminator character for a fixed-width region, the value shown
in the Row Length property represents the value of the longest row in the region.

Example
After converting the line-oriented region shown in Figure 166 to fixed-width, it looks like
this:

Figure 168. Line-Oriented Region Converted to Fixed-WIdth

242

Stylus Studio User Guide

Working with Regions

Figure 166 shows the same fixed-width file after it has been resized by dragging the
document pane.

Figure 169. Resized Fixed-Width Region

Defining and Joining Regions

An input file can contain any number of regions; fixed-width and line-oriented regions can
exist in the same file. The Custom XML Conversion Editor provides tools that allow you
to define new regions and join existing ones.
This section covers the following topics:

Defining a Region on page 243

Joining Regions on page 246

Defining a Region
When you define a region in an input file, Stylus Studio splits the region at the current
cursor location. The new region starts with the character on which the cursor resided when
the region was defined, but it can be of either type fixed-width or line-oriented
regardless of the type of the original region.
Consider the following input file:
# Bike Inventory Overview 2004-10-01 09:00:07EDT
Make,Model,Year,Mileage
BMW,R1150RS,2004,14274
Kawasaki,GPz1100,1996,60234
Ducati,ST2,1997,24000
Moto Guzzi,LeMans,2001,12393
BMW,R1150R,2002,17439
Ducati,Monster,2000,15682
Aprilia,Futura,2001,17320

Stylus Studio User Guide

243

Converting Non-XML Files to XML

By default, Stylus Studio reads this as a file with a single region. You might decide you
want your XML to distinguish headers from actual records and treat the two accordingly
(not generating headers as XML, for example).
When you define a new region, the Custom XML Conversion Editor renumbers all the
rows, using a region:row number format. In addition, each region is displayed with its own
field name row, which is displayed in light green with the default field element name,
field, as shown in Figure 170.

Figure 170. Regions Are Numbered and Colored Differently

Field and row values are independent across regions. For example, the <row> element
might be <reg1>, <reg2>, and so on for each of the regions in an input file.
To define a region:

244

Place the cursor in the document pane on the character with which you want to start
the new region.

Click the Start New Region Here ( ) button, or select CustomXMLConversion >
Start New Region Here from the Stylus Studio menu.

Stylus Studio User Guide

Working with Regions

Stylus Studio displays the Start New Region dialog box.

Figure 171. Start New Region Dialog Box

Choose the type of region you want to create (line-oriented, fixed-width, or nooutput).

Choose where you want the new region to start (at the current row, or at a specific
number of bytes from the start of the file).
If the .conv file you are creating will be used with different input files, it is possible
that the line lengths could vary from file to file, changing the byte offset. Consider
using the row setting (the default) for the Begin New Region property in this case.

Tip

Click OK.

Stylus Studio User Guide

245

Converting Non-XML Files to XML

Joining Regions
You can join regions that you define as well as regions that Stylus Studio interpreted when
it first read the input file. You can join the current region to either adjacent region the
previous region, or the next region.
The region type after the join operation depends on whether you are joining with the
previous region or the next region.The region you are joining assumes the type of the
region to which it is being joined.
Table 20. Region Type After Joining Regions
Region Joined With

Resulting Region Type

The region you are using to perform the join

The region to which you are joining

To join a region:
1.

Place the cursor anywhere in the region you want to join with another region.

Click the Join with Previous Region ( ) or Join with Next Region ( ) button.
These actions are also accessible from the CustomXMLConversion menu and the
shortcut menu in the Custom XML Conversion Editor.
Stylus Studio joins the region you specified in step 1with the adjacent region.

Controlling Region Output

By default, Stylus Studio generates output for all fixed-width and line-oriented regions.
No-output regions are never converted to XML. In addition to pattern matching, which
controls whether or not individual rows in a region are output based on a pattern you
define, you can omit entire regions from output by selecting Yes from the Omit from
Output drop-down list in the Region Type section of the Properties window.

246

Stylus Studio User Guide

Working with Fields

This section describes some of the features you can use to work with input file fields. It
covers the following topics:

Naming Fields on page 247

Defining Fields on page 250

Component and Sub-Component Fields on page 253

Naming Fields
Every field in an input file including fields in the same region and row can have its
own field element name. All field element names (<field> is the default) include the
namespace prefix in the XML output if one was specified.
Field names are determined by two properties Element Name Source in the Region
Type properties, and Field Element Name, as shown in Figure 172.

Figure 172. Sources for Field Names in XML Output

The Element Name Source indicates the origin of the field name used in the XML output
when converting the input file. The Field Element Name property specifies the actual
value used to name the <field> element.

Stylus Studio User Guide

247

Converting Non-XML Files to XML

Using the Element Name Source Property

There are three values for the Element Name Source property:

User-Supplied Specifies that you will supply names for the <field> element. You
can do this by editing the Field Element Name property, or by double-clicking the
field element name in the document pane to edit the field name directly in the
document pane.
The default value of the Field Element Name property is field. If you use other values
for the Element Name Source property, Stylus Studio provides the values for the Field
Element Name property.
User-Supplied is the default setting for the Element Name Source property.

From First Row You can use this setting to take <field> element names from the
first row in the region. If you have used the Rows to Skip property to skip rows in a
region, the first available region is used to supply the <field> element names.
Consider the following input file:
Make:Model:Year
BMW:R1150RS:2004
MZ:Scorpion:1995
Ducati:ST2:1997

If you set Element Name Source to From First Row, the XML output uses Make,
Model, and Year for the <field> element names, as shown here:
<?xml version="1.0" encoding="utf-8"?>
<root>
<row>
<Make>BMW</Make>
<Model>R1150RS</Model>
<Year>2004</Year>
</row>
<row>
<Make>MZ</Make>
<Model>Scorpion</Model>
<Year>1995</Year>
</row>
<row>
<Make>Ducati</Make>
<Model>ST2</Model>
<Year>1997</Year>
</row>
</root>

You can specify any row as the source for field names using the Get Field Names from
This Row from the rows shortcut menu.

248

Stylus Studio User Guide

Working with Fields

WS-EDI Standard This setting allows rows and fields to be named based on the WS-

EDI Standard level 0. See http://www.ws-edi.org for more information on this

standard.

More About Using Rows for Field Names

When you use an existing row as the source for field names in the XML output, Stylus
Studio changes the display of that row in the document pane to a darker blue to indicate
this, as shown here:

Figure 173. Using a Row for Field Names

In addition, preceding rows in that region, if any, are grayed out, and the value of the Rows
to Skip field in the Region Type properties changes to reflect this.
In the event that the first row has fewer names than there are fields in one or more
subsequent lines in the file, Stylus Studio names the extra fields <fieldn>, where n is the
field number relative to other fields in the row. Also, if the values in the row are not valid
XML identifiers, they are converted using the following rules:

Whitespace and nulls are trimmed from both ends

SQL/XML rules are used, except that underscores (_) are not converted to _x005F_
symbols

Beyond these exceptions, strict rules are used. See section 9.1 (page 91) of
http://www.sqlx.org/SQL-XML-documents/5FCD-14-XML-2004-07.pdf.

How to Name Fields

To provide user-supplied field names:
1.

Display the Properties window if it is not already displayed (click View > Properties
on the Stylus Studio menu).

Place the cursor anywhere in the field you want to name.

The Field Element Name property displays the current value for the field.

Type the new name in the Field Element Name property and press Enter.

Stylus Studio User Guide

249

Converting Non-XML Files to XML

Alternative:
1.

Double-click the field name in the document pane.

The field name field becomes editable.

Figure 174. You Can Edit the Field Name Directly in the Document Pane
2.

Type a new value for field and press Enter.

To specify alternate sources for field names:

Display the Properties window if it is not already displayed (click View > Properties
on the Stylus Studio menu).

Select the field name source you want to use from the Element Name Source dropdown list.

Press Enter.

Defining Fields
You can define fields in any region in a fixed-width input file, as shown in Figure 175.
Once you have defined a field, you can change its size by simply dragging it to any column
in the grid.

Figure 175. Line Identifying a Field in a Fixed-Width Input File

Each field you define is treated as a separate element in the XML output by the custom
XML conversion definition. The input file shown in Figure 175, for example, would result

250

Stylus Studio User Guide

Working with Fields

in XML with two <field> elements, one consisting of the make of motorcycle, and one
consisting of the model, year, and mileage. You can use the field feature to exercise
control over the XML defining separate fields for make, model, year, and mileage, for
example.
Consider the following input file:
Make
BMW
Kawasaki
Ducati
MotoGuzzi
BMW
Ducati
Aprilia

Model
R1150RS
GPz1100
ST2
LeMans
R1150R
Monster
Futura

Year
2004
1996
1997
2001
2002
2000
2001

Mileage
14274
60234
24000
12393
17439
15682
17320

By default, each row is considered to have a single field, containing Make, Model, Year, and
resulting in XML output like this:

Mileage,

<?xml version="1.0" encoding="utf-8"?>

<root>
<row>
<field>Make
Model
Year

Mileage

</field>
</row>
<row>
<field>BMW

14274

R1150RS

2004

</field>
</row>
...

Stylus Studio User Guide

251

Converting Non-XML Files to XML

If you specify fields for Model, Year, and Mileage, the XML output by the custom XML
conversion definition looks like this:
<?xml version="1.0" encoding="utf-8"?>
<root>
<row>
<field>Make</field>
<field>Model</field>
<field>Year</field>
<field>Mileage
</field>
</row>
<row>
<field>BMW</field>
<field>R1150RS</field>
<field>2004</field>
<field>14274
</field>
</row>
...

Neither approach is always correct, but this feature gives you the ability to define the type
of XML output that is appropriate for your use.
Tip Of course, in this example, the next logical step might be to use the first row (Make, Model,
Year,

and Mileage) as the field names as described in Naming Fields on page 247.

To define a field:
1.

Place the cursor in the document pane on the character with which you want to start
the new field.

Click the Begin Field in This Column ( ) button. This action is also accessible from
the CustomXMLConversion menu and the shortcut menu in the Custom XML
Conversion Editor.
Stylus Studio displays a thin orange line that identifies the start of the newly defined
field.

To remove a field:

The procedure for removing a field is the same as the procedure for defining one place
the cursor on any character adjacent to the field line you want to remove and click the
Begin Field in This Column (
) button.

252

Stylus Studio User Guide

Working with Fields

Creating Notes for Fields

Stylus Studio allows you to create notes on individual fields. These notes are for reference
purposes only; they are not output in the XML.
To create notes for a field:
1.

Click the entry field for the Notes property.

The Notes property is in the Field Element Name > Source Data Type tree in the
Properties window. These properties appear only for rows for which a match pattern
exists. See Pattern Matching on page 257 for more information on this topic.

Tip

The Notes dialog box appears.

Figure 176. Notes Dialog Box

Type the notes you want to associate with the field and click the OK button.

Tip If a field has a note defined for it, it is displayed in a tooltip which appears when you

hover the mouse pointer over the field in the Custom XML Conversion Editor.

Component and Sub-Component Fields

Some file formats many EDI variants, for example allow fields to be subdivided into
arrays, sub-fields, or composite fields. Collectively, these fields are referred to as
component fields in custom XML conversion definitions. Typically, the headers of these
files contain information about the character used to specify component fields. Stylus
Studio uses this information to set the default value for the Field Component Separator
property and render XML output accordingly.

Stylus Studio User Guide

253

Converting Non-XML Files to XML

Consider the following input file, which uses a semi-colon (;) to specify component fields:
Make;Model;Year;Color;Seat
BMW;R1150RS;2004;grey,metallic;black,vinyl
MZ;Scorpion;1995;green,clearcoat;black,vinyl
Ducati;ST2;1997;red,clearcoat;black,leather

Using the first row to supply the field names and default Component Element Name
(component), the custom XML conversion definition creates the following XML output
(first two elements shown for brevity):
<?xml version="1.0" encoding="utf-8"?>
<root>
<row>
<Make>BMW</Make>
<Model>R1150RS</Model>
<Year>2004</Year>
<Color>
<component>grey</component>
<component>metallic</component>
</Color>
<Seat>
<component>black</component>
<component>vinyl</component>
</Seat>
</row>
<row>
<Make>MZ</Make>
<Model>Scorpion</Model>
<Year>1995</Year>
<Color>
<component>green</component>
<component>clearcoat</component>
</Color>
<Seat>
<component>black</component>
<component>vinyl</component>
</Seat>
</row>
...

The <component> elements are created as subelements of the <Color> and <Seat> elements.
For line-oriented regions in files containing component fields, you can change the default
Field Component Separator property, and the Component Element Name and
Component Element Name properties, that is, the name you want to use for the

component fields container elements.

254

Stylus Studio User Guide

Controlling XML Output

Custom XML conversion definitions provide several ways for you to control the XML
output. Most XML output is specified using properties displayed in the Properties
window. Some XML output, such as the number of regions or the number of fields in a
row, are specified using the Custom XML Conversion Editor.
This section describes the properties used to control some of the most common output
operations. See Custom XML Conversion Definitions Properties Reference on
page 280 for detailed information on all properties.
This section covers the following topics:

Specifying Element Names on page 255

Specifying Format on page 256

Omitting Regions and Fields, and Rows on page 256

Pattern Matching on page 257

Using Lookup Lists on page 262

Using Key=Value Characters on page 265

Specifying Element Names

You can specify names for the following nodes in an XML document output by a custom
XML conversion definition:

Root element The default for the <root> element is root. You can change the default
using the Root Element Name property.

Region element The default for the <region> element is region. You can change the
default using the Region Element Name property. Different regions can have different
names.

Namespace You can specify names for both the namespace prefix and the
namespace using the Namespace and Namespace Prefix properties, respectively. The
namespace prefix you specify is added to every element name.

Row element The default for the <row> element is row. You can change the default
using the Row Element Name property. Rows in different regions can have different
names.

Field element The default for the <field> element is field. You can change the
default using the Field Name property. Each field can have its own name. If your input
file defines subelements. you can use the Component Element Name and SubComponent Element Name properties to provide a name for the containing element.
Stylus Studio User Guide

255

Converting Non-XML Files to XML

Specifying Format
There are several ways to exercise control over the format of the XML document output
by a custom XML conversion definition.

Indenting By default, Stylus Studio indents the XML generated by a custom XML
conversion definition. You can remove indenting by changing the value of the Indent
XML? property to False.

Whitespace The Normalize Whitespace property converts tabs, carriage returns,

and line-feeds to spaces. Leading and trailing whitespaces are then removed, and any
two or more consecutive whitespaces are collapsed to a single space.

XML Schema The XML Schema Document property allows you to specify the
XML Schema you want to associate with the XML output. There are also fields that
allow you to specify System and Public DTDs.

Omitting Regions and Fields, and Rows

Stylus Studio allows you to omit specific regions and fields from an input file when it is
converted to XML.

Omitting regions The Omit from Output property lets you omit an entire region from
XML output. (Regions with a Region Type of No-output are always omitted from
XML output.)

Omitting fields The Omit from Output property lets you omit a field from XML
output. You can omit a field

Only when it is empty. This is the default.

When it is empty or evaluates to a zero value.

Always, regardless of its value

Never, regardless of its value

Comments You can filter rows using the Comment String property if the
beginning of a row matches the string you enter for this property, Stylus Studio
ignores the row when converting the input file to XML. You can also specify patterns
that rows must match in order for them to be converted to XML. See Pattern
Matching on page 257 for more information.

256

Stylus Studio User Guide

Controlling XML Output

Pattern Matching
You can use regular expressions to specify match patterns for the rows in the input file.
Only those rows in the input file that match the pattern you specify are output to XML
when the file is converted. The simplest way to define a match pattern is to use the Match
Pattern property in the Row Element Name section of the Properties window.

Example
Consider the following input file:
Make,Model,Year,Mileage
BMW,R1150RS,2004,14274
Kawasaki,GPz1100,1996,60234
Ducati,ST2,1997,24000
Moto Guzzi,LeMans,2001,12393
BMW,R1150R,2002,17439
Ducati,Monster,2000,15682
Aprilia,Futura,2001,17320

If you specify a simple regular expression, say, ^B, for the Match Pattern property, Stylus
Studio displays the input file in the Custom XML Conversion Editor as shown in
Figure 177 green check marks identify the rows that match the pattern, and red Xs
identify the rows that do not. (You can also display matching rows in a contrasting color
by clicking the Highlight Matching Rows button. See Document Pane Display Features
on page 230 for more information about this feature.)

Figure 177. Match Pattern Definition and Display

Note that the match pattern also appears as a new node in the schema pane. This new node,
the only one defined for the custom XML conversion definition at this point, uses the
default row element name (row) and the value of the expression.

Stylus Studio User Guide

257

Converting Non-XML Files to XML

Since the match pattern selects only those rows that begin with the letter B, the custom
XML conversion definition creates the following XML document when it is run against
the input file:
<?xml version="1.0" encoding="utf-8"?>
<root>
<row>
<Make>BMW</Make>
<Model>R1150RS</Model>
<Year>2004</Year>
<Mileage>14274</Mileage>
</row>
<row>
<Make>BMW</Make>
<Model>R1150R</Model>
<Year>2002</Year>
<Mileage>17439</Mileage>
</row>

See Working with Nodes on page 260 to learn about adding the row element
name/match pattern pairs that define them.

Sample Regular Expressions

The following table presents some commonly used regular expressions.
Expression

Matches

^ABC

Match all lines starting with ABC

^[Aa][Bb][Cc]

Match all lines starting ABC, abc or

any mix of upper and lowercase (Abc,
for example)

AAA

Match all lines containing AAA

^(DEF | GHI)

Match all lines starting with DEF or

GHI

XYZ$

Match all lines ending with XYZ

XYZ\$

Match all lines containing XYZ

Go to http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html to
learn about the specific regular expression implementation supported in Stylus Studio. Go

258

Stylus Studio User Guide

Controlling XML Output

to http://www.boost.org/libs/regex/doc/syntax.html for additional examples of regular

expression usage.

Specifying Multiple Match Patterns

You can specify multiple match patterns for a single file. If we define a new match pattern,
^K, this results in a new node (<row> ^K) in the schema pane, which now displays both
nodes (see Figure 178). When an input file is converted, Stylus Studio matches the
patterns in the order in which the nodes that represent them are defined in the schema.
Blank patterns are always matched last.
When you define multiple match patterns, the document pane displays a gray square
alongside rows that match a pattern other than the one, if any, associated with the currently
selected row. In Figure 178, for example, row 3 is the currently selected row; it matches
the pattern ^K we have defined. Because row 3 is the active row, Stylus Studio displays
gray squares in rows 2 and 6 (which match the pattern B defined previously).

Figure 178. Gray Squares Identify Rows That Match Other Patterns

Stylus Studio User Guide

259

Converting Non-XML Files to XML

Working with Nodes

In addition to defining nodes using the Match Pattern field of the Properties window, you
can also use the Set Node and Match Pattern dialog box, shown here:

Figure 179. Set Node and Match Pattern Dialog Box

This dialog box allows you to

Define a new node even one that does not match a row in the current input file. For
example, we could define a match pattern for Triumph motorcycles (<row> ^T) even
though there are no Triumph motorcycles in the input file.

Clone an existing node this allows you to copy an existing node and modify its
match pattern to create a new node.

Edit an existing node. (You can also do this in the Properties window, of course.)
When you open the dialog box, the Row Element Name and Match Pattern fields contain
default values that reflect the currently selected row in the document pane or node in the
schema pane.
Defining a New Node
To define a new node:

260

Select a row in the document pane or a node in the schema pane.

Select CustomXMLConversion > Add Node and Pattern from the Stylus Studio
menu.
Alternative: Select Add Node and Pattern from the document pane or schema pane
shortcut menu.
The Set Node and Pattern dialog box appears.

Change the default values in the Row Element Name and Match Pattern fields.

Click OK.

Stylus Studio User Guide

Controlling XML Output

Cloning a Node
To clone a node:
1.

Select the node in the schema pane that you want to clone.
Alternative: Select the row in the document pane that is represented by a row element
name/match pattern pair you want to clone.

Select CustomXMLConversion > Clone Node and Pattern from the Stylus Studio
menu.
Alternative: Select Clone Node and Pattern from the document pane or schema pane
shortcut menu.
The Set Node and Pattern dialog box appears.

Change the default values in the Row Element Name and Match Pattern fields as
needed.

Click OK.

Editing a Node
To edit a node:
1.

Select the node in the schema pane that you want to edit.
Alternative: Select the row in the document pane that is represented by a row element
name/match pattern pair you want to edit.

Select CustomXMLConversion > Edit Node and Pattern from the Stylus Studio menu.
Alternative: Select Edit Node and Pattern from the document pane or schema pane
shortcut menu.
Alternative: Double-click the node.
The Set Node and Pattern dialog box appears.

Change the default values in the Row Element Name and Match Pattern fields as
needed.

Click OK.

Removing a Node
When you remove a node, you are deleting the row element name/match pattern pair from
the custom XML conversion you are defining.

Stylus Studio User Guide

261

Converting Non-XML Files to XML

To remove a node:
1.

Select the node in the schema pane that you want to remove.
Alternative: Select the row in the document pane that is represented by a row element
name/match pattern pair you want to remove.

Select CustomXMLConversion > Remove Node and Pattern from the Stylus Studio
menu.
Alternative: Select Remove Node and Pattern from the document pane or schema
pane shortcut menu.
Alternative: Press the Delete key.
A warning message appears.

Click Yes to remove the node, otherwise click No.

Using Lookup Lists

You can define lookup lists for individual fields. When Stylus Studio converts the input
file, it replaces the string in the input file (the lookup) with the value you have defined for
it in the Lookup List dialog box. Figure 180 shows an example of a lookup list that has
been defined for a Status field:

Figure 180. Sample Lookup List

For any Status fields in the input document with a value of, say, 100, Stylus Studio would
convert that value to Continue in the XML document it outputs; values of 202 would be
converted to Accepted; and so on.

262

Stylus Studio User Guide

Controlling XML Output

Input file values that do not match a lookup are emitted in the XML document as-is,
allowing exceptional values to be decoded. For example, you might have a temperature
lookup list with these values for a <Temperature> field:
32 | Freeze
212 | Boil

All other temperatures would be emitted as-is.

Defining Lookup Lists

Lookups are case-sensitive, so, for example, a lookup of bmw would not match any of the
Make fields in the following sample file:
Make,Model,Year,Mileage
BMW,R1150RS,2004,14274
Kawasaki,GPz1100,1996,60234
Ducati,ST2,1997,24000
Moto Guzzi,LeMans,2001,12393
BMW,R1150R,2002,17439
Ducati,Monster,2000,15682
Aprilia,Futura,2001,17320

You can define lookup lists only for fields in rows for which a match pattern (even a blank
match pattern, as is the default) exists. Finally, you can paste comma- and tab-delimited
text directly into the lookup list. This allows you to easily reuse existing lookup tables
without having to re-enter text.
To define a lookup list:
1.

Select a row for which a match pattern exists.

Click the Lookup List entry field in the Properties window.

Stylus Studio User Guide

263

Converting Non-XML Files to XML

The Lookup List dialog box appears.

Figure 181. Lookup List Dialog Box

264

Enter lookup/value pairs in the corresponding entry fields.

When you are done, click OK.

Stylus Studio User Guide

Controlling XML Output

Working with Lookup Lists

The following table summarizes the functions of the Lookup List dialog box, which allow
you to work with new and existing lookup lists.
Table 21. Lookup List Dialog Box Buttons
Button

Function

Commits the lookup list to the custom

XML conversion.

Cancel

Closes the Lookup List dialog box

without committing any changes.

Copy

Copies the lookup list.

Paste

Pastes comma- and tab-separated text into

the lookup list. Replaces existing content,
regardless of which row you have selected

Append

Adds comma- and tab-separated text to the

end of the lookup list. Existing lookup list
content is preserved.

Insert

Adds a new row to the lookup list.

Delete

Removes the selected row from the lookup

list.

Note Copy, Paste, and Append use the system clipboard and insert at the current cursor

location. Any blank rows are discarded when you save the lookup list.

Using Key=Value Characters

The Key=Value Character Region property allows you to set the separator for key=value
pairs as seen in the input file. When Stylus Studio converts an input file to XML, it uses
the value on the left side of the key=value character for the element name, and the value
on the right for the element value. Consider the following input file:
Triumph Inventory,Year and Quantity
Yr2003=24
Yr2004=12
Yr2005=15

Stylus Studio User Guide

265

Converting Non-XML Files to XML

If you set the Key=Value Character property to =, Stylus Studio creates the following
XML document when you preview the custom XML conversion:
<?xml version="1.0" encoding="utf-8"?>
<root>
<row>
<field>Triumph Inventory</field>
<field>Year and Quantity</field>
</row>
<row>
<Yr2003>24</Yr2003>
</row>
<row>
<Yr2004>12</Yr2004>
</row>
<row>
<Yr2005>15</Yr2005>
</row>
</root>

Using Custom XML Conversion Definitions in Stylus

Studio
You can use custom XML conversion definitions to open any file as XML anywhere in
Stylus Studio. For example, you might want to use a text file (.txt) as the source
document for XQuery Mapper. When you open a file using a custom XML conversion
definition, the XML Converters engine converts that file to XML on-the-fly, using the
settings defined in the custom XML conversion definition you select.
You can also use the DataDirect XML Converters API to invoke a custom XML
conversion definition (or an XML Converter). See the documentation for DataDirect
XML Converters for more information:
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

How to Open a File Using a Custom XML Conversion Definition

You can use the Open dialog box to open a file using a custom XML conversion definition
in Stylus Studio.
To open a file using a custom XML conversion definition from the Open dialog box:
1.

266

Display the Open dialog box (select File > Open from the Stylus Studio menu, for
example).

Stylus Studio User Guide

Using Custom XML Conversion Definitions in Stylus Studio

Navigate to the directory that contains the file you want to open using the custom
XML conversion definition and select the file.

Check the Open using XML Converter check box and click the Open button.

Figure 182. Check Box to Open Files Using XML Converters

Stylus Studio displays the Select XML Converter dialog box.

Figure 183. Select XML Converter Dialog Box

Stylus Studio User Guide

267

Converting Non-XML Files to XML

If you are using a custom XML conversion definition (.conv), select Custom XML
Conversions. Then, use the browse button in the Value field to locate the custom
XML conversion definition you want to use. Go to step 5.

Figure 184. Selecting a Custom XML Conversion Definition

Click OK.
The file is converted to XML and appears in the editor from which you displayed the
Open dialog box in step 1.

Tip You can use the same basic procedure, from the Save As dialog box, to save a file using

a custom XML conversion definition. See Saving an XML File in Another Format on
page 220.

268

Stylus Studio User Guide

The Converter URI Scheme

You can use the converter: URI scheme to reach a variety of data sources using DataDirect
XML Converters and custom XML conversion definitions.

Where You Use Converter URIs

You can use converter URIs as the argument in XQuery and XSLT 2.0 doc() functions,
and in XSLT 1.0 document() functions.

Specifying a Converter URI

To specify a converter: URI, you need to specify

The XML Converter you want to use EDI, CSV, dBase, custom XML conversion
definition (.conv file), and so on.

Values for any XML Converters properties (separator or escape characters, for
example) for which you do not want to use the default values. Options for custom
XML conversions are part of the custom XML conversion definition and are not
specified.

The file to be converted.

Example Converter URI with a DataDirect XML Converters

A converter: URI that invokes the DataDirect XML Converter for comma-separated
values (CSV) to convert the three.txt file in the Stylus Studio\examples directory to
XML might look like this:
converter:CSV:newline=lf:first=yes:?file:///c:/StylusStudio/examples/
three.txt

The instructions to the XML Converters engine from this instance of the converter:URI
are described the following table.

Stylus Studio User Guide

269

Converting Non-XML Files to XML

Table 22. URI Scheme Example

Instruction

Converter URI String

Use the Comma-Separated Values XML

Converter converter

converter:csv

The line separator in the source file is a

line feed

newline=lf

The values in the first row of the source file

should be used to supply field names

first=yes

The source file is three.txt

file:///c:/StylusStudio/examples/three.txt

Properties that use default values (a comma is the default separator character for the CSV
XML Converter, for example) do not have to be specified in a converter:URI.

Example Converter URI with a Custom XML Conversion Definition

A converter URI that references a custom XML conversion definition might look like this:
converter:///myConverter.conv?file:inventory.txt

This converter uses myConverter.conv to convert the file inventory.txt to some format
(specified in the custom XML conversion definition when it was built using the Custom
XML Conversion Definition Editor in Stylus Studio). Note that individual configuration
properties are not specified they are part of the definition described in the .conv file.

Converter URI Syntax

The converter URI syntax is the same whether you are using them for DataDirect XML
Converters or custom XML conversion definitions.
converter:name:[property_name=value: | property_name=value: | ...]?file:file
URL

Where:

name is the name of the DataDirect XML Converters or the .conv file name of a
custom XML conversion definition.

270

Stylus Studio User Guide

The Converter URI Scheme

The names for XML Converters names are displayed in Stylus Studio; see Where
Converter URIs are Displayed in Stylus Studio on page 272. They are also described
in the DataDirect XML Converters documentation; see
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.
property_name is the name of a DataDirect XML Converters property. You need to
specify a property and its value only if you want to configure the converter to use
something other than the default value. You do not specify properties for custom
XML conversion definitions.
XML Converters properties are displayed in Stylus Studio; see Where Converter
URIs are Displayed in Stylus Studio on page 272. They are also described in the
DataDirect XML Converters documentation; see
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.
file URL is the URL of the file you want to convert.

XML Converter Properties

While the format of the converter:URI is the same from one XML Converter to another,
XML Converters have different properties. For example, the XML Converter for dBase
files has settings that the XML Converter for binary files does not.
In addition, property names in converter URLs appear in an abbreviated format the Line
separator property is called newline in a converter:URI.
XML Converters properties are displayed in the Select XML Converter dialog box, as
shown in Figure 183. See the DataDirect XML Converters Users Guide and Reference
for complete properties reference information:
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

Stylus Studio User Guide

271

Converting Non-XML Files to XML

Where Converter URIs are Displayed in Stylus Studio

Converter URIs are displayed in the following places in Stylus Studio:

The URI field of the EDI to XML editor:

Figure 185. Converter:URI displayed in the EDI to XML Editor

You use the EDI to XML editor to create conversion files that you can save and reuse.
See Chapter 4 Converting EDI to XML for more information.

272

Stylus Studio User Guide

The Converter URI Scheme

The URI field of the Select XML Converter dialog box displays the converter:URI for
the XML Converters or custom XML conversion definition you have selected.

Figure 186. Converter:URI Displayed in the Select XML Converter Dialog Box

Note that XML Converters name and properties used in the converter:URI vary from
the full names displayed in the Select XML Converter dialog box. In addition, note
that only properties whose default value you change in the Value field are displayed
in the URL field.
The Project window (select Show Full URL from the Project window shortcut menu)
displays the converter:URI used to create an XML document:

Figure 187. Converter:URI Displayed in Project WIndow

Stylus Studio User Guide

273

Converting Non-XML Files to XML

You can use any of these sources for the converter:URI strings you want to use in your
XQuery and XSLT code. See Using Stylus Studio to Build a Converter URI on
page 274 for more information.
Tip Converter URIs in the Select XML Converter dialog box are already escaped and can be
used as-is. Converter URIs taken from the Project window must be escaped manually

when you paste them into your XSLT or XQuery code.

Using Stylus Studio to Build a Converter URI

If you have Stylus Studio X14 XML Enterprise Suite, you can use Stylus Studio to
construct converter URLs. Converter URIs can be complex property names and their
values vary from one XML Converters to another, for example so using Stylus Studio
to construct them can reduce errors in your applications.

Using the URI in the Select XML Converter Dialog Box

To construct a converter URI using the URI in the Select XML Converter dialog box:

274

Use the XML Converters to open a file as an XML document in Stylus Studio. See
Using XML Converters to Open a Non-XML File as XML on page 219or How to
Open a File Using a Custom XML Conversion Definition on page 266 if you need
help with this step.

Before clicking OK to complete the conversion, copy the converter:URI in the URI
field of the Select XML Converter dialog box (see Figure 186).

Click OK to complete the conversion. (You can click Cancel if you are peforming this
procedure just to obtain the converter:URI.)

Paste the converter URI in your XSLT or XQuery code as needed.

Stylus Studio User Guide

The Converter URI Scheme

Using the URI in the Properties Window

To construct a converter URI using the URI in the Properties window:
1.

Tip

Open a new document in any Stylus Studio text editor (for example, File > New > XML
Document).
The purpose of this step is to provide an editor into which you can drag-and-drop the
the document you created in step 1 in order to display the associated converter:URI.

Drag the document you created in step 1from the Project window and drop it into the
text editor you opened in step 2.
The complete URI appears in the text editor.

Figure 188. Copying a URL to a Text Editor

Copy the complete converter URI.

Paste the converter URI in your XSLT or XQuery code as needed.

Note: Escape characters as required for strings in Java programs. For example,
escape=\:quotes='" becomes escape=\\:quotes='\" (the single quote does not need to be

escaped).
Stylus Studio User Guide

275

Converting Non-XML Files to XML

Working with EDI Conversions

You can convert EDI to XML (and vice versa) in Stylus Studio using the built-in
DataDirect XML Converters for EDI. The XML Converters for EDI handles most
versions of EDI standard dialects (see Supported EDI Dialects on page 276)
automatically, and it optionally performs validation of content, structure, and code list
values.
This section describes more about the level of support for converting EDI to XML (and
vice versa) in Stylus Studio.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the EDI to XML Mapping video. A
complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

Supported EDI Dialects on page 276

Converting Custom EDI Message Types on page 277

Documentation for DataDirect XML Converters on page 279

XML Schemas for Custom EDI Message Types on page 279

Validating XML from/to EDI on page 280

Supported EDI Dialects

DataDirect XML Converters supports the following EDI dialects:

ATIS

Cargo-IMP

EANCOM

EDIFACT

Edig@s

HL7

NCPDP

PADIS

TRADACOMS

X12

276

Stylus Studio User Guide

Working with EDI Conversions

Visit http://www.datadirect.com/products/data-integration/datasources/edistandards/index.ssp to learn detailed information about version and message support for
all suppored EDI dialects.

Converting Custom EDI Message Types

DataDirect XML Converters supports the Standard Exchange Format (SEF). SEF allows
you to describe structure of an EDI document based on an extension (or restriction) to a
standard EDI message type. You can instruct the EDI XML Converter to read your SEF
extension file and use it when converting your proprietary EDI to XML.

Working with SEF Files

You can build a SEF file based on the SEF specification. A copy of the SEF standard
specification has been placed on the DataDirect Technologies web site:
http://www.datadirect.com/docs/sef161.pdf

A far easier way is to use the Stylus Studio EDI to XML module to create a SEF file. Using
graphical tools, the EDI to XML editor allows you to

Take advantage of the XML Converters repository of numerous EDI dialects and
versions

Create a SEF file based on a sample EDI document or an EDI dialect

Customize an EDI dialect to suit your needs changing a segment from mandatory
to optional, for example

Modify XML Converters properties

Preview conversions of custom EDI to XML

See Chapter 4 Converting EDI to XML for more information.

Process Overview
The process for converting a custom EDI message type includes the following steps:
1.

Create a SEF file (mycustomEDI.sef, for example) that describes how the custom EDI
message type differs from the EDI standard on which it is based its extensions or
restrictions, in other words. The purpose of this document is to teach the DataDirect
XML Converters engine about the differences between your custom EDI message
type and the EDI standard message type on which it is based.

Stylus Studio User Guide

277

Converting Non-XML Files to XML

Open the EDI file you want to convert to XML. Select File > Open, and then select
the Open Using XML Converter check box.

Select the EDI XML Converter in the Select XML Converter dialog box.

Specify the file URL for the SEF file (mycustomEDI.sef , for example) in the
Extension map file property. See Specifying the SEF File Location on page 278 if
you need help with this step.

Figure 189. Specifying a Custom EDI Message Type

Click OK to convert your custom EDI message type to XML.

Specifying the SEF File Location

You can specify the location of the SEF file in the Extension map file property using

An absolute URL (c:/mypath/mycustomEDI.sef, for example)

A relative path (mydir/mycustomEDI.sef, for example)

Note that if you are using a relative path, it must be relative to the same directories in
which the DataDirect XML Converters executables are installed:

For XML Converters for .NET Stylus Studio installation directory\compontents\XML

Converters for .NET\bin\XMLConverters.dll

For XML Converters for .Java Stylus Studio installation directory\compontents\XML

Converters for Java\lib\XMLConverters.jar

In environments in which the location of the XMLConverters.* file cannot be determined,

you must specify the location. For example:

278

Stylus Studio User Guide

Working with EDI Conversions

For XML Converters for .NET set the registry key HKLM/Software/DataDirect/XML
Converters 5.0/ProductLocation

For XML Converters for Java set the system property

com.ddtek.xmlconverter.bindir, or com.ddtek.xmlconverter.libdir

Documentation for DataDirect XML Converters

Documentation for DataDirect XML Converters is available in several locations and
formats for XML Converters for both Java and .NET.

Stylus Studio Installation

You can find XML Converters documentation in the following folders where you installed
Stylus Studio:

.NET

\compontents\XML Converters for .NET\doc PDF version of the Users Guide

and Reference and Installation Guide

\compontents\XML Converters for .NET\help HTML version of the Users

Guide and Reference

Java

\compontents\XML Converters for Java\doc PDF version of the Users Guide

and Reference and Installation Guide

\compontents\XML Converters for .NET\help HTML version of the Users

Guide and Reference

DataDirect Technologies Web Site

You can find XML Converters documentation on the DataDirect Technologies web site:
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp

XML Schemas for Custom EDI Message Types

Warning This functionality has been deprecated in favor of support for the Standard Exchange

Format (SEF). Use SEF files to describe the XML Schema for custom EDI message
types. For more information, see Chapter 4 Converting EDI to XML.

Stylus Studio User Guide

279

Converting Non-XML Files to XML

Validating XML from/to EDI

Stylus Studio provides the EDI to XSD document wizard to convert various EDI dialects
and message types to XML Schema. Such an XML Schema can be useful if you are
converting XML to EDI, because it allows you to ensure that the EDI created by the
DataDirect XML Converters for EDI conforms to a particular EDI message type standard.
You can also use the XML Schema created by the EDI to XSD document wizard to
validate data after you have converted EDI to XML, when URL-based error checking is
disabled, to determine how well the incoming stream conforms to the EDI standards.
See Creating XML Schema from EDI on page 577 for more information on using this
document wizard.

Custom XML Conversion Definitions Properties

Reference
This section provides reference information for properties displayed in the Properties
window of the Custom XML Conversion Editor. It covers the following topics:

Input File Properties on page 281

XML Output URL Properties on page 282

Region Type Properties on page 284

Row Element Name Properties on page 287

Field Element Name Properties on page 288

Data Type Properties (by data type) on page 290

Specifying Control Characters on page 311

280

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Input File Properties

Table 23. Input File Properties
Property

Description

Editable

Affects XML

Input File

The URL of the file you are using as

the input file.

Yes. You can

select a new
input file from
this field.

Input
Encoding

Encoding detected by Stylus Studio.

Yes

Physical
Size

The size of the input file in bytes.

Portion
Loaded

The size of the input file in bytes

loaded into Stylus Studio.

Characters
Loaded

The number of characters loaded. For

especially large files, Stylus Studio
does not read the entire file as only a
sample is required to define a custom
XML conversion definition. The
finished custom XML conversion
definition, however, reads any file you
open it with in its entirety.

Character
Unicode
Value

The Unicode value of the character

under the cursor.

Stylus Studio User Guide

281

Converting Non-XML Files to XML

XML Output URL Properties

Table 24. XML Output File Properties

282

Property

Description

document you want to associate with
the XML document output by the
custom XML conversion definition.

Yes

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Table 24. XML Output File Properties
Property

Description

Editable

Affects XML

XML
Schema
Namespace

The namespace you want to use with

the XML Schema document.

Yes

Indent
XML?

Whether or not you want to indent the

XML output.

Yes

Stylus Studio User Guide

283

Converting Non-XML Files to XML

Region Type Properties

Note Each region has its own field and row properties. In addition, some properties apply only

to line-oriented regions. These properties are marked with an asterisk.

Table 25. Region Properties

284

Property

Description

Editable

Affects XML

Region Type

The type of the region that currently

has focus.

Yes. You can

change the
region type
from this field.

Region
Element
Name

The name you want to assign to this

region in the XML output. Optional.

Yes

Element
Name
Source

Whether the source for the element

names in this region is user-supplied,
is taken from the first row in the
region, or is based on the WS-EDI
standard.

Yes

Rows to Skip

The number of rows, starting at the

beginning of the region, you want to
omit from output.

Yes

Omit from
Output

Whether or not you want to omit the

entire region from output.

Yes

Size

The regions size in characters.

Portion of
File

The starting and ending offsets of the

current region.

Row Count

The number of rows in the current

region.

Row
Length+

The number of characters in the

current row.

Line
Terminator*

The type of line terminator character

detected by Stylus Studio.

Yes

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Table 25. Region Properties
Property

Description

Whether or not to treat a pair of

delimiting characters within a
delimited string as escaped characters.
For example, if this property is set to
Yes, abcxyz is treated as
abcxyz.

Yes

* This property is for line-oriented regions only.

286

This property is for fixed-width regions only.

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Row Element Name Properties

Table 26. Row Properties
Property

Description

Editable

Affects XML

Row
Element
Name

The name you want to assign to all

rows in the region. The default value is
row.

Yes

Match
Pattern

A regular expression you can use to

filter rows in a region. Only rows that
match the pattern you specify are
output to XML.

Yes

Current Row
Length

The length of the current row.

Fields in
Current Row

The number of fields in the current

row.

Max Fields
in Row

The number of fields in the row that

contains the largest number of fields.

Stylus Studio User Guide

287

Converting Non-XML Files to XML

Field Element Name Properties

Note Each region has its own field and row properties. In addition, some properties apply only

to line-oriented regions. These properties are marked with an asterisk.

Table 27. Field Properties
Property

Description

Editable

Affects XML

Field
Element
Name

The name you want to use for field

elements in the XML output. The
default value is field.

Yes

Component
Element
Name

The name you want to use for subfields detected by Stylus Studio (based
on the Component Separator
character) in the XML output. The
default value is component.

Yes

SubComponent
Element
Name

The name you want to use for subfields detected by Stylus Studio (based
on the Sub-Component Separator
character) in the XML output. The
default value is subcomponent.

Yes

Source Data
Type

The data type of the current field.

Stylus Studio provides support for the
following data types:

Yes

String, Boolean, number, date, time,

byte, short, integer, long, float, double.
Note that some properties are typespecific.
See Data Type Properties (by data
type) on page 290 for information on
properties that are associated with
specific data types.
Target Data
Type

288

Not currently used.

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Table 27. Field Properties
Property

Description

Editable

Affects XML

Number

The number of the field in which the

cursor is located. Starting with 1 from
the left-most field.

Cursor
Position

The offset of the cursors current

location from the start of the current
field.

Offset

The offset of the start of the current

field. Measured from the start of the
row.

Length

The length of the current field in

characters.

Max Field
Length *

The length of the longest of all the

instances of this field.

Value

The value of the current field.

This value also appears in the status

bar.

* This property is for line-oriented regions only.

Stylus Studio User Guide

289

Converting Non-XML Files to XML

Data Type Properties (by data type)

This section describes the properties that are specific to a given data type.

Common Properties
All data types support these properties:
Table 28. Common Properties
Description

Lookup List

This property lets you build a substitution table for

output. It includes a two-column table. At runtime,
any item which evaluates to a value in the left column
is replaced by the corresponding value in the right
column in the output stream. A blank value on the
left can be used to set a default value for the field.
Note that this is applied before the test to determine
if the data should be qualify for Omit from Output.

Yes

Notes

Allows you to add internal comments for a field. It is

not used by custom XML conversion definitions.

Omit from Output

Allows a field to be omitted from XML output based

on its presence or value. Valid values include:

Yes

XML Output Form

290

Affects
XML

Property

Only When Empty. This is the default.

When Empty or Zero. Does not emit an element

containing the value if it evaluates numerically
to zero.

Always. Always hides the field from the output.

Never. Always includes the field in the output

Determines whether the value is emitted into the

output stream as an element or as an attribute. The
default is element.

Yes

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

BCD Datatype Properties

Binary Coded Decimal (BCD) is a set of ways to pack one or two decimal digits into each
byte. These are various related types of machine-specific encodings for numbers. The
Comp3 and Zoned types are different implementations of this idea.
Table 29. BCD Properties
Property

Description

Editable

Affects XML

Architecture

Select the architecture that matches the

machine type that the data originated on,
or was designed for, from this list:

Yes

NBCD Signed

NBCD Unsigned

Excess-3

BCD 2421

BCD 84-2-1

IBM 1401 Signed

IBM 1401 Unsigned

Packed

The name you want to use for sub-fields

detected by Stylus Studio (based on the
Component Separator character) in the
XML output. The default value is
component.

Yes

Scaling
Factor
(10^n)

The name you want to use for sub-fields

detected by Stylus Studio (based on the
Sub-Component Separator character) in
the XML output. The default value is
subcomponent.

Yes

Stylus Studio User Guide

291

Converting Non-XML Files to XML

Binary Datatype Properties

Binary data in raw form.
Table 30. Binary Properties
Property

Description

Editable

Affects XML

Rendering

How the data is written to XML:

Yes

Base-64 Encoding writes the data

in a form compatible with the W3C
XML Schema base64Binary type
(default)

Hexadecimal Encoding writes the

data in a form compatible with the
W3C XML Schema hexBinary type

Octal Encoding writes the data

as a series of octal triplets

# Literal Encoding copies the data

as-is to the output stream, which
may not render as valid XML

Boolean Datatype Properties

True/false values, with support for three-valued-logic (true/false/unknown or null). The
following steps are taken to determine the value of a boolean field:

292

If the field contains all binary zeros, it is false.

If the field contains all binary ones (that is, all 0xFF values), it is true.

If the field is one byte long and contains a 0x01 value, it is true.

If the first or last byte in the field contains a 0x01 and all of the other bytes are 0x00,
it is true.

If the contents of the field match any of the items in the True Value Match List or False
Value Match List, then the value is true or false respectively.

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

If none of these rules apply, the value is considered unknown.

Table 31. Boolean Properties

Property

Description

Editable

Affects XML

True Value
Match List

A semicolon (";") -separated list of

values. If the input value matches any of
them in step 5, it is considered true and
the value from the True Output As
property is emitted. The default list is:

Yes

yes

true

.y.

.t.

The comparisons are not case-sensitive.

False Value
Match List

A semicolon (";") -separated list of

values. If the input value matches any of
them in step 5, it is considered false and
the value from the False Output As
property is emitted. The default list is:

false

.n.

.f.

The comparisons are not case-sensitive.

True Output
As

If the value is determined to be true then

this value is output. The default is "Yes".

Yes

False Output
As

If the value is determined to be false then

294

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Byte Datatype Properties

A single byte with a range of 0 to 255 for unsigned or -128 to 127 for signed.
Table 32. Byte Properties
Property

Description

Signed

true (default)

false use this to make the value

unsigned

Scaling
Factor
(10^n)

This is a value from -16 (shifts the

decimal 16 places to the right, making
the number smaller by n orders of
magnitude) to 0 (keeps the number
exactly as it appears in the input) to 16
(shifts the decimal 16 places to the left,
making the number larger by n orders of
magnitude). To enter a scaling factors
from 10-16 to 1016, just enter the
exponent value.

Editable

Affects XML

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.

Stylus Studio User Guide

295

Converting Non-XML Files to XML

Comp3 Datatype Properties

Also known as "Computational-3," "Packed" or "Packed Decimal." A COBOL storage
format similar to Zoned below but differing in internal structure. It is also related to the
BCD types.
Table 33. Comp3 Properties
Property

Description

Editable

Affects XML

Scaling
Factor
(10^n)

This is a value from -16 (shifts the

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.

Date Datatype Properties

A date, stored either as a string or in binary form.
The parsing rules are:

296

If the length is 3, then the day, month and year are read as binary values in the Date
Format order. The Window for Two-digit Years value is used to determine the century.
If the format is YJ, then the first byte is the year, and the second two are the day
number in the year, stored as LSB, MSB.

If the length is 6, then the same is used, except each day/month/year is taken as two
digits.

If the length is 8 and there are no separators, then the day and month each get two
digits and the year gets four.

Otherwise, it is parsed using the YMD Separator characters.

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

For months, the names or abbreviations in English, German, Spanish, French,

Portuguese and Italian are recognized.

Table 34. Date Properties

Property

Description

Editable

Affects XML

Date Format

The default is read from the local system

settings at the time the custom XML
converter is defined.

Yes

YMD
Separator

DMY (day-month-year)

MDY (month-day-year)

YMD (year-month-day)

YJ (year-daynumber a.k.a. "Julian"

format)

A hint to the parser as to the most likely

separator between the date components
that will be seen.
The default value comes from the local
system configuration, and also includes
the period ("."), comma (","), hyphen (""), slash ("/") and space.

Stylus Studio User Guide

297

Converting Non-XML Files to XML

Table 34. Date Properties
Property

Description

Editable

Affects XML

Window for
Two-digit
Years

If the year is only given as two digit, this

is the cut-off date for determining the
century. The default is 1950.

Yes

Left
Padding,
Right
Padding

These two properties control what sort of

Yes

The default for both is spaces (0x20) and

298

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

DateTime Datatype Properties

A date plus a time.
This is parsed as a date followed by the Date-Time Separator followed by a time. It
combines the properties of both, and includes that one additional property.
Table 35. DateTime Properties
Property

Description

Editable

Affects XML

Date-Time
Separator

This is the character that separates the

date string from the time string. The
default values are 'T' and ' '.

Yes

Decimal Datatype Properties

Reads 16 bytes and interprets it as a .net System.Decimal. Numbers as large as 1028
(positive or negative) and with as many as 28 significant digits can be stored as a decimal
type without loss of precision.

Stylus Studio User Guide

299

Converting Non-XML Files to XML

Double Datatype Properties

The standard IEEE 8-byte floating point format.
Table 36. Double Properties
Property

Description

Editable

Affects XML

Scaling
Factor
(10^n)

This is a value from -16 (shifts the

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
Endian

300

When binary numbers are stored, they

can be stored with the smallest
component first (little-endian) or last
(big-endian).

Little the standard for Intel x86based machines (default)

Big

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Float Datatype Properties

The standard IEEE 4-byte floating point format.
Table 37. Float Properties
Property

Description

Editable

Affects XML

Scaling
Factor
(10^n)

This is a value from -16 (shifts the

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
Endian

Stylus Studio User Guide

When binary numbers are stored, they

can be stored with the smallest
component first (little-endian) or last
(big-endian).

Little the standard for Intel x86based machines (default)

Big

301

Converting Non-XML Files to XML

Integer Datatype Properties

A four-byte integer with a range of 0 to 4,294,967,295 for unsigned or -2,147,483,648 to
2,147,483,647 for signed.
Table 38. Integer Properties
Property

Description

Signed

true (default)

false use this to make the value

unsigned

Scaling
Factor
(10^n)

This is a value from -16 (shifts the

Editable

Affects XML

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
Endian

302

When binary numbers are stored, they

can be stored with the smallest
component first (little-endian) or last
(big-endian).

Little the standard for Intel x86based machines (default)

Big

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Long Datatype Properties

An eight-byte integer with a range of 0 to 18,446,744,073,709,551,615 for unsigned or 9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 for signed.
Table 39. Long Properties
Property

Description

Signed

true (default)

false use this to make the value

unsigned

Scaling
Factor
(10^n)

A value from -16 (shifts the decimal 16

places to the right, making the number
smaller by n orders of magnitude) to 0
(keeps the number exactly as it appears
in the input) to 16 (shifts the decimal 16
places to the left, making the number
larger by n orders of magnitude). To
enter a scaling factors from 10-16 to 1016,
just enter the exponent value.

Editable

Affects XML

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
Endian

Stylus Studio User Guide

When binary numbers are stored, they

can be stored with the smallest
component first (little-endian) or last
(big-endian).

Little the standard for Intel x86based machines (default)

Big

303

Converting Non-XML Files to XML

Number Datatype Properties

This corresponds to numbers stored in text form.
Note that if the number is followed by a percent ("%") it is divided by 100; if followed by
a permille ("") it is divided by 1000.
A leading or trailing '+' is ignored, as numbers are assumed positive. A leading or trailing
'-' will make the number negative.
Table 40. Number Properties

304

Property

Description

Editable

Affects XML

Decimal

The character that corresponds to the

decimal point. It is typically a period
(".") or comma (","). The default value is
determined by the settings on the
machine creating the custom XML
converter.

Yes

Thousands

The character that corresponds to the

thousands separator. The default is
fetched from the system settings, and is
typically a comma (","), period (".") or
space, and is subsequently stored with
the custom XML converter. If seen in the
input, it is thrown away and not
preserved in the output.

Yes

Base

The numeric base in which the number is

stored in the input file. It can be anything
from 2 (binary) to base 36. The default is
10 (decimal). Other common numbers
are 8 (octal) and 16 (hexadecimal).

Yes

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Table 40. Number Properties
Property

Description

Editable

Affects XML

Scaling
Factor
(10^n)

A value from -16 (shifts the decimal 16

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
C Rules for
Octal and
Hex

Stylus Studio User Guide

yes if a number begins with 0 it is

considered octal, or if it begins with
0x it is considered hexadecimal;
otherwise it is considered decimal
(default)

no numbers are considered in the

given Base only

305

Converting Non-XML Files to XML

Table 40. Number Properties
Property

Description

Use
Currency
Conventions

yes if the number is surrounded by

'(' and ')' or has a trailing 'cr' (caseinsensitive) it is considered
negative, or if it has a trailing 'db' or
'dr' (also case-insensitive) it is
considered positive (default)

Left
Padding,
Right
Padding

These two properties control what sort of

Editable

Affects XML

Yes

The default for both is spaces (0x20) and

306

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Short Datatype Properties

A two-byte integer with a range of 0 to 65,535 for unsigned or -32,768 to 32,767 for
signed.
Table 41. Short Properties
Property

Description

Signed

true (default)

false use this to make the value

unsigned

Scaling
Factor
(10^n)

A value from -16 (shifts the decimal 16

Editable

Affects XML

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.
Endian

Stylus Studio User Guide

When binary numbers are stored, they

can be stored with the smallest
component first (little-endian) or last
(big-endian).

Little the standard for Intel x86based machines (default)

Big

307

Converting Non-XML Files to XML

String Datatype Properties

A regular string of characters.
Table 42. String Properties
Property

Description

Normalize
White Space

yes change all linefeeds, carriage

returns and tabs into spaces, then
remove all spaces from start and end
of text, then collapse any
consecutive spaces into a single
space (default)

no (leave all whitespace alone)

Left
Padding,
Right
Padding

These two properties control what sort of

Editable

Affects XML

Yes

The default for both is spaces (0x20) and

308

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Time Datatype Properties

A time value.
The parsing rules are as follows:
1.

If the first character is an 'n' or 'N', it is assumed to be noon (12:00:00).

If the first character is an 'm' or 'M', it is assumed to be midnight (00:00:00).

If there is a HMS separator, the next three steps are skipped.

If the length is six or more, then the hours are the first two characters, the minutes are
the next two characters, and the seconds are the next two digits.

If the length is four or five, then the hours are the first two characters, and the minutes
are the next two characters.

No valid date can be determined.

If an HMS separator was seen, then the following rules are tried:

Up to two digits become the hour, terminated by the HMS separator.

Up to two more digits become the minute, also terminated by the HMS separator.

10.

If there are any more digits, the next two become the seconds value.

11.

If there is a decimal character and more digits, they become fractional parts of the
seconds.

12.

If an 'am' or 'pm' (case-insensitive) marker is found, the hours are adjusted

accordingly.

Stylus Studio User Guide

309

Converting Non-XML Files to XML

13.

Wrapping is performed for seconds >= 60 and minutes >= 60. Hours are moduloed
with 24.

Table 43. Time Properties

Property

Description

Editable

Affects XML

HMS
Separator

This is a hint to the parser as to the most

likely separator between the hours,
minutes and seconds that will be seen.

Yes

The default value comes from the local

system configuration, and also includes
the colon (":"), period (".") and space.
Left
Padding,
Right
Padding

These two properties control what sort of

padding is to be found on either side of
the field and then removed. Any
characters listed here will be removed.
Characters can be specified either by
their Unicode values, their Unicode
names, or single-quoted.
The default for both is spaces (0x20) and
tabs (0x09).
If there are field delimiters, these are the
characters that are trimmed from the
contents within the delimiters. The
region-level Characters to Toss setting
determines which characters are
trimmed outside of the delimiters. If
there are no delimiters, then the
Characters to Toss setting is applied first,
and then Left Padding and Right Padding
are applied.

310

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Zoned Datatype Properties

Also known as the "IBM Signed" format. It is related to Comp3.
Table 44. Zoned Properties
Property

Description

Editable

Affects XML

Scaling
Factor
(10^n)

A value from -16 (shifts the decimal 16

Yes

Example: Entering an exponent of 3 will

cause any numbers to be multiplied by
1000 (103) before being output to XML.

Specifying Control Characters

Lists of symbols are used to designate characters for properties like Field Component
Separator, Line Terminator, and Field Separator.
Individual symbols can be expressed in several forms. Numbers and letters, for example,
can be entered using single quotes, such as A, B, C. Control characters or other
Unicode values can be expressed using their decimal value, or their hex value by
preceding it with 0x 128 or 0x80, for example. In addition, certain control characters
have alternate mnemonic representations, and Stylus Studio supports them, as well.
When entering multiple symbols for a given property, separate symbols using a comma.

Stylus Studio User Guide

311

Converting Non-XML Files to XML

The following table summarizes commonly used control characters. For more
information, visit http://www.unicode.org.
Table 45. Commonly Used Control Characters

312

Decimal

Hex

Mnemonic

Control Key

0x00

NUL

^@, '\0'

0x01

SOH

0x02

STX

0x03

ETX

0x04

EOT

0x05

ENQ

0x06

ACK

0x07

BEL or BELL

^G, '\a'

0x08

^H, '\b'

0x09

TAB or HT

^I, '\t'

0x0A

^J, '\n'

0x0B

^K, '\v'

0x0C

^L, '\f'

0x0D

^M, '\r'

0x0E

0x0F

0x10

DLE

0x11

DC1 or XON

0x12

DC2

0x13

DC3 or XOFF

0x14

DC4

0x15

NAK

Stylus Studio User Guide

Custom XML Conversion Definitions Properties Reference

Table 45. Commonly Used Control Characters
Decimal

Hex

Mnemonic

Control Key

0x16

SYN

0x17

ETB

0x18

CAN

0x19

0x1A

SUB

0x1B

ESC

0x1C

0x1D

0x1E

0x1F

127

0x7F

DEL

128

0x80

129

0x81

130

0x82

BPH

131

0x83

NBH

132

0x84

IND

133

0x85

NEL

134

0x86

SSA

135

0x87

ESA

136

0x88

HTS

137

0x89

HTJ

138

0x8A

VTS

139

0x8B

PLD

Stylus Studio User Guide

313

Converting Non-XML Files to XML

Table 45. Commonly Used Control Characters

314

Decimal

Hex

Mnemonic

140

0x8C

PLU

141

0x8D

142

0x8E

SS2

143

0x8F

SS3

144

0x90

DCS

145

0x91

PU1

146

0x92

PU2

147

0x93

STS

148

0x94

CCH

149

0x95

150

0x96

SPA

151

0x97

EPA

152

0x98

SOS

153

0x99

154

0x9A

SCI

155

0x9B

CSI

156

0x9C

157

0x9D

OSC

158

0x9E

159

0x9F

APC

160

0xA0

NBSP

173

0xAD

SHY

Control Key

Stylus Studio User Guide

Chapter 4

Converting EDI to XML

Support for the EDI to XML module is available only in Stylus Studio XML
Enterprise Suite.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the EDI to XML
module video.
This chapter describes how to use the Stylus Studio EDI to XML module to convert
standard and proprietary EDI to XML.
This chapter covers the following topics:

What is the EDI to XML Module? on page 316

Creating an EDI to XML Conversion on page 320

Previewing an EDI to XML Conversion on page 322

Example: Converting a Conforming EDI File on page 323

Example: Converting a Non-conforming EDI File on page 326

Resolving EDI Document Errors on page 332

Specifying XML Converter Properties on page 339

Customizing an EDI Standard on page 340

Generating XQuery and XML Schema from EDI on page 360

EDI Structure Definitions Properties Reference on page 365

EDI XML Converters Properties Reference on page 375

Stylus Studio User Guide

315

Converting EDI to XML

What is the EDI to XML Module?

The EDI to XML module is a graphical tool designed to help you translate EDI documents
to XML. In particular, it enables you to convert EDI documents that do not conform to
any of the EDI dialects supported by DataDirect XML Converter, whose conversion
engine forms the basis of the EDI to XML module. Documents might be nonconforming
for any number of reasons perhaps the document contains an error in the standard EDI
structure, or perhaps you have customized an EDI standard to suit your business purposes.
Regardless, the EDI to XML module makes it possible to convert nonconforming EDI to
XML and to save that conversion definition for use with other EDI documents that share
the same specification.

Supported EDI Dialects

DataDirect XML Converter supports the following EDI dialects: ATIS, Cargo-IMP,
EANCOM, EDIFACT, Edig@s, HIPAA, HL7, NCPDP, PADIS, TRADACOMS, and
X12.

When to Use the EDI to XML Module

Consider using the EDI to XML module when you

Want to visually inspect the data and structure of an EDI document

Need to convert an EDI document that does not conform to an EDI standard

Want to create a conversion definition that allows you to convert other nonconforming EDI documents

Want to experiment with different XML Converter settings to see how they affect the
conversion process and the resulting XML

Want to create scenarios that use different EDI documents, based on different EDI
standards, or that use different XML Converter settings
You can perform all of these operations and others using the EDI to XML editor.
This section covers the following topics:

The EDI to XML Editor on page 317

The SEF File on page 318

Choosing an EDI Document on page 319

EDI to XML Conversions and EDI Standards on page 319

EDI XML Conversions and EDI Definitions on page 342

316

Stylus Studio User Guide

What is the EDI to XML Module?

The EDI to XML Editor

The EDI to XML editor is a visual editor that helps you create a conversion file that can
be used to convert EDI documents to XML and to preview the XML that results from that
conversion. The conversion file you create can be saved and used to convert other EDI
documents with the same structure to XML.

Figure 190. EDI to XML Editor with Preview Window Displayed

You can use the EDI to XML editor to:

View an EDI file you want to convert to XML. The EDI document pane shows any
errors in the file that is, how the file deviates from the EDI standard on which it is
based and provides Quick Fixes and other tools to help you correct the errors.

Customize EDI standard definitions to accommodate proprietary or non-conforming

EDI. By default, the EDI structure pane displays the structure of the EDI standard
associated with the EDI document displayed in the EDI document pane, but you can
change both the dialect and version to display the structure for any of the numerous
dialects supported by DataDirect XML Converter.

Stylus Studio User Guide

317

Converting EDI to XML

You can import a local copy of EDI standard definitions and modify them in
numerous ways adding new values to a code list, changing a segments Requirement
property from Mandatory to Optional, and so on. See Customizing an EDI Standard
on page 340 for more information on this topic.
Specify properties for the DataDirect XML Converter. The EDI to XML module uses
the DataDirect XML Converter engine to convert EDI to XML. See Specifying
XML Converter Properties on page 339 for more information on this topic.
Preview the EDI to XML conversion. When you click the Preview Result button ( ),
Stylus Studio opens the Preview window and displays the XML that results from
converting the source EDI document using the parameters specified for the XML
Converter engine as well as changes made to the EDI standard, if any.

Using Undo
Undo (Edit > Undo, or Ctrl+z) is supported throughout the EDI to XML editor. For
example, you can undo changes made to

The URI field

The Dialect and Version drop-down lists

Nodes in the EDI structure pane

Tip Use Undo to undo changes incrementally. If you want to undo all of the changes you have

made to the EDI structure definition, use the Restore Definition feature. See Undoing
Customizations on page 358 for more information.

The SEF File

While you can use the EDI to XML module to convert individual EDI documents to XML,
the modules main purpose is to allow you to develop a set of conversion settings that can
be captured and then reused to convert to XML other EDI documents with the same
structure. These settings are saved in a Standard Exchange Format (SEF) file (.sef) that
is created when you save your work in the EDI to XML editor.
The SEF file contains information about any EDI definitions that you might have
imported and changed, as well as changes to the XML Converter properties default
values. The structure information for supported EDI dialects and versions remains with
the XML Converter, ensuring that the SEF file remains very small.
Once you create a SEF file, you can use it to convert other EDI documents in one of these
ways:

318

Stylus Studio User Guide

What is the EDI to XML Module?

Referencing it in the converter:EDI URI scheme the user= property allows you to
specify the URI of a SEF file. (The easiest way to make changes to the converter: URI
scheme is through the XML Converter properties. See Specifying XML Converter
Properties on page 339 and EDI XML Converters Properties Reference on
page 375 for more information on these topics.)
Invoking the setEDIExtension() method that is part of the XML Converter API. This
method is available in both Java and .NET interfaces. See How XML Converters are
Used in Stylus Studio on page 214 for more background information on the
DataDirect XML Converter in Stylus Studio, or refer to the DataDirect XML
Converter documentation that is part of your Stylus Studio installation
\components\XML Converters for .NET and \components\XML Converters for Java
where you installed Stylus Studio.
Open the SEF file in Stylus Studio and create a new scenario using a new EDI
document as the source document you want to convert to XML.

Choosing an EDI Document

When choosing an EDI document from which you want to create an EDI to XML
conversion, consider using one that is representative of other EDI documents you need to
convert to XML. You might need to create multiple EDI to XML conversions for the types
of EDI documents you typically convert to XML. But when the EDI documents you need
to convert to XML have the same dialect and version, for example, consider creating one
EDI to XML conversion to convert both documents.

EDI to XML Conversions and EDI Standards

An EDI to XML conversion can become associated with an EDI standard (dialect and
version) in one of two ways:

Stylus Studio infers the EDI standard based on the source EDI document that is being
used to create the EDI to XML conversion

You can specify the EDI standard explicitly (whether or not you are using a source
EDI document)

Stylus Studio User Guide

319

Converting EDI to XML

The EDI dialect and version associated with an EDI to XML conversion is always
displayed in the EDI to XML editor.

Figure 191. EDI Dialect and Version Controls

You can change the EDI dialect and/or version any time you are working with the EDI to
XML editor using the Select Dialect and Select Version fields.

Creating an EDI to XML Conversion

This section describes how to create an EDI to XML conversion and how to save your
work as a SEF file.
You can base your EDI to XML conversion on

An existing EDI document. Use this method when you have a sample EDI document
that is representative of other documents in your enterprise that will need to be
converted to XML.

An EDI standard. Use this method when you do not have a sample EDI document but
know how your proprietary EDI differs from one of the EDI standards (dialect and
version) supported by Stylus Studio.
The following sections use sample files installed with Stylus Studio to illustrate the
conversion process and features of the EDI to XML module. See Example: Converting
a Conforming EDI File on page 323 and Example: Converting a Non-conforming EDI
File on page 326 for more information.

Using an EDI Document

To create an EDI to XML conversion using an EDI document:

320

Select File > New > EDI to XML Conversion from the Stylus Studio menu.
The New EDI to XML Conversion dialog box appears.

In the Select a sample EDI document field, type the URI for the EDI document you
want to use as the model for your EDI to XML conversion.
Stylus Studio User Guide

Creating an EDI to XML Conversion

Alternative: Use the more button ( ) to locate the EDI document.

When you select the document, the EDI dialect and version on which it is based are
displayed in the Dialect and Version fields in the Select the dialect and version you
need to customize group box.
3.

Click OK.
The EDI to XML editor appears. The EDI document is displayed in the EDI
document pane; the EDI structure for the EDI standard on which the document is
based is displayed in the EDI Structure pane.

To save your work in the EDI to XML editor, select File > Save from the Stylus Studio
menu.
Stylus Studio displays the Save As dialog box, prompting you to save the file with a
.sef extension.

Using an EDI Standard

To create an EDI to XML Conversion using an EDI standard:
1.

Select File > New > EDI to XML Conversion from the Stylus Studio menu.
The New EDI to XML Conversion dialog box appears.

Select the Select the dialect and version you need to customize radio button.

Use the Dialect and Version fields in the Select the dialect and version you need to
customize group box to select the dialect and version of the EDI standard you want
to customize.

Click OK.
The EDI to XML editor appears. The EDI structure for the EDI standard you selected
is displayed in the EDI Structure pane. The EDI document pane is empty.
You can change the dialect and version using the drop-down lists at the top of the EDI
to XML editor.

To save your work in the EDI to XML editor, select File > Save from the Stylus Studio
menu.
Stylus Studio displays the Save As dialog box, prompting you to save the file with a
.sef extension.

Stylus Studio User Guide

321

Converting EDI to XML

Previewing an EDI to XML Conversion

The EDI to XML module uses the Stylus Studio scenarios feature to help you preview the
results of your EDI to XML conversion. A scenario is a collection of information in the
case of an EDI to XML conversion, an EDI input document and output URI that you
can save and reuse to test how different EDI customizations and XML Converter settings
affect the conversion of an EDI document to XML.
When you create an EDI to XML conversion using an EDI document, Stylus Studio
automatically creates a scenario that specifies that EDI document as the EDI input for the
EDI to XML conversion. You can change the EDI input document, or create another
scenario using a different EDI document, on the Scenario Properties dialog box.
To display the Scenario Properties dialog box:

Click the Edit scenario properties button ( ) on the EDI to XML editor tool bar.
Alternative: Select EDI > Scenario Properties from the Stylus Studio menu.
Alternative: Select Create Scenario from the scenario drop-down list on the EDI to
XML editor tool bar.

Figure 192. Scenario Properties Dialog Box

Active Scenario Is Previewed

As you create new scenarios, they are listed in the Existing Scenarios field. The scenario
selected in this list is the active scenario when you preview the EDI to XML conversion,
the active scenario is the one that is being run. You can specify a different active scenario
322

Stylus Studio User Guide

Example: Converting a Conforming EDI File

by selecting it in this list, but it can be more convenient to select it from the Create
Scenario from the scenario drop-down list on the EDI to XML editor tool bar:

Figure 193. Setting the Active Scenario

When you choose a new active scenario, Stylus Studio uses the EDI input and output URI
specified in the scenario when you preview the EDI to XML conversion.

How to Preview an EDI to XML Conversion

To preview an EDI to XML conversion:
1.

Select the scenario you want to preview from the scenario drop-down list on the EDI
to XML editor tool bar.

Click the Preview Result ( ) button.

Alternative: Select EDI > Preview Result from the Stylus Studio menu.

Example: Converting a Conforming EDI File

This section describes how to convert an EDI file to XML using the Stylus Studio EDI to
XML module. It uses the 831.x12 EDI file, which is installed in the \EDItoXML\EDI files
folder where you installed Stylus Studio. This file conforms to the X12 EDI standard, and
contains no errors.
To convert 831.x12 to XML:
1.

Select File > New > EDI to XML Conversion from the Stylus Studio menu.
The New EDI to XML Conversion dialog box appears.

In the Select a sample EDI document field, type the URI for the 831.x12 EDI file.

Stylus Studio User Guide

323

Converting EDI to XML

Alternative: Use the more button ( ) to locate 831.x12.

When you select the document, X12 is displayed in the Dialect field and 004030 is
displayed in the Version field in the Select the dialect and version you need to
customize group box.
3.

Click OK.
The EDI to XML editor appears. The 831.x12 EDI file you selected in Step 2 is
displayed in the EDI document pane. The message in the status bar (No errors found)
indicates that the 831.x12 EDI file has no errors.
The EDI Structure pane displays information for X12 version 004030 from the
DataDirect XML Converter repository. Stylus Studio uses this information to parse
and validate the source EDI document associated with this EDI to XML conversion.
Since the 831.x12 EDI file has no errors and appears to conform to the X12 standard,
it is ready to be converted to XML. (For information on addressing errors in EDI files,
see Resolving EDI Document Errors on page 332.)

Figure 194. 831.x12 EDI Before Conversion

324

To convert the 831.x12 EDI file to XML, click the Preview Result button ( ).
The Save As dialog box appears, requesting that you save your EDI to XML
conversion as a SEF file.

Stylus Studio User Guide

Example: Converting a Conforming EDI File

Provide a name for the file and click the Save button.
Stylus Studio opens the Preview window and displays the XML that results from
converting the 831.x12 EDI file.

Figure 195. 831.x12 Converted to XML

Note that no changes were made to either the EDI structure for the X12 standard or to the
default converter settings used by the XML Converter engine (as shown in the URI field).
Sometimes you will need or want to create local copies of EDI standards definitions or
change properties used by the XML Converter engine. These topics are discussed in the
following example, Example: Converting a Non-conforming EDI File on page 326, as
well as in greater detail in Specifying XML Converter Properties on page 339 and
Customizing an EDI Standard on page 340.

Stylus Studio User Guide

325

Converting EDI to XML

Example: Converting a Non-conforming EDI File

This section describes how to convert the code99.x12 EDI file to XML using the Stylus
Studio EDI to XML module. This file is installed in the \EDItoXML\EDI files folder where
you installed Stylus Studio.
The code99.x12 EDI file uses a proprietary X12 format one that is based on the X12
standard but uses enterprise-specific code lists and code list values. This example shows
how to modify the XML Converter properties and local EDI definitions to accommodate
this proprietary X12 format.
To convert code99.x12 to XML:

326

Select File > New > EDI to XML Conversion from the Stylus Studio menu.
The New EDI to XML Conversion dialog box appears.

In the Select a sample EDI document field, type the URI for the code99.x12 EDI file.
Alternative: Use the more button ( ) to locate code99.x12.
When you select the document, X12 is displayed in the Dialect field and 004030 is
displayed in the Version field in the Select the dialect and version you need to
customize group box.

Click OK.
The EDI to XML editor appears. The code99.x12 EDI file you selected in Step 2 is
displayed in the EDI document pane.
The message in the status bar (No errors found) indicates that the code99.x12 EDI file
has no errors. Or at least none that is apparent based on the default settings for the
properties used by the XML Converter engine.
By default, the XML Converter engine does not validate code list tables. However,
since our application development policy requires that we validate code lists, we need
to change the code list validation property.

Stylus Studio User Guide

Example: Converting a Non-conforming EDI File

To display the property settings for the XML Converter, click the more button (
to the right of the converter URI field.
Stylus Studio displays the Select XML Converters Properties dialog box.

Figure 196. Select XML Converter Properties Dialog Box

The property that controls code list validation is Force error if value not in code list
(tbl).
5.

Change the value for tbl to yes and click OK.

When you make a change to the SEF file, as we have just done by changing the XML
Converter properties associated with it, Stylus Studio reloads the source EDI
document after a moment. This occurs automatically, but you can force it by clicking
the Waiting to reload document text in the status bar. You can also change the delay
(by default, it is 5 seconds) in the Options dialog box (Tools > Options > Module
Settings > EDI to XML).
See Working with Code Lists on page 337 for more information on code list
validation.

Stylus Studio User Guide

327

Converting EDI to XML

With code list validation on, we see that our EDI source document contains an error
(indicated by a red squiggle at the errors location in the EDI document pane. If you
hover the pointer over the red squiggle, a tool tip provides more information about the
error:

Figure 197. Tool Tips for Errors in EDI Documents

328

When we alert our provider to this error, he informs us that all EDI documents he
provides us for processing will include this code value in the Transaction Set Purpose

Stylus Studio User Guide

Example: Converting a Non-conforming EDI File

Code code list, as it does in the code99.x12 EDI file we are using to build our EDI to
XML conversion:

Figure 198. Clicking the EDI Document Back-maps to the EDI Structure
7.

If we click line BGN:99:88200001:20041201 in the EDI document panel, Stylus Studio

back-maps to the corresponding node in the EDI Structure tree. This allows us to see

Stylus Studio User Guide

329

Converting EDI to XML

that the Transaction Set Purpose Code code list value 99 is not defined in the X12
standard:

Figure 199. EDI Value Not Present in EDI Standard

We know we can ignore the error by suppressing code list validation (as seen earlier
in this example). But to accommodate the new code value, we need to add it to the
Transaction Set Purpose Code code list. We do this by modifying a local copy of the
Transaction Set Purpose Code code list to include code 99. This modification to the
standard will exist only in the SEF file that is used to convert other files of this type;
we are not changing the definition of the EDI standard in the DataDirect XML
Converter repository.

330

Stylus Studio User Guide

Example: Converting a Non-conforming EDI File

In the EDI Structure pane, right-click 353:Transaction Set

Add > Code from the shortcut menu.
Stylus Studio displays the Code Definition dialog box.

Purpose Code and choose

Figure 200. Code Definition Dialog Box

Enter 99 in the Value field; enter Status Under Review in the Description field, and
click OK.
The values in the Transaction Set Purpose Code code list tree are displayed in bold,
indicating that this definition (and any changes to it) is local, stored in the SEF file
that represents our EDI to XML conversion. (For more information, see
Customizing an EDI Standard on page 340.)
After a moment, Stylus Studio reloads the source EDI document. The red squiggle
does not appear because we have added 99 to the code list table; the status bar displays
an OK symbol ( ) and the message, No errors found. The EDI to XML conversion
can now be tested.

10.

To convert the code99.x12 EDI file to XML, click the Preview Result button (
The Save As dialog box appears, requesting that you save your EDI to XML
conversion as a SEF file.

11.

Provide a name for the file and click the Save button.
Stylus Studio opens the Preview window and displays the XML that results from
converting the code99.x12 EDI file

Stylus Studio User Guide

331

Converting EDI to XML

Resolving EDI Document Errors

This section describes the features of the EDI to XML editor that help you identify and
resolve errors in the EDI document you are using as a model for creating the EDI to XML
conversion. It covers the following topics:

What Is an EDI Document Error? on page 332

How Errors Are Represented on page 333

Locating Data Errors on page 334

Displaying Information about Errors on page 334

Correcting Dialect and Version Errors on page 335

Quick Fixes on page 335

What Is an EDI Document Error?

An EDI document error is any value in the document that is inconsistent with the EDI
standard on which the document is based. Examples of errors include

Mis-matched EDI dialect or version

Missing mandatory segments and elements

Segments that are out of order

Code list values that are not defined in the EDI standard

332

Stylus Studio User Guide

Resolving EDI Document Errors

How Errors Are Represented

EDI document errors are represented using colors and symbols in the EDI document pane,
as summarized in the following table.
Table 46.
Error Type

Example

Description

Incorrect EDI dialect

A red background
indicates that the EDI
dialect specified in the
document does not agree
with the dialect specified
in the EDI to XML editor.

Incorrect EDI version

A yellow background
indicates that the EDI
version specified in the
document does not agree
with the version specified
in the EDI to XML editor.

Data error

A red squiggle indicates

that the EDI document
contains data that is
inconsistent with the EDI
standard on which the
document is based.

The number of data errors identified is summarized in the status bar. Prev and Next
buttons (and their keyboard equivalents) help you navigate from one error to the next.
Note that incorrect dialect and version are not included in this count.

Figure 201. Errors are Summarized in Status Bar

Stylus Studio User Guide

333

Converting EDI to XML

Locating Data Errors

You can locate data errors by searching the document visually. An alternative is to use
tools in the EDI to XML editor to move the cursor from one error to the next to ensure
that you do not overlook any errors that might affect the conversion process or the
composition of your SEF file:

F4 and Next button in the status bar moves the cursor to the next error in the source
EDI document

Shift+F4 and the Prev button in the status bar moves the cursor to the previous error
in the source EDI document
When the cursor stops on an error in the EDI document, Stylus Studio expands the
corresponding node in the EDI Structure tree to show the related EDI definition. The
Properties window also shows properties for that definition.

Displaying Information about Errors

Once you locate an error, hover the pointer over the error (the red squiggle for data errors;
the red or yellow background for EDI dialect or version errors) to display a tool tip:

Figure 202. Tool Tips for Errors in EDI Documents

The tool tip provides information about the error and suggestions for correcting it.

334

Stylus Studio User Guide

Resolving EDI Document Errors

Correcting Dialect and Version Errors

To correct a dialect or version error, right-click the line with the red or yellow background
in the EDI document pane and choose the appropriate fix from the shortcut menu:

Figure 203. Fixing a Version Error

Stylus Studio changes the value in the Select Dialect or Select Version fields at the top of
the EDI to XML editor and the red or yellow background is cleared.
Note that you can change the dialect and version manually any time you need using the
drop-down lists:

Figure 204. Dialect and Version Fields

Note When the SEF file is being used to convert an EDI document to XML, whether in Stylus

Studio or programmatically, using DataDirect XML Converter, the EDI standard

declared in the EDI document and not the values shown in the EDI to XML editor
establishes the dialect and version used to parse the document for conversion. Any locally
defined definitions in the SEF file are used during the conversion as well.

Quick Fixes
The Quick Fixes feature displays one or more ways to address a given error. Quick Fixes
is available for data errors only.

Stylus Studio User Guide

335

Converting EDI to XML

To display Quick Fixes choices, right-click on a document error (the red squiggle) in the
EDI document pane and choose Quick Fixes from the shortcut menu. The menu displays
the fixes that are available for the current error:

Figure 205. Sample Quick Fixes Menu

Fixes (when there is more than one) are listed in increasing order of scope when
possible, the scope of the first choice is limited to the current error (or class of error) only;
other fixes listed are typically broader in scope (turning off a type of checking or
validation, for example).

How Quick Fixes Works

Quick Fixes typically provides the following suggestions for addressing errors in the EDI
document:

Change the value of a property in the EDI structure. For example, error DDEE0004
indicates that a mandatory element was missing. One Quick Fix for this type of error
is to change that elements Requirement property from Mandatory to Optional. This
results in importing a local copy of the segments definition to the SEF file and
changing the elements Requirement property. This change affects the specific
definition only and might be appropriate if you want to do validation in general, but
in this specific context, you do not require a value for the element.
You can import and change EDI standard definitions at any time. See Customizing
an EDI Standard on page 340 for more information.

Ignore a specific error number in this example, ignore all DDEE0004 errors. This
has the effect of treating all elements as optional. This is appropriate if you want to
convert the data without checking if all mandatory elements are present.

Change an XML Converter property. In this example, the suggestion would be to use
opt=yes, which treats all elements and segments as optional. This is appropriate if you
want to convert the data and do little or no validity checking.
You can change the XML Converter properties at any time. See Specifying XML
Converter Properties on page 339 for more information.

336

Stylus Studio User Guide

Resolving EDI Document Errors

Working with Code Lists

EDI dialects are typically associated with one or more code lists, tables that contain a set
of codes and their descriptions that can be used to validate EDI segments and messages.
Code list validation is controlled by the tbl XML Converter property in the Select XML
Converter Properties dialog box, shown here.

Figure 206. tbl= Property Controls Code List Validation

Enabling Code List Validation

By default, Stylus Studio does not perform code list validation against the EDI you are
converting to XML (tbl=no). To enable code list validation, set tbl=yes. For an example
of code list validation, see Example: Converting a Non-conforming EDI File on
page 326.

Handling Missing Values

When validation is on, the XML Converters engine raises an error for any missing or
unrecognized code list values. You can handle missing or unrecognized values in one of
two ways. You can:

Add missing values to a local copy of the EDI standard code list.

Add a special value, ... that suppresses code list validation for that table only.
When you enter ... for a code list value, any elements with values not in the codelist are
treated as valid. Further, if you provide a description for the ... code list value when you
create the code, that value is output in the XML comments. Here, for example, any
Stylus Studio User Guide

337

Converting EDI to XML

missing values from the Piece Identification Indicator code list table are output to XML
with the comment missing:

Figure 207. Providing Descriptions for Missing Code List Table Values

Note that the ... code value affects code list validation only for the table for which it was
created. Code list validation for other tables is unaffected.
See Example: Converting a Non-conforming EDI File on page 326 for an example of
modifying a code list; see Creating a Code on page 354 to learn how to add a value to
a code list.
Tip You can add the ... code list value on-the-fly using the Quick Fixes feature. See Quick

Fixes on page 335 for more information.

338

Stylus Studio User Guide

Specifying XML Converter Properties

The EDI to XML module uses the DataDirect XML Converter engine to convert EDI
documents to XML. You specify the properties you want the XML Converter engine to
use for your EDI to XML conversion in the Select XML Converter Properties dialog box:

Figure 208. Select XML Converter Properties Dialog Box

The settings you specify here are saved with the SEF file for your EDI to XML conversion
and are displayed in the URI field (in converter:EDI URI scheme format) at the top of the
EDI to XML editor.
See EDI XML Converters Properties Reference on page 375 for detailed information
about XML Converter properties.
To display the Select XML Converters dialog box:

Click the Edit Converter Properties button (

) in the URI field.

About the Converter URI

The converter URI scheme (converter:EDI) provides the property settings that are used by
the XML Converter engine. Note that it displays only properties whose settings you have
changed default values used by the XML Converter are not displayed.
See The Converter URI Scheme on page 269 to learn more about the converter URI
scheme and how it is used in Stylus Studio and by DataDirect XML Converter.

Stylus Studio User Guide

339

Converting EDI to XML

Customizing an EDI Standard

This section describes the DataDirect XML Converter EDI standards repository and how
to create customized EDI definitions for your EDI to XML conversions. It covers the
following topics:

The EDI Standards Repository on page 340

Ways to Customize an EDI Standard on page 341

EDI XML Conversions and EDI Definitions on page 342

Views of the EDI Structure on page 342

Creating New Structure Definitions on page 344

Modifying Existing Definitions on page 348

Modifying Definition Properties on page 355

Importing EDI Standard Definitions on page 356

Undoing Customizations on page 358

Removing a Definition on page 359

The EDI Standards Repository

The DataDirect XML Converter installed with Stylus Studio includes a repository of all
the EDI standards it supports ATIS, Cargo-IMP, EANCOM, EDIFACT, Edig@s,
HIPAA, HL7, NCPDP, PADIS, TRADACOMS, and X12 dialects, and most recent and
current versions of these dialects. A filtered view of the repository is displayed in the EDI
Structure pane, which shows definitions for the EDI standard specified in the Select
Dialect and Select Version fields.
If you use an EDI document to create your EDI to XML conversion, the EDI dialect and
version are inferred from the source document. You can change the dialect and/or version
to view definitions for another EDI standard any time you choose.
The EDI Structure pane also shows any new definitions you have created or existing
definitions you have modified. For more information, see Ways to Customize an EDI
Standard on page 341 and Views of the EDI Structure on page 342.

340

Stylus Studio User Guide

Customizing an EDI Standard

Ways to Customize an EDI Standard

There are several ways to customize an EDI standard to reflect proprietary EDI formats.
You can:

Modify definitions in a local copy of the EDI standard add a value to a code list,
remove a segment reference, and so on.

Change definition properties change a requirement from mandatory to optional,

choose to rename the definition when it is output to XML, and so on.

Import definitions you might want to import code list values from a current EDI
standard into an EDI to XML conversion based on a prior standard, for example.

What Happens When You Customize a Standard

When you customize an EDI standard by changing a definition, Stylus Studio imports a
copy of that definition into your EDI to XML conversion that reflects the changes you
made to the EDI standard definition. This local copy of the EDI standard definition
remains with your EDI to XML conversion in the SEF file unless you restore the standard
definition.
All imported definitions whether imported implicitly (by changing a property, for
example) or explicitly are displayed in bold text in the EDI Structure pane. In the
following illustration, for example, the segment reference DFI: Default Information has
been added to the transaction message 831: Application Control Totals.

Figure 209. Bold Text Shows Changes to Standard Definition

Here, both 831: Application Control Totals and Group 1: AMT are shown in bold because
those definitions have changed based on the addition of the DFI: Default Information
segment reference.

Stylus Studio User Guide

341

Converting EDI to XML

Creating New Definitions

In addition to making changes to definitions from an EDI standard, you can create new
definitions for messages, segments, elements, composites, and code lists. These
definitions are added to the local definitions that are part of your EDI to XML conversion,
along with any EDI standard definitions that you have customized. New definitions are
also shown using bold text in the EDI Structure pane.
See Creating New Structure Definitions on page 344 for more information.

EDI XML Conversions and EDI Definitions

When you use an EDI to XML conversion to convert an EDI document to XML, the
DataDirect XML Converter engine uses

The EDI dialect and version declared in the EDI document you are converting

Any customized definitions you have created (shown in bold in the EDI Structure
pane)

XML Converter properties specified in the converter:EDI URI

The SEF file associated with your EDI to XML conversion does not contain any
information about the EDI standard displayed in the EDI to XML editor. Rather, the XML
Converter engine uses its knowledge about the EDI standard (from the repository) for the
document being converted, along with any changes to the standard for those definitions
that you have created or modified.

Views of the EDI Structure

The EDI Structure pane provides two views to help you build your EDI to XML
conversion:

The complete specification for the EDI standard you have selected, including local
definitions

Only local definitions that you have imported to the SEF

342

Stylus Studio User Guide

Customizing an EDI Standard

You use the Show Full Dialect Specification button (

) to toggle between these views.

Figure 210. EDI Structure Pane Shows Full or Local Specification

When you create an EDI to XML conversion (whether based on an EDI document or
starting directly from an EDI standard), the EDI Structure pane makes the complete
specification accessible just expand a node to view a definition, and its properties appear
in the Properties window.

Figure 211. Full Specification

As you build your EDI to XML conversion and make changes to the EDI standard, you
might want to simplify the view in the EDI Structure pane to display only those local
definitions. In the following illustration, the segments A1, A2, and AC have all been

Stylus Studio User Guide

343

Converting EDI to XML

imported from repository. These definitions, which are shown in bold, reside in the SEF
file that represents your EDI to XML conversion.

Figure 212. Imported Definitions

Creating New Structure Definitions

A structure definition is a top-level definition in an EDI Structure:

Message

Segment

Element

Composite

Code list
Structure definitions can be created from anywhere in the EDI Structure that is, context
(as shown by cursor placement or focus) does not matter. New structure definitions are
placed in the appropriate EDI structure folder, sorted alphanumerically. Creating a new
structure definition does not affect existing definitions in the EDI Structure.
This section covers the following topics:

Adding a Message on page 345

Adding a Segment on page 345

Adding an Element on page 346

Adding a Composite on page 347

Adding a Code List on page 347

For information on creating context-specific definitions (code list values, segment
references, and similar definitions, see Modifying Existing Definitions on page 348.

344

Stylus Studio User Guide

Customizing an EDI Standard

Adding a Message
To add a message:
1.

Right-click any node in the EDI Structure and select New Definition > Message from
the shortcut menu.
Alternative: Select EDI > New Definition > Message from the Stylus Studio menu.
The Message Definition dialog box appears.

Figure 213. Message Definition Dialog Box

Enter a message name and, optionally, a description.

Click OK.
The message definition is added to the existing transaction messages in the EDI
Structure; new messages are sorted in alphanumeric order.

Adding a Segment
To add a segment:
1.

Right-click any node in the EDI Structure tree and select New Definition > Segment
from the shortcut menu.
Alternative: Select EDI > New Definition > Segment from the Stylus Studio menu.

Stylus Studio User Guide

345

Converting EDI to XML

The Segment Definition dialog box appears.

Figure 214. Segment Definition Dialog Box

Enter a segment name and, optionally, a description.

Click OK.
The segment definition is added to the existing segments in the EDI Structure; new
segments are sorted in alphanumeric order.

Adding an Element
To add an element:
1.

Right-click any node in the EDI Structure and select New Definition > Element from
the shortcut menu.
Alternative: Select EDI > New Definition > Element from the Stylus Studio menu.
The Element Definition dialog box appears.

Figure 215. Element Definition Dialog Box

346

Stylus Studio User Guide

Customizing an EDI Standard

Enter an element name and specify a data type (the default is AN Alphanumeric).

Optionally specify minimum and maximum lengths and a description.

Click OK.
The element definition is added to the existing elements in the EDI Structure; new
elements are sorted in alphanumeric order.

Adding a Composite
To add a composite:
1.

Right-click any node in the EDI Structure and select New Definition > Composite
from the shortcut menu.
Alternative: Select EDI > New Definition > Composite from the Stylus Studio menu.
The Composite Definition dialog box appears.

Figure 216. Composite Definition Dialog Box

Enter a composite name and optionally specify a description.

Click OK.
The composite definition is added to the existing composites in the EDI Structure;
new composites are sorted in alphanumeric order.

Adding a Code List

To add a code list:
1.

Right-click any node in the EDI Structure and select New Definition > Code List from
the shortcut menu.
Alternative: Select EDI > New Definition > Code List from the Stylus Studio menu.

Stylus Studio User Guide

347

Converting EDI to XML

The Code List Definition dialog box appears.

Figure 217. Code List Definition Dialog Box

Enter a code list name and click OK.

The code list definition is added to the existing code lists in the EDI Structure; new
code lists are sorted in alphanumeric order.

See Creating a Code on page 354 to learn how to add values to a code list.

Modifying Existing Definitions

In addition to creating new definitions, you can also modify existing definitions in an EDI
Structure. For example, you can add an element reference to an existing composite. When
you modify an existing definition, Stylus Studio imports a local copy of this definition
from the EDI repository and places it in your EDI to XML conversion. Imported
definitions are displayed in bold in the EDI Structure pane in the EDI to XML editor. See
Ways to Customize an EDI Standard on page 341 for more information on this topic.
This section covers the following topics:

Adding versus Inserting on page 348

Creating a Segment Reference on page 349

Creating a Group on page 350

Creating an Element or Composite Reference on page 351

Creating a Repetition on page 353

Creating a Variation on page 353

Creating a Code on page 354

You can also modify an existing definition by changing one of its properties. See
Modifying Definition Properties on page 355 for more information.

Adding versus Inserting

You modify an existing definition by adding or inserting another definition to it.

348

Stylus Studio User Guide

Customizing an EDI Standard

When you add a definition, it is added to the end of the existing definition. For
example, if you add an element reference to a segment, the new element reference is
added after the last element reference currently defined for that segment.
To add a definition, choose Add from the shortcut or Stylus Studio menu.
When you insert a definition, you get to choose whether to place it before or after the
current definition. For example, if the focus is on a segment reference, you can choose
whether to place a new group before or after the segment reference.
To insert a definition, choose Insert After or Insert Before from the shortcut or Stylus
Studio menu.

Creating a Segment Reference

You can create a segment reference for a message or a group. You can reference an
existing segment or create a new segment and reference that.
To create a segment reference:
1.

Right-click the message or group definition to which you want to add the segment
reference and select Add > Segment Reference from the shortcut menu.
Alternative: Select EDI > Add > Segment Reference from the Stylus Studio menu.
The Add Segment Reference dialog box appears.

Figure 218. Add Segment Reference Dialog Box

Choose the segment you want to reference, or click New Segment to create a new
segment as your segment reference. See Adding a Segment on page 345 for
information on creating segments.

Stylus Studio User Guide

349

Converting EDI to XML

Choose the setting for the Modifier property you can leave this field blank, or you
can define the segment reference as Dependent, Must Be Used, Not Recommended,
Not Used, or Used.

Choose the setting for the Requirement property you can choose Conditional,
Facultative, Mandatory, or Optional.

Choose the setting for the Maximum Use, Ordinal, and Position property. You can use
the default values if appropriate.

Click OK to add the segment reference to the EDI Structure.

Creating a Group
You can create a group for a message or another group. You can use an existing segment
for the groups loop trigger or create a new segment and use that.
To create a group:
1.

Right-click the message or group definition to which you want to add the group and
select Add > Group from the shortcut menu.
Alternative: Select EDI > Add > Group from the Stylus Studio menu.
The Group Definition dialog box appears.

Figure 219. Group Definition Dialog Box

350

Choose the segment you want to use as the loop trigger, or click New Segment to
create a new segment as your loop trigger. See Adding a Segment on page 345 for
information on creating segments.

Stylus Studio User Guide

Customizing an EDI Standard

Optionally, specify a group label.

Choose the setting for the Modifier property you can leave this field blank, or you
can define the segment reference as Dependent, Must Be Used, Not Recommended,
Not Used, or Used.

Choose the setting for the Requirement property the default is Conditional, but you
can choose Facultative, Mandatory, or Optional.

Choose the setting for the Maximum Use property. You can use the default value if
appropriate. You can specify Ordinal or Position properties for a group definition only
if the Loop Sequence property for the EDI Structure is set to Enable.

Click OK to add the group to the EDI Structure.

Creating an Element or Composite Reference

You can create an element or composite reference for a segment, composite, repetition,
variation, or another element or composite reference. You can use an existing element or
composite for the element or composite reference, or create a new element or composite
and use that.
To create an element or composite reference:
1.

Right-click the definition to which you want to add the element or composite
reference and select Add > Element or Composite Reference from the shortcut menu.
Alternative: Select EDI > Add > Element or Composite Reference from the Stylus
Studio menu.

Stylus Studio User Guide

351

Converting EDI to XML

The Add Element or Composite Reference dialog box appears.

Figure 220. Add Element or Composite Reference Dialog Box

Choose the element or composite you want to reference, or click New Element or New
Composite to create a new element or composite to reference. See Adding an
Element on page 346 or Adding an Element on page 346 for information on
creating these definitions.

352

Choose the setting for the Modifier property you can leave this field blank, or you
can define the reference as Delete, Dependent, Must Be Used, Not Recommended,
Not Used, or Used.

Choose the setting for the Requirement property the default is Conditional, but you
can choose Facultatif (composite reference) or Dependent (element reference),
Mandatory, or Optional.

Enter the value for the Repeat Count, Minimum, Maximum, and Ordinal properties.
You can use the default value, if available and appropriate.

Click OK to add the reference to the EDI Structure.

Stylus Studio User Guide

Customizing an EDI Standard

Creating a Repetition
You can create a repetition for a segment, composite, segment or composite reference, or
another repetition. A repetition is created as a child of the definition. It is given the label
REPEAT in the EDI Structure.
To create a repetition:
1.

Right-click the definition for which you want to create a repetition and select Add >
Repetition from the shortcut menu.
Alternative: Select EDI > Add > Repetition from the Stylus Studio menu.
The repetition is added to the definition.

Creating a Variation
You can create a variation for a segment or a composite. A variation results in the cloning
of the segment or composite on which it is based. The original definition is given the label
in the EDI Structure of # Base; the first variation is labeled #1. Subsequent variations are
labeled #2, #3, and so on. The first # is the symbol for the tree node, and not part of the
name.
To create a variation:
1.

Right-click the definition for which you want to create a variation and select Add >
Variation from the shortcut menu.
Alternative: Select EDI > Add > Variation from the Stylus Studio menu.
The variation is added to the definition.

Stylus Studio User Guide

353

Converting EDI to XML

Creating a Code
You can add a code to an element, an element reference, a code list, or another code. You
can create a single code (99, for example) or a range of codes (AA to AZ, for example).
To create a code definition:
1.

Right-click the definition to which you want to add the code definition and select Add
> Code from the shortcut menu.
Alternative: Select EDI > Add > Code from the Stylus Studio menu.
The Code Definition dialog box appears.

Figure 221. Code Definition Dialog Box

354

If you want to create

A single code, enter a value in the Value field and, optionally, a description in the
Description field.

A range of codes, select the Range radio button, and enter range values in the
Begin and End fields.

Click OK to add the reference to the EDI Structure.

Stylus Studio User Guide

Customizing an EDI Standard

Modifying Definition Properties

The Properties window, like the one shown in the following illustration, allows you to edit
properties associated with the definition in the EDI Structure that currently has focus.

Figure 222. Properties Window

A definition gains focus when you

Click a line in the EDI document pane

Click a definition in the EDI Structure pane

The Properties is a docking window. By default, it is docked to the Stylus Studio window,
but you can drag it anywhere you like.
When you modify a definitions properties, Stylus Studio imports a local copy of this
definition from the EDI repository and places it in your EDI to XML conversion.
Imported definitions are displayed in bold in the EDI Structure pane. See Ways to
Customize an EDI Standard on page 341 for more information on this topic.
You can also modify an existing definition by adding new definitions to it. See
Modifying Existing Definitions on page 348 for more information.

Stylus Studio User Guide

355

Converting EDI to XML

Importing EDI Standard Definitions

This section describes how to import EDI standard definitions. You might want to do this,
for example, to import code list values from a more recent version of a dialect while
leaving the rest of the EDI standards on which your EDI to XML conversion is based
intact.
In the following example, we are importing the Late Reason Code code list from X12
version 005050 into our EDI to XML conversion, which is based on X12 version 004030,
to acquire a new code value LB = Awaiting Wage Amount Verification.
To import an EDI standard definition:

356

Open the EDI to XML conversion whose EDI structure you want to update by
importing an EDI Standard.

In the EDI Structure pane, select the definition you want to import.

Stylus Studio User Guide

Customizing an EDI Standard

Here, we have selected 9: Late Reason Code. Note that the last code defined for this
code list (in version 004030) is LA = Intermittent Lost Time Prior to First Payment.

Figure 223. EDI Structure

Change the value in the Select Version field to 005050.

This displays the EDI structure for X12 version 005050 in the EDI Structure pane.
Note that the Late Reason Code code list includes LB = Awaiting Wage Amount
Verification.

Right-click the code list 9: Late Reason Code, and choose Import Definition from the
shortcut menu.
This directs Stylus Studio to import the codes for this code list from X12 version
005050 into the local EDI Structure.

Change the version back to 004030 (since this is the version on which the EDI to
XML conversion is based).

Stylus Studio User Guide

357

Converting EDI to XML

Click the Show Full Dialect Specification button ( ). Note that the 9: Late Reason
Code code list appears in bold to indicate that a local copy of this definition has been
created.

Figure 224. Local Definitions in EDI Structure

Undoing Customizations
You can undo any customizations you make using the Restore feature in the EDI to XML
editor. When you undo a customization, the modified definition reverts to its EDI
standard, effectively removing it from the SEF file for your EDI to XML conversion.
Tip You can use Undo to undo changes incrementally, backing out changes one at a time. See

Using Undo on page 318 for more information.

358

Stylus Studio User Guide

Customizing an EDI Standard

To undo a change to an EDI standard definition:
1.

In the EDI Structure tree, select the modified EDI standard definition whose change
you want to undo.
Modified definitions are displayed in bold text. Use the Show Full Dialect
) to toggle the display of modified standards in the EDI
Structure tree.

Tip

Specification button (

Right-click the modified definition and select Restore Definition from the short cut
menu.
Alternative: Select EDI > Restore Definition from the Stylus Studio menu.
The modified definition reverts to its EDI standard; it is removed from the SEF file
for your EDI to XML conversion and no longer appears in bold text in the EDI
Structure tree.

Removing a Definition
In addition to adding and changing definitions, you can modify your local copy of an EDI
standard by removing a definition. You can remove the following definitions:

Composite references

Element references

Segment references

Groups

Repetitions

Variations
Use care when removing references and groups, as this can have unintended
consequences regarding the expected structure of an EDI document and numbering.
Tip If you want to remove a definition because that structure is never used by the EDI

documents in your organization, consider changing the definitions Modifier property to

Not used. This retains the definition in the EDI Structure, but instructs the XML
Converter engine to ignore it when converting EDI to XML.

Stylus Studio User Guide

359

Converting EDI to XML

To remove a definition:
1.

In the EDI Structure tree, select the definition you want to remove from the EDI
Structure.

Right-click the definition and select Remove from the short cut menu.
Alternative: Select Remove from the Stylus Studio menu.
The definition is removed from the EDI Structure tree.

Generating XQuery and XML Schema from EDI

Stylus Studio provides tools to help you generate XQuery and XML Schema from EDI
messages:

Generate XQuery/XML Schema use this tool when you are working in the EDI to
XML editor. The current context of the EDI dialect, version, and message type
provide much of the information used to generate the XQuery and/or XML Schema.
The SEF file associated with your EDI to XML Conversion also provides information
that has an impact on the generated XQuery/and or XML Schema.

EDI to XQuery document wizard use the EDI to XQuery document wizard when
you want to generate XQuery and/or XML Schema from an EDI message but are not
currently working in the EDI to XML editor.

Generate XQuery/XML Schema

The Generate XQuery/XML Schema tool lets you generate XQuery and/or XML Schema
based on the currently selected EDI message in the EDI to XML editor.
To use the Generate XQuery/XML Schema tool:

360

In the EDI to XML editor, select the EDI message for which you want to generate
XQuery and/or XML Schema from the EDI structure pane.

Select EDI > Generate XQuery/XML Schema from the menu.

Alternative: Right-click the EDI message and choose Generate XQuery/XML Schema
from the short-cut menu.

Stylus Studio User Guide

Generating XQuery and XML Schema from EDI

The Generate XQuery/XML Schema dialog box appears.

Figure 225. Generate XQuery/XML Schema Dialog Box

Specify the generation options as described in the following section, Generate

XQuery/XML Schema Dialog Box on page 361.

Click OK.

Generate XQuery/XML Schema Dialog Box

This section describes the fields of the Generate XQuery/XML Schema dialog box.
Message

Displays the name of the message; based on the message that was active in the EDI
Structure pane of the EDI to XML editor when you selected EDI > Generate
XQuery/XML Schema from the menu.
Mode

Whether the EDI is processed in batch or interactive mode. Valid for EANCOM,
EDIFACT, and IATA (Cargo-IMP and PADIS) only.
Create XQuery for this EDI Message A check box you use to indicate that you want to

generate XQuery for the EDI message.

XQ File The URI for the file to which the generated XQuery is written. By
default, this is Untitledn_name.xquery file, where n is a unique number and name
is the EDI message name abbreviation.

Stylus Studio User Guide

361

Converting EDI to XML

Mandatory segments and elements only Generates only those segments whose

Requirement property is mandatory and, for them, only the mandatory element
and composite references.
All segments but only mandatory elements Generates all segments, but, for
each of them, only the mandatory element and composite references.
All segments and elements Generates all segments, and all element and
composite references specified for them.

Create XML Schema for this EDI Message A check box you use to indicate that you
want to generate XML Schema for the EDI message.

XSD File The URI for the file to which the generated XML Schema is written.
By default, this is Untitledn_name.xsd file, where n is a unique number and name
is the EDI message name abbreviation.

Write annotations describing each element Whether or not you want the
generated XML Schema to include annotations that are part of the EDI message.

Enumerations for elements that have codelists Whether or not you want the
generated XML Schema to include enumerations for fields that have lists of
values.

Use unbounded for maxOccurs when loop value is 99 or higher) Replaces

maxOccurs values of 100 or greater with unbounded. This option ensures that
the generated XML Schema can be successfully validated by most processors.

EDI to XQuery Document Wizard

The EDI to XQuery document wizard lets you generate XQuery and/or XML Schema.
The document wizard gives you the flexibility to specify values such as the XML structure
and SEF file to use when generating output.
To use the EDI to XQuery document wizard:
1.

362

In the Stylus Studio, select File > Document Wizards from the menu.
The Document Wizard dialog box appears.

Stylus Studio User Guide

Generating XQuery and XML Schema from EDI

Click the XQuery tab and double-click the EDI to XQuery icon.
The Generate XQuery from EDI Standards dialog box appears.

Figure 226. Generate XQuery from EDI Standards Dialog Box

Specify the generation options as described in the following section, Generate

XQuery from EDI Standards on page 363.

Click OK.

Generate XQuery from EDI Standards

This section describes the fields of the Generate XQuery from EDI Standards dialog box.
Message

You use the fields in the Message group box to specify information about the EDI
standard for which you want to generate XQuery.

Stylus Studio User Guide

363

Converting EDI to XML

Dialect Drop-down list that lets you specify the EDI dialect for which you want

to generate XQuery.
Version Drop-down list that lets you specify the version for the EDI dialect you
selected.
Mode Whether the EDI is processed in batch or interactive mode. Valid for
EANCOM, EDIFACT, and IATA only.
Message/Description The specific EDI message for which you want to generate
the XQuery.

XML Structure

You use the fields of the XML Structure group box to specify the structure of the XML

Use long names for Whether or not you want to use the long element and/or
segment names as part of the XML tag UNB01-SyntaxIdentifier versus UNB01,
for example.

Wrap GROUP element around message groups Whether you want to wrap
a <GROUP> element around transaction messages. This can make message
groupings easier to handle with XPath for EDI document with multiple message
groups.

Prefix GROUP_N tags with the message name Adds the message name to the
GROUP_n prefix in the XML element tag. For example, <TS_831_GROUP_1>.

Put the data value in value= attributes Places code list data values in an value=
string in the element tag. For example, <BGN01 value="00"></BGN01>. By default, the data value is output to XML as text
(<BGN01>00</BGN01>).

Put decoded data values in decode= attributes Places decoded code list data
values in a decode= string in the element tag. For example, <ISA15
decode=Production Data>. By default, the decoded value is not output to XML.
XQuery Generate Options

You use the XQuery Generation Options group box to specify what EDI structures
you want represented in the generated XQuery. XQuery resulting from the document
wizard is output as an Untitledn.xquery file, where n is a unique number, directly to
the Stylus Studio desktop.

Mandatory segments and elements only Generates only those segments whose
Requirement property is mandatory and, for them, only the mandatory element
and composite references.

All segments but only mandatory elements Generates all segments, but, for
each of them, only the mandatory element and composite references.
364

Stylus Studio User Guide

EDI Structure Definitions Properties Reference

All segments and elements Generates all segments, and all element and

composite references specified for them.

Create XML Schema for this EDI Message

In addition to generating XQuery for an EDI message, you can choose to generate an
XML Schema for the same message at the same time. The fields in this group box
allow you to specify the settings that are used to generate the XML Schema for the
selected EDI message.

XSD File The URI for the XML Schema (.xsd) file that is output by the
document wizard.

Write annotations describing each element Whether or not you want the
generated XML Schema to include annotations that are part of the EDI message.

Enumerations for elements that have codelists Whether or not you want the
generated XML Schema to include enumerations for fields that have lists of
values.

Use unbounded for maxOccurs when loop value is 99 or higher) Replaces

maxOccurs values of 100 or greater with unbounded. This option ensures that
the generated XML Schema can be successfully validated by most processors.
SEF File The URI of the Standard Exchange Format (SEF) file, if any, you want to use

when generating XML in XQuery and XML Schema files. The SEF file can augment
information that Stylus Studio uses to generate XQuery and XML Schema customized
EDI definitions are stored in the SEF file, for example. If the same setting is specified by
both the document wizard and the SEF file, the SEF file value is used.

EDI Structure Definitions Properties Reference

This section provides reference information for the EDI Structure definition properties
displayed in the Properties window in the EDI to XML editor.
This section covers the following topics:

Code List Properties on page 366

Composite Properties on page 366

Composite Reference Properties on page 367

EDI Structure Properties on page 368

Element Properties on page 368

Element Reference Properties on page 369

Stylus Studio User Guide

365

Converting EDI to XML

Group Properties on page 370

Message Properties on page 371
Repetition Properties on page 372
Segment Properties on page 372
Segment Reference Properties on page 373
Transaction Message Properties on page 374

Code List Properties

Table 47. Code List Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Name

The name of the code list. Names are always uppercase.

Yes

Composite Properties
Table 48. Code List Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Name

The name of the composite. Names are always uppercase.

Yes

Description

The definition description. Can be mixed case.

Yes

Syntax Rules

The logic used when a composite references

<hyperlink>Requirement property is set to Conditional.

Yes

Rules entered in this field are preserved, but the rule is not
enforced at runtime.

366

Stylus Studio User Guide

EDI Structure Definitions Properties Reference

Composite Reference Properties

Table 49. Composite Reference Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Modifier

Indicates whether the composite reference is used in your

customized EDI structure. For new composite references, you
can leave this field empty. If you are modifying an existing
composite reference because you want to indicate that it is not
used in your customized EDI structure, set Modifier to Not
Used instead of removing it from the EDI structure.

Yes

Valid values for this property are Deleted, Dependent, Must

be used, Not recommended, Not used, Recommended.
Requirement

Whether the composite reference is Conditional, Dependent,

Mandatory, or Optional.

Yes

Note: If a Modifier is specified, it overrides the Requirement

at runtime.
Repeat
Count

The number of times the reference can occur within the

segment, composite, or other definition.

Yes

Ordinal

The references place within the segment, composite, or other

definition. This field is grayed out unless you have set the EDI
Structure <hyperlink>Loop Sequence Enabled property to
Enable.

Yes

Not available if the composite reference you are editing is part

of a composite (and not a segment).
Rename
XML Node

If present, this value is used instead of the composite

reference name to form the XML node name. The original
name is retained as an attribute in the XML tag.

Yes

Not available if the composite reference you are editing is part

of a composite (and not a segment).

Stylus Studio User Guide

367

Converting EDI to XML

EDI Structure Properties

Table 50. EDI Structure Properties
Property

Description

Editable

SEF Version

The SEF syntax version

Yes

Loop
Sequence
Enabled

Determines whether groups have their own ordinal and

position number.

Yes

Description

The definition description. Can be mixed case.

Yes

Element Properties
Table 51. Element Properties

368

Property

Description

Editable

Type

Yes

Stylus Studio User Guide

EDI Structure Definitions Properties Reference

Element Reference Properties

Table 52. Element Reference Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Modifier

Indicates whether the element reference is used in your

customized EDI structure. For new element references, you
can leave this field empty. If you are modifying an existing
element reference because you want to indicate that it is not
used in your customized EDI structure, set Modifier to Not
Used instead of removing it from the EDI structure.

Yes

Valid values for this property are Dependent, Must be used,

Not recommended, Not used, Recommended.
Requirement

Whether the element reference is Conditional, Dependent,

Mandatory, or Optional.

Yes

Note: If a Modifier is specified, it overrides the Requirement

at runtime.
Repeat
Count

The number of times the reference can occur within the

segment, composite, or other definition.

Yes

Minimum
Length

The elements minimum length.

Yes

Maximum
Length

The elements maximum length.

Yes

Ordinal

The references place within the segment, composite, or other

definition. Default value if present, has been calculated not to
interfere with other definitions.

Yes

Stylus Studio User Guide

369

Converting EDI to XML

Table 52. Element Reference Properties
Property

Description

Editable

Rename
XML Node

If present, this value is used instead of the element reference

name to form the XML node name. The original name is
retained as an attribute in the element tag.

Yes

Not applicable to element references defined in segment

references.
Append
Value to
XML Node

Allows you to append a code list value to the element tag of a

related node <ISA01_P tag="ISA01">, for example. This
allows you to create an XML Schema that can aid XML
mapping when the source XML document presents
name/value pairs as separate elements, you can effectively
collapse two nodes into one. The tag to which you append the
code list value is also given an attribute that identifies the
source of the code value to assist XML Converter when
converting XML to EDI.

Yes

Not available for element references defined in segment

references.

Group Properties
Table 53. Group Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Modifier

Indicates whether the group is used in your customized EDI

structure. For new groups, you can leave this field empty. If
you are modifying an existing group because you want to
indicate that it is not used in your customized EDI structure,
set Modifier to Not Used instead of removing it from the EDI
structure.

Yes

Valid values for this property are Dependent, Must be used,

Not recommended, Not used, Recommended.

370

Stylus Studio User Guide

EDI Structure Definitions Properties Reference

Table 53. Group Properties
Property

Description

Editable

Requirement

Whether the group is Conditional, Dependent, Mandatory, or

Optional.

the XML node name. The original name is retained as an
attribute in the element tag.

Yes

Message Properties
Table 54. Message Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Name

The name of the message. Names are always uppercase.

Yes

Stylus Studio User Guide

371

Converting EDI to XML

Table 54. Message Properties
Property

Description

Editable

Description

The definition description. Can be mixed case.

Yes

Rename
XML Node

If present, this value is used instead of the message name to

form the XML node name. The original name is retained as
an attribute in the XML tag.

Yes

Repetition Properties
Table 55. Repetition Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Repetition

The number of times the definition (segment, segment

reference, composite, composite reference, other repetition,
or variation) can be repeated.

Yes

Segment Properties
Table 56. Segment Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Name

The name of the segment. Names are always uppercase.

Yes

Description

The definition description. Can be mixed case.

Yes

Syntax Rules

The logic used when a segment references

<hyperlink>Requirement property is set to Conditional.

Yes

Rules entered in this field are preserved, but the rule is not
enforced at runtime.

372

Stylus Studio User Guide

EDI Structure Definitions Properties Reference

Table 56. Segment Properties
Property

Description

Editable

Allow
multiple tail
components

For the HL7 dialect, this property allows the last element
(whether composite or atomic) of that segment to repeat an
unlimited number of times (as long as the overall limit of 254
elements in a segment is not exceeded).

Yes

Valid values are True and False (the default).

Rename
XML Node

If present, this value is used instead of the segment name to

form the XML node name. The original name is retained as
an attribute in the XML tag.

Yes

Segment Reference Properties

Table 57. Segment Reference Properties
Property

Description

Editable

Type

A label that identifies the type of definition.

Modifier

Indicates whether the segment reference is used in your

customized EDI structure. For new segment references, you
can leave this field empty. If you are modifying an existing
segment reference because you want to indicate that it is not
used in your customized EDI structure, set Modifier to Not
Used instead of removing it from the EDI structure.

Yes

Valid values for this property are Dependent, Must be used,

Not recommended, Not used, Recommended.
Requirement

Whether the composite reference is Conditional, Facultatif,

Mandatory, or Optional.

Table 57. Segment Reference Properties
Property

Description

Editable

Position

The position within the associated message or group at which

the segment reference starts. Default value if present, has
been calculated not to interfere with other segments or groups
in the message.

Yes

Rename
XML Node

If present, this value is used instead of the segment reference

name to form the XML node name. The original name is
retained as an attribute in the XML tag.

Yes

Transaction Message Properties

See Message Properties on page 371.

374

Stylus Studio User Guide

EDI XML Converters Properties Reference

See Chapter 4, XML Converters Properties, in the DataDirect XML Converters
Users Guide and Reference for complete properties reference information for all
DataDirect XML Converters. information. Documentation for DataDirect XML
Converters is available:

In the \doc folder for DataDirect XML Converters where you installed Stylus Studio
\components\XML Converters for .NET\doc, for example

On the DataDirect Technologies web site:

http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp

Stylus Studio User Guide

375

Converting EDI to XML

376

Stylus Studio User Guide

Chapter 5

Working with XSLT

Stylus Studio provides many features for creating, updating, and applying stylesheets.
This section of the documentation covers the following topics:

Getting Started with XSLT on page 377

Tutorial: Understanding How Templates Work on page 401

Working with Stylesheets on page 413

Specifying Extension Functions in Stylesheets on page 430

Working with Templates on page 435

Using Third-Party XSLT Processors on page 440

Validating Result Documents on page 445

Post-processing Result Documents on page 446

Generating Formatting Objects on page 447

Generating Scalable Vector Graphics on page 453

Generating Java Code for XSLT on page 454

Generating C# Code for XSLT on page 460

XSLT Instructions Quick Reference on page 465

Getting Started with XSLT

This section provides an introduction to using Extensible Stylesheet Language
Transformations (XSLT). It discusses the following topics:

What Is XSLT? on page 378

What Is a Stylesheet? on page 379

Stylus Studio User Guide

377

Working with XSLT

What Is a Template? on page 382

How the XSLT Processor Applies a Stylesheet on page 385
Controlling the Contents of the Result Document on page 391
Specifying XSLT Patterns and Expressions on page 393
Frequently Asked Questions About XSLT on page 395
Sources for Additional XSLT Information on page 396
Benefits of Using Stylus Studio on page 397

What Is XSLT?
The Extensible Stylesheet Language (XSL) is the World Wide Web Consortium's (W3C)
language for manipulating XML data. XSLT is the component of XSL that allows you to
write a stylesheet that you can apply to XML documents. The result of applying a
stylesheet is that the XSLT processor creates a new XML, HTML, or text document based
on the source document. The XSLT processor follows the instructions in the stylesheet.
The instructions can copy, omit, and reorganize data in the source document, as well as
add new data.
XSL is an XML-based language. It was developed by the W3C XSL working group
within the W3C Stylesheets Activity. The W3C activity group has organized its
specification of XSL into three parts:

XPath specifies the syntax for patterns and expressions used in stylesheets. The XSLT
processor uses an XPath expression to execute a query on the source document to
determine which nodes to operate on. See Writing XPath Expressions on page 691.

XSLT specifies the syntax for a stylesheet that you apply to one XML document to
create a new XML, HTML, or text document.

XSL formatting object language is an XML vocabulary for specifying formatting

instructions.

What XSLT Versions Does Stylus Studio Support?

Stylus Studio X14 supports XSLT 1.0 and XSLT 2.0. XSLT 2.0 was designed to work
with XPath 2.0.
For more information on

XSLT 1.0, go to http://www.w3.org/TR/xslt

XSLT 2.0, go to http://www.w3.org/TR/xslt/20

378

Stylus Studio User Guide

Getting Started with XSLT

To learn more about the changes from XSLT 1.0 to XSLT 2.0, go to
http://www.w3.org/TR/xslt20/#changes.

What Is a Stylesheet?
A stylesheet is an XML document that contains instructions for generating a new
document based on information in the source document. This can involve adding,
removing, or rearranging nodes, as well as presenting the nodes in a new way.
This following topics provide more information:

Example of a Stylesheet on page 379

About Stylesheet Contents on page 382

Example of a Stylesheet
When you work with a stylesheet, three documents are involved:

XML source document

Result document, which can be HTML, XML, or text

XSL stylesheet, which is also an XML document

For example, suppose you have the following XML document:
<?xml version="1.0"?>
<bookstore>
<book>
<author>W. Shakespeare</author>
<title>Hamlet</title>
<published>1997</published>
<price>2.95</price>
</book>
<book>
<author>W. Shakespeare</author>
<title>Macbeth</title>
<published>1989</published>
<price>9.95</price>
</book>
<book>
<author>D. Alighieri</author>
<title>The Divine Comedy</title>
<published>1321</published>
<price>5.95</price>
</book>
</bookstore>

Stylus Studio User Guide

379

Working with XSLT

You can use a stylesheet to transform this XML document into an HTML document that
appears as follows in a Web browser:

Figure 227. Example of Transformed XML

The Web page in Figure 227 is defined by the following HTML document:
<html> <head> <title>Stylesheet Example</title> </head>
<body> <table align="center" cellpadding="5">
<tr><th>Title</th><th>Author</th><th>Price</th></tr>
<tr><td>The Divine Comedy</td><td>D. Alighieri</td>
<td align="right">5.95</td></tr>
<tr><td>Hamlet</td><td>W. Shakespeare</td>
<td align="right">2.95</td></tr>
<tr><td>Macbeth</td><td>W. Shakespeare</td>
<td align="right">9.95</td></tr>
</table> </body> </html>

The HTML document contains HTML markup that is not in the source document. In the
HTML document, the data from the source document is not in the same order as it is in
the XML source document. Also, this HTML document does not include some data that
is in the XML source document. Specifically, the HTML document does not include
information about the date of publication (the published elements).
To create this HTML file, the stylesheet contains two templates that provide instructions
for

Adding a table with a heading row

Wrapping the contents of the title, author, and price elements in table cells

380

Stylus Studio User Guide

Getting Started with XSLT

Following is a stylesheet that does this.

xsl:style
sheet is an

XSLT
instruction.
It must be
the root
element in a
stylesheet
in Stylus
Studio.
xsl:template

is an XSLT
instruction. It
contains literal
data to be
copied to the
result document
and XSLT
instructions to
be followed by
the XSLT
processor. The
processor
performs these
steps for the
source nodes
identified by the
match attribute
value. In this
template, the
match attribute
identifies the
root node of the
source
document.

<?xml version = "1.0">

<xsl:stylesheet xmlns:xsl=
"http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:output method="html"/>
<xsl:template match="/">
<html> <head>
<title>Stylesheet Example</title></head>
<body>
<table align="center" cellpadding="5">
<tr>
<th>Title</th>
<th>Author</th>
<th>Price</th></tr>
<xsl:apply-templates
select="/bookstore/book">
<xsl:sort select="author"/>
</xsl:apply-templates>
</table>
</body>
</html>
</xsl:template>
<xsl:template match="book">
<tr>
<td><xsl:value-of select="title"/></td>
<td><xsl:value-of select="author"/></td>
<td align="right">
<xsl:value-of select="price"/>
</td>
</tr>
</xsl:template>
</xsl:stylesheet>

This template matches

book elements in the
source document. That
is, the templates match
attribute identifies book
elements. In this
stylesheet, the XSLT
processor performs the
actions in this template
three times, once for
each book element in
the source document.

Stylus Studio User Guide

Namespace declaration for W3C

XSLT namespace.
xsl:output is an XSLT

instruction. In this stylesheet, it

specifies that the result
document will be in HTML

xsl:apply-templates is an

XSLT instruction. For each node

identified by this instructions
select attribute, the XSLT
processor goes to another
template in this stylesheet, and
performs the actions defined in
that template. When done, the
processor returns here, and
moves to the next line in this
template. In this template, the
select attribute identifies all
book elements in the source
document.

xsl:value-of is an

xsl:sort is an XSLT

XSLT instruction. The

XSLT processor
extracts the contents
of the source node
specified in the select
attribute and copies it
into the result
document.

instruction. The XSLT processor

processes the book nodes in
alphabetical order by author.

381

Working with XSLT

About Stylesheet Contents

Stylesheets are XML documents. They contain a combination of

XSLT elements and attributes. In the previous stylesheet, the XSLT elements are

xsl:stylesheet on page 499

xsl:output on page 490

xsl:template on page 499

xsl:apply-templates on page 467

xsl:sort on page 496

xsl:value-of on page 502

Each XSLT element is an instruction to the XSLT processor. For information about
all XSLT instructions, see XSLT Instructions Quick Reference on page 465.

Non-XSLT elements and attributes. In the previous stylesheet, these include the
HTML elements that create the table.
The root element of a stylesheet must declare a namespace that associates a prefix with
the URI for an XSLT processor. The URI in the namespace declaration in the previous
example identifies the W3C standard XSLT processor. This declaration, shown again
below, instructs the XSLT processor to recognize the XSLT elements and attributes by
their xsl prefix:
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

In this stylesheet, you must use the xsl prefix for all XSLT instructions.
Note The Stylus Studio XSLT processor requires the namespace URI to be
http://www.w3.org/1999/XSL/Transform. The prefix can be anything you want. Typically,

it is xsl.
When you write a stylesheet, you specify the actions you want the XSLT processor to
perform when it processes a particular source node. To do this, you define XSLT
templates, which are described in the next section.

What Is a Template?
A template defines what the XSLT processor should do when it processes a particular
node in the XML source document. The XSLT processor populates the result document
by instantiating a sequence of templates. Instantiation of a template means that the XSLT
processor

382

Stylus Studio User Guide

Getting Started with XSLT

Copies any literal data from the template to the result document
Executes the XSLT instructions in the template

The following topics further describe what a template is:

Contents of a Template on page 383

Determining Which Template to Instantiate on page 384

How the select and match Attributes Are Different on page 385

Contents of a Template
The stylesheet example in Example of a Stylesheet on page 379 defines the following
templates using the xsl:template instruction:
<xsl:template match="/">
<html><head><title>Stylesheet Example</title></head>
<body>
<table align="center" cellpadding="5">
<tr><th>Title</th><th>Author</th><th>Price</th></tr>
<xsl:apply-templates select="/bookstore/book">
<xsl:sort select="author">
</xsl:apply-templates>
</table></body></html>
</xsl:template>
<xsl:template match="book">
<tr><td><xsl:value-of select="title"/></td>
<td><xsl:value-of select="author"/></td>
<td align="right"><xsl:value-of select="price"/></td></tr>
</xsl:template>

In the xsl:template tag, the value of the match attribute is an XPath pattern. This pattern
matches (identifies) a node or a set of nodes in the source XML document. The value of
the match attribute is the template rule.
The template body defines actions you want the XSLT processor to perform each time it
instantiates this template. It contains

XSLT instructions you want the XSLT processor to follow; for example, xsl:applytemplates in the first template, and xsl:value-of in the second template.

Elements that specify literal output you want the XSLT processor to insert in the result
document. For example:
<table align="center" cellpadding="5">

Stylus Studio User Guide

383

Working with XSLT

Determining Which Template to Instantiate

When the XSLT processor applies a stylesheet to an XML document, it begins processing
with the root node of the XML source document. To process the root node, the XSLT
processor searches the stylesheet for a template rule that matches the root node. A
template rule matches the root node when the value of the templates match attribute is "/".
If you explicitly defined a template rule that matches the root node, the XSLT processor
finds it and instantiates its template. If the XSLT processor does not find an explicitly
defined template rule that matches the root node, the processor instantiates the default
template that matches the root node. Every stylesheet includes this default template.
Note Whether or not you explicitly define a template rule that matches the root node, the XSLT

processor always instantiates a template that matches the root node.

In the sample stylesheet on Example of a Stylesheet on page 379, the template rule in
the first template matches the root node:
<xsl:template match="/">

The XSLT processor instantiates this template to start generating the result document. It
copies the first few lines from the template to the result document. Then the XSLT
processor reaches the following XSLT instruction:
<xsl:apply-templates select="/bookstore/book"/>

When the XSLT processor reaches the select attribute, it creates a list of all source nodes
that match the specified pattern. In this example, the list contains book elements. The
processor then processes each node in the list in turn by instantiating its matching
template. First, the XSLT processor searches for a template that matches the first book
element. The template rule in the second template matches the book element:
<xsl:template match="book">

After instantiating this template for the first book element, the XSLT processor searches
for a template that matches the second book element. The XSLT processor instantiates the
book template again, and then repeats the process for the third book element. That is, the
XSLT processor searches for a matching template, and instantiates that template when it
is found.
After three instantiations of the book template, the XSLT processor returns to the first
template (the template that matches the root node) and continues with the line after the
xsl:apply-templates instruction.

384

Stylus Studio User Guide

Getting Started with XSLT

How the select and match Attributes Are Different

Consider the following instructions:
<xsl:apply-templates select=expression/>
<xsl:template match=pattern/>

The

xsl:apply-templates

expression.

The

instruction uses the select attribute to specify an XPath

instruction uses the match attribute to specify an XPath

xsl:template

pattern.

When the XSLT processor reaches an expression that is the value of a select attribute, it
evaluates the expression relative to the current node. The result of the evaluation is that
the XSLT processor selects a set of nodes to be processed.
When the XSLT processor reaches a pattern that is the value of a match attribute, it
evaluates the pattern alone. The result of the evaluation is that the XSLT processor
determines whether or not the pattern matches the node already selected for processing.
For example, suppose you have the following instruction:
<xsl:apply-templates select="/bookstore/book"/>

This instruction selects the book elements for processing. For each book element, the
XSLT processor searches for a template that matches the book element. The following
template matches the book element because the pattern identifies all elements that contain
author elements. Because book elements contain author elements, this template is a
match:
<xsl:template match="*[author]">
<td><xsl:value-of select="author"/></td>
</xsl:template>

This example shows that the expression that the XSLT processor uses to select nodes and
the pattern it uses to match nodes are independent of each other.

How the XSLT Processor Applies a Stylesheet

When the XSLT processor applies a stylesheet, it starts by automatically selecting the root
node for processing and then searching for a template that matches the root node. The
XSLT processor then iterates through the process of instantiating templates, selecting
nodes in the source document for processing, and matching patterns, until no more
templates need to be instantiated.

Stylus Studio User Guide

385

Working with XSLT

This section uses the sample stylesheet on Example of a Stylesheet on page 379 to
present this process in more detail in the following topics:

Instantiating the First Template on page 386

Selecting Source Nodes to Operate On on page 387

Controlling the Order of Operation on page 388

Omitting Source Data from the Result Document on page 389

When More Than One Template Is a Match on page 390

When No Templates Match on page 390

Instantiating the First Template

To apply a stylesheet, the XSLT processor searches for a template that matches the source
document root. The XSLT processor then instantiates the matching template and begins
to process it line by line.
The specific processing depends on the contents of the template that matches the root
node. The parts of the template include

XSLT instructions

Literal result elements

Literal result text

It is important to understand that the contents of the XML source document do not dictate
the order of XSLT processing. The XSLT processor performs only those actions that you
specify, and operates on only the source nodes that you select. For example:
<xsl:template match="/">
<html><head><title>Stylesheet Example</title></head>
<body>
<table align="center" cellpadding="5">
<tr><th>Title</th><th>Author</th><th>Price</th></tr>
<xsl:apply-templates select="/bookstore/book"/>
</table></body></html>
</xsl:template>

This template matches the root node. Consequently, the XSLT processor begins
processing by instantiating this template. This means it processes each part of the
template in the order in which it appears.
In the preceding example, the XSLT processor first copies the first four lines in the
template body directly into the result document. Then it executes the xsl:applytemplates instruction. When execution of that instruction is complete, the XSLT
386

Stylus Studio User Guide

Getting Started with XSLT

processor continues processing this template with the last line in the template body. After
that, processing of this template is complete, and processing of the stylesheet is also
complete.

Selecting Source Nodes to Operate On

Aside from the root node, the XSLT processor operates on only those nodes in the source
document that are selected as the result of executing an XSLT instruction. In a stylesheet,
there are two XSLT instructions that select nodes in the source document for processing:
<xsl:apply-templates select = "expression"/>
<xsl:for-each select ="expression">
template_body
</xsl:for-each>

The value of the select attribute is an XPath expression. To evaluate this expression, the
XSLT processor uses the current source node as the initial context node. This is the node
for which the instruction that contains the select attribute is being executed. For example,
if this instruction is in the template that matches the root node, the root node is the current
source node.
or xsl:for-each instruction, the XSLT processor uses the
select expression you specify plus the current source node to select a set of nodes. By
default, the new list of source nodes is processed in document order. However, you can
use the xsl:sort instruction to specify that the selected nodes are to be processed in a
different order. See xsl:sort on page 496.
In an

xsl:apply-templates

When the XSLT processor reaches an xsl:apply-templates instruction, the XSLT

processor processes each node in the list of selected nodes by searching for its matching
template and, if a matching template is found, instantiating it. In other words, the XSLT
processor instantiates a template for each node if a matching template is found. The
matching template might not be the same template for all selected nodes. If the XSLT
processor does not find a matching template, it continues to the next selected node.
In an xsl:for-each instruction, the XSLT processor instantiates the embedded template
body once for each node in the list of selected nodes.

Stylus Studio User Guide

387

Working with XSLT

Controlling the Order of Operation

Typically, the template that matches the root node includes an xsl:apply-templates
instruction. When the XSLT processor executes the xsl:apply-templates instruction, it
performs the following steps:
1.

The processor evaluates the expression specified for the xsl:apply-templates select
attribute to create a list of the source nodes identified by the expression.

For each node in the list, the XSLT processor instantiates the best matching template.
(Template properties such as priority and mode allow multiple templates to match the
same node.)

The processor returns to the template that contains the xsl:apply-templates

instruction and continues processing that template at the next line.

It is important to note that in step 2, the matching template might itself contain one or
more xsl:apply-templates instructions. As part of the instantiation of the matching
template, the XSLT processor searches for a template that matches the nodes identified by
the new xsl:apply-templates instruction. In this way, the XSLT processor can descend
many levels to complete processing of the first selected node in the initial xsl:applytemplates instruction. The xsl:apply-templates instruction allows you to access any
elements in the source document in any order.
Example
The sample template on Instantiating the First Template on page 386 contains the
following xsl:apply-templates instruction:
<xsl:apply-templates select="/bookstore/book"/>

The select attribute specifies "/bookstore/book" as the expression. This selects the set of
book elements in the source document as the nodes you want to process. For each selected

node, the XSLT processor performs the following steps:

388

The XSLT processor searches the stylesheet for a template that matches "book".

Stylus Studio User Guide

Getting Started with XSLT

When the XSLT processor finds the template that matches the book element, it
instantiates it. The following template matches the book elements selected by the
xsl:apply-templates instruction:
<xsl:template match="book">
<tr><td><xsl:value-of select="title"/></td>
<td><xsl:value-of select="author"/></td>
<td align="right"><xsl:value-of select="price"/></td></tr>
</xsl:template>

The XSLT processor creates an HTML table row and executes the xsl:value-of
instructions. These instructions insert the values for the matching books title,
author, and price elements into the table.

The XSLT processor repeats this process for each book node. In other words, it instantiates
this template three times, once for each book element in the source document.
It is important to note that the XSLT processor does not search for a matching template
once and then instantiate that matching template for each selected element. Rather, the
XSLT processor performs the search for a matching template for each node selected for
processing. For each node selected for processing, the XSLT processor

Searches for and chooses the best matching template

Instantiates the chosen template

Another way to control the order of operation is to specify the xsl:if, xsl:choose, and
xsl:when instructions. See XSLT Instructions Quick Reference on page 465.

Omitting Source Data from the Result Document

The XSLT processor operates on only those nodes that you specify. If a node in your XML
source document is never referenced in a stylesheet, the XSLT processor never does
anything with it.
For example, the sample source XML document on Example of a Stylesheet on
page 379 includes more than the title, author, and price for each book. It also includes the
year of publication:
<book>
<author>W. Shakespeare</author>
<title>Hamlet</title>
<published>1997</published>
<price>2.95</price>
</book>

Stylus Studio User Guide

389

Working with XSLT

However, the template that matches the book element does not specify any processing for
the published element. Consequently, the published elements do not appear in the result
document.

When More Than One Template Is a Match

Sometimes, more than one template matches the node selected by an xsl:applytemplates instruction. In this situation, the XSLT processor chooses the best match.
Which match is the best match depends on the templates priority, mode, and order in the
stylesheet. Priority, mode, and order are template properties that you can set.

Priority Priority is a numeric value, such as 1, 10, or 99. The higher the numeric
value, the higher the templates priority. Priority is a useful way to distinguish the
relative importance of two templates.

Mode A templates mode allows you to define the context in which a given template
should be performed. To use the mode attribute, you specify it (mode=xyz, for
example) in both the xsl:template and xsl:apply-template instructions. Once you
have specified a mode, the processor applies a template only if the modes match.

Order If the XSLT processor cannot distinguish the best match among two or more
templates, it uses the last matching template that appears in the stylesheet. Thus, you
can enforce priority indirectly by the order in which you define the templates within
a stylesheet.
For information on specifying these attributes, see xsl:template on page 499 and
xsl:apply-templates on page 467.

When No Templates Match

When the XSLT processor cannot find a template that matches a selected node, it uses
built-in templates. Every stylesheet includes built-in templates whether or not you
explicitly define them.
The XSLT processor supports these built-in templates:

The following template matches the root node and element nodes and selects all
attributes and child nodes for further processing:
<xsl:template match="*|/">
<xsl:apply-templates />
</xsl:template>

390

Stylus Studio User Guide

Getting Started with XSLT

The following template matches text and attribute nodes. This template copies the
value of the text or attribute node to the result document:
<xsl:template match="@*|text()">
<xsl:value-of select="." />
</xsl:template>

Although Stylus Studio does not explicitly insert these templates in stylesheets you create
with Stylus Studio, they are always present. That is, as specified by the W3C XSLT
Recommendation, these templates are always defined, whether or not they are explicitly
defined. See Using Stylus Studio Default Templates on page 437.

Controlling the Contents of the Result Document

This section highlights some of the XSLT instructions you can specify in a stylesheet to
control the contents of the result document. This section discusses the following topics:

Specifying Result Formatting on page 391

Creating New Nodes in the Result Document on page 392

Controlling White Space in the Result on page 392

Specifying Result Formatting

In a stylesheet, you can specify that the XSLT processor should format the result as XML,
HTML, or text. Table 58 describes the XSLT processor output for each alternative:
Table 58. Output Based on Result Format
Result Format

XSLT Processor Output

XML

Well-formed XML.

HTML

Recognized HTML tags and attributes that are formatted

according to the HTML 4.0 specification. Most browsers
should be able to correctly interpret the result. It is your
responsibility to ensure that the result is well-formed
HTML. For example, <BR> elements should not have child
nodes.

Text

All text nodes in the result in document order.

See xsl:output on page 490 for information about specifying formatting in a stylesheet.

Stylus Studio User Guide

391

Working with XSLT

Creating New Nodes in the Result Document

The simplest way to create new nodes in a result document is to specify them as literal
result elements or literal result text in a stylesheet template. For example:
<xsl:template match="/">
<html><head></head><body><table>
<tr><th>Title</th><th>Author</th><th>Price</th></tr>
...
</table></body></html>
</xsl-template>

This template creates many nodes in the result document that were not in the source
document.
You can also use XSLT instructions to create new nodes. Typically, you use XSLT
instructions when you need to compute the name or value of the node. You can find
information about using the following instructions in the XSLT Instructions Quick
Reference on page 465:

xsl:element on page 478

xsl:attribute on page 468

xsl:comment on page 475

xsl:processing-instruction on page 495

xsl:text on page 501

You can use the xsl:value-of on page 502 instruction to provide the contents for a new
node. You can also create a new node by copying the current node from the source
document to the result document. The current node is the node for which the XSLT
processor instantiates a template. See xsl:copy on page 475.

Controlling White Space in the Result

For readability, XML documents (both source documents and stylesheets) often include
extra white space. White space in XML documents includes spaces, tabs, and new-line
characters. Because this white space is for readability, it receives special treatment.
Text nodes that contain only white space are

Preserved as normal text nodes in a source document

Ignored in a stylesheet, unless the parent node is xsl:text

392

Stylus Studio User Guide

Getting Started with XSLT

Significant white space

Stylus Studio recommends that you specify xsl:text in a stylesheet whenever you want
to create significant white space in the result. Significant white space is white space that
you want to appear in the result in exactly the way that you specify.
To obtain white space for readability during output formatting, specify the xsl:output
instruction with the indent attribute. Default values are yes for HTML, and no for XML.
With Stylus Studio, you can select the Indent check box on the Params/Other tab to
display indented output instead of one long string. Note that the value of the indent
attribute, if specified in the stylesheet, has precedence over the Indent option.

Specifying XSLT Patterns and Expressions

In a stylesheets xsl:template, xsl:apply-templates, xsl:for-each, and xsl:value-of
instructions, you specify patterns or expressions as the values for the match or select
attributes. These patterns are XPath expressions. You specify patterns or expressions to

Define which nodes a template rule matches.

Select lists of source nodes to process.

Extract source node contents to generate result nodes.

Depending on the context, an XSLT pattern or expression can mean one of the following:

Does this template match the current node?

Given the current node, select all matching source nodes.

Given the current node, select the first matching source node.

Given the current node, do any source nodes match?

Patterns or expressions can match or select any type of node. The XSLT processor can
match a pattern to a node based on the existence of the node, the name of the node, or the
value of the node. You can combine patterns and expressions with Boolean operators. For
detailed information about patterns and expressions, see Writing XPath Expressions on
page 691.

Examples of Patterns and Expressions

Following are examples of patterns and expressions you can specify in stylesheet
instructions:
xsl:template match = "book/price"

Stylus Studio User Guide

393

Working with XSLT

Matches any price element that is a child of a book element.

xsl:template match = "book//award"

Matches any award element that is a descendant of a book element.

xsl:template match = "book [price]"

Matches any book element that has a child that is a price element.
xsl:template match = "book [@price]"

Matches any book element that has a price attribute.

xsl:template match = "book [price=14]"

Matches any book element that has a child that is a price element whose value is 14.
xsl:template match = "book [@price=14]"

Matches any book element that has a price attribute whose value is 14.
xsl:apply-templates select = "book"

Selects all book elements that are children of the current element.
xsl:apply-templates select = "book/price"

Selects all price elements that are children of book elements that are children of the
current element.
xsl:apply-templates select = "//book"

Selects all book elements in the source document.

xsl:apply-templates select = ".//book"

Selects all book elements that are descendants of the current element.

394

Stylus Studio User Guide

Getting Started with XSLT

Frequently Asked Questions About XSLT

How can I use quoted strings inside an attribute value?

If you need to include a quoted string inside an attribute value (in a select expression, for
example), you can use the single quotation mark character (') in the value of the attribute.
For example:
select = "book[title = 'Trenton Today']".

How do I choose when to use xsl:for-each and when to use xsl:apply-templates?

The way xsl:for-each and xsl:apply-templates select nodes for processing is identical.
The way these instructions find the templates to process the selected nodes is different.
With xsl:for-each, the template to use is fixed. It is the template that is contained in the
body of the xsl:for-each element. With xsl:apply-templates, the XSLT processor finds
the template to be used for each selected node by matching that node against the template
rules in the stylesheet.
Finding a template by matching requires more time than using the contained template.
However, matching allows for more flexibility. Also, matching lets you avoid repeating
templates that might be used in more than one place in a stylesheet.
Named templates are another option for invoking a template from more than one place in
a stylesheet, when you know which template you want. It is a common mistake to use (and
bear the overhead of) matching when it is not needed. But it allows you to do powerful
things. Matching can take into account the following:

Pattern matching on the node

Precedence of templates based on stylesheet importance

Template priority

Template ordering
Most complex document-formatting stylesheets use

xsl:apply-templates

extensively.

TIp Use the XSLT Profiler to help you understand where the processor is spending most of

its time. See Profiling XSLT Stylesheets on page 558.

XSLT Profiling is available only in Stylus Studio XML Enterprise Suite.

Stylus Studio User Guide

395

Working with XSLT

How can I insert JavaScript in my result document?

If you want your result document to contain JavaScript commands, you must properly
escape the JavaScript code. Use the following format in your XSLT template:
<script>
<xsl:comment>
<![CDATA[ <your JavaScript here> ]]>
</xsl:comment>
</script>

However, this method does not work when your JavaScript section contains a block of
XSLT code. In this case, enclosing the JavaScript in a CDATA tag causes the XSLT
processor to ignore not just the JavaScript but also the markup code within that tag.
In this situation, enclose the entity reference within an <xsl:text> tag with disableto "yes". For example:

output-escaping set

if(length <xsl:text disable-output-escaping="yes">></xsl:text> 1)

You can use this wherever an entity reference needs to be handled specifically, as opposed
to being handled as part of an entire JavaScript section.
My browser does not understand the tag <br/>. How can I output just <br>?

Although your XSLT stylesheet must contain valid XML (meaning all tags must be either
empty or have a closing element), you can instruct the XSLT processor to generate output
compliant with HTML. See Deleting Templates on page 440.
Alternative: To ensure that your stylesheet always generates correct HTML, specify the
490.

xsl:output instruction with the method attribute set to html. See xsl:output on page

Sources for Additional XSLT Information

For additional information about XSL and XSLT, visit the following Web sites:

http://www.w3.org/Style/XSL/

W3C Extensible Stylesheet Language specification

http://www.w3.org/TR/xslt

W3C XSLT Recommendation

396

Stylus Studio User Guide

Getting Started with XSLT

Benefits of Using Stylus Studio

Now that you have an understanding of what a stylesheet can do, you can appreciate the
benefits of using Stylus Studio to create them. Stylus Studio is the first integrated
environment for creating, managing, and maintaining an XSL-enabled Web presence. By
combining the tools needed to create XSLT stylesheets in a visual editing environment,
Stylus Studio speeds initial development and eases maintenance. Key elements of Stylus
Studios XSLT features include

Structural Data View on page 397

Sophisticated Editing Environment on page 398

XSLT and Java Debugging Features on page 399

Integrated XML Parser/XSLT Processor on page 401

Structural Data View

Stylus Studio graphically displays the structure, or schema, of the XML data to which you
want to apply a stylesheet.

Figure 228. Tree View Lets You Easily Edit XSLT

Stylus Studio User Guide

397

Working with XSLT

Using this tree view, you can apply formatting to your XML double-clicking a node in
the tree automatically adds an xsl:template match= instruction for that node, for example.
Similarly, when you drag a node into the XSLT source, Stylus Studio displays a pop-up
menu that allows you to easily insert an XSLT instruction.

Figure 229. Stylus Studio Displays XSLT Instructions for Quick Editing

Finally, you can also use the tree to move quickly among different XSLT templates
clicking a node in the tree places the cursor at the corresponding template in the XSLT
source.

Sophisticated Editing Environment

The Stylus Studio editor allows you to edit both the XML source document and the XSLT
stylesheet. There is no need to memorize complicated syntax. As you type, Stylus Studio

398

Stylus Studio User Guide

Getting Started with XSLT

Sense:X technology automatically suggests XSLT or HTML tag and attribute names, and
ensures that all XML is well formed.

Figure 230. Sense:X Speeds Coding, Reduces Errors

Sense:X also adapts to your document by suggesting more frequently used tags first. Valid
XSLT and HTML tag names are color coded to improve readability.

XSLT and Java Debugging Features

Complex stylesheets require robust debugging features. With Stylus Studio, you can do
the following:

Set breakpoints in your stylesheet.

Monitor the value of XSLT variables.

Trace the sequence of XSLT instructions that created HTML output. With a click
anywhere in the rendered HTML page, Stylus Studio Visual Backmapping

Stylus Studio User Guide

399

Working with XSLT

technology displays the XSLT instructions responsible for creating that portion of
HTML output.

Figure 231. Click to HTML Output to Backmap to XSLT Source

Also, you can click in the stylesheet and the backmapping feature highlights the text
generated by that template.
Use the XSLT Profiling report to review performance metrics to help troubleshoot and
tune your XSLT stylesheets.

XSLT Profiling is available only in Stylus Studio XML Professional Suite.

400

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

Integrated XML Parser/XSLT Processor

Stylus Studio integrates an XML parser with an XSLT processor. This allows Stylus
Studio to instantly show the output of your stylesheet. Each time you apply a stylesheet
to an XML document, Stylus Studio detects and flags any errors in your stylesheet or
XML data.
Stylus Studios default XSLT processor is compliant with the W3C XSLT
Recommendation. You can also use custom processors of your own.

Tutorial: Understanding How Templates Work

When Stylus Studio creates a new stylesheet, it contains one template, which matches the
root node. However, this template is empty. If you apply the new stylesheet as is, the result
document has no contents. To generate a result document with contents, you need to add
instructions to the template that matches the root node.
All stylesheets have two default templates that do not appear in the stylesheet itself. It is
important for you to understand how the default templates work so that you can

Add instructions to the template that matches the root node.

Define additional templates to operate on the elements in your document.

Specify HTML markup in templates.

When you can do this, you can write a stylesheet that generates a dynamic Web page that
displays your information.
This tutorial provides step-by-step instructions for defining a stylesheet that generates a
dynamic Web page from an XML document. The tutorial shows how the default templates
work, and it provides instructions for defining templates that instantiate the default
templates. It also provides instructions for adding HTML markup to the stylesheet. The
result is a dynamic Web page that displays the particular information you choose.
Each of the following topics contains instructions for defining the stylesheet. You should
perform the steps in each topic before you move on to the next topic. After the first topic,
some steps depend on actions you performed in a previous topic. This section organizes
the process as follows:

Creating a New Sample Stylesheet on page 402

Understanding How the Default Templates Work on page 405

Editing the Template That Matches the Root Node on page 410

Creating a Template That Matches the book Element on page 411

Stylus Studio User Guide

401

Working with XSLT

Creating a Template That Matches the author Element on page 412

For a simpler tutorial that shows you how to define a stylesheet that generates a dynamic
Web page from a static HTML document, see Working with Stylesheets Getting
Started on page 33.
This tutorial duplicates some of the information in subsequent sections. For complete
information, see the following topics:

Working with Stylesheets on page 413

Working with Templates on page 435

Creating a New Sample Stylesheet

To create a stylesheet to use in this tutorial, follow these instructions:
1.

From the Stylus Studio menu bar, select File > New > XSLT Stylesheet.
Stylus Studio displays a new untitled stylesheet and the Scenario Properties dialog
box, and selects the text in the Scenario Name field.

Figure 232. Scenarios Let You Easily Test Different XSLT/XML Pairs

402

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

In the Scenario Properties dialog box, in the Scenario Name field, type
DynamicBookstoreScenario.

Click Browse
to the right of the Source XML URL: field.
Stylus Studio displays the Open dialog box.

Navigate to the Stylus Studio examples\query directory.

Double-click bookstore.xml. This is the XML document that the new stylesheet will
operate on.

In the Scenario Properties dialog box, click OK.

This creates a scenario with the name DynamicBookstoreScenario. This scenario
associates the bookstore.xml document with the new stylesheet. If you want to apply
the new stylesheet to other XML documents, you must create a new scenario or
change the name of the XML document in this scenario.
Stylus Studio displays the new stylesheet in the XSLT editor. A tree representation of
the bookstore.xml document appears to the right.

Figure 233. The XSLT Editor Shows XSLT Source on Left, Tree on Right

Stylus Studio User Guide

403

Working with XSLT

The default stylesheet that Stylus Studio creates contains one template, which
matches the root node.

404

In the XSLT editor tool bar, click Preview Result

.
Stylus Studio displays the Save As dialog box so you can save the XSLT you are
composing.

In the URL: field, type myStylesheet.xsl and click Save.

Stylus Studio applies the new stylesheet to bookstore.xml and displays the result in
the Preview window. The result, displayed in the Preview window, has no contents
because the template that matches the root node is empty.

In the XSLT editor pane, click in the empty line that follows <xsl:template
match="/"> .

10.

Type <x, which displays the Sense:X completion list.

11.

In the completion list, scroll down and click xsl:apply-templates.

12.

Type />.

13.

In the XSLT editor tool bar, click Preview Result

Stylus Studio displays the Save As dialog box.

14.

Enter a name for the file and click Save.

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

This time, the Preview window contains all text in bookstore.xml and none of the
markup. This is because the xsl:apply-templates instruction instantiates the default
templates.

Figure 234. Default Templates Contain No Formatting Instructions

To create a Web page, you need to add HTML markup that displays the information the
way you want. To make it easier to do that, you need to understand how the text is already
being copied to the result document.

Understanding How the Default Templates Work

This topic is part of a sequence that starts with Creating a New Sample Stylesheet on
page 402.

Stylus Studio User Guide

405

Working with XSLT

After you complete the steps in the previous section, you can see the bookstore.xsl
stylesheet in the XSLT editor pane. It has the following contents:
<?xml version='1.0' ?>
<xsl:stylesheet version="1.0"xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
<xsl:apply-templates/>
</xsl:template>
</xsl:stylesheet>

The stylesheet explicitly contains one template, which matches the root node. When the
XSLT processor applies a stylesheet, the first thing it does is search for a template that
matches the root node. If there is no template that explicitly matches the root node, the
XSLT processor uses a built-in template.
There are two built-in templates, also called default templates. Every XSLT stylesheet
contains these templates whether or not they are explicitly specified. This is part of the
W3C XSLT Recommendation.
This section discusses the following topics:

Instantiating the Template That Matches the Root Node on page 406

Instantiating the Root/Element Default Template on page 407

Instantiating the Text/Attribute Default Template on page 408

Illustration of Template Instantiations on page 409

Instantiating the Template That Matches the Root Node

The XSLT processor instantiates the template that matches the root node. The template
that matches the root node contains only the xsl:apply-templates instruction. In this
template, the xsl:apply-templates instruction does not specify a select attribute.
Consequently, the XSLT processor operates on the children of the node for which the root
template was instantiated. In the bookstore.xml document, the root node has three
children:

XML declaration

Comment

406

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

bookstore document

element

Figure 235. Source XML Document from DynamicBookstoreScenario

Unless you specify otherwise, the XSLT processor operates on the children in document
order. The first child is a processing instruction (the XML declaration). The XSLT
processor ignores processing instructions.
The second child is the comment node, and the XSLT processor also ignores comment
nodes.
The third child is the bookstore document element. The XSLT processor searches for a
template that matches bookstore. Because there is no template that explicitly matches the
bookstore element, the XSLT processor instantiates a built-in template that is not
explicitly in the stylesheet.

Instantiating the Root/Element Default Template

One default template matches *|/. This means it matches every element in the source
document, and it also matches the root node. This is the root/element default template.
The root/element default template contains only the xsl:apply-templates instruction.
Like the template that matches the root node, the xsl:apply-templates instruction in the
root/element default template does not specify a select attribute. That is, it does not
identify the set of nodes for which templates should be applied. Consequently, the XSLT
processor operates on the children of the node for which the root/element template was
instantiated.
In this case, the root/element default template was instantiated for the bookstore element.
The children of the bookstore element include four book elements, a magazine element,
and a book element associated with the my namespace.

Stylus Studio User Guide

407

Working with XSLT

The XSLT processor operates on these children in document order. First, it searches for a
template that matches book. Because there is no template that explicitly matches the book
element, the XSLT processor instantiates the root/element default template for the first
book element.
Again, by default, the xsl:apply-templates instruction in the root/element default
template operates on the children of the current node in document order. That is, it
operates on the children of the first book element.
In the first book element, the first child is the title element. The XSLT processor searches
for a template that matches the title element. Because there is no template that explicitly
matches the title element, the XSLT processor instantiates the root/element default
template again.
At this point, the XSLT processor has initiated instantiation of the root template once, and
the root/element default template several times:
Instantiate root template for root node.
Instantiate root/element template for bookstore element.
Instantiate root/element template for first book element.
Instantiate root/element template for title in first book element.

It is important to understand that these instantiations are not yet complete. Each
subsequent instantiation of the root/element default template is inside the previous
instantiations.

Instantiating the Text/Attribute Default Template

When the XSLT processor instantiates the root/element default template for the title
element, the xsl:apply-templates instruction operates on the children of the title
element. The title element has one child, which is a text node. The XSLT processor
searches for a template that matches this text node. The second default template in the
stylesheet matches this text node. This template matches text()|@*, meaning that it
matches every text node and every attribute in the source document. This is the
text/attribute template.
The XSLT processor instantiates the text/attribute default template for the title elements
text node. This template contains only the xsl:value-of instruction. Its select attribute
identifies the current node, which is the node for which the template was instantiated. This
template copies the text contained in the current text node to the result document.
Now the result document contains the following text:
Seven Years in Trenton

408

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

The XSLT processor is finished with the title element, and it next processes the author
element in the first book element. There is no template that explicitly matches author, so
the XSLT processor instantiates the root/element default template. The first child of the
author element is the first-name element, and again, there is no template that explicitly
matches the first-name element. The XSLT processor instantiates the root/element
default template for the first-name element. The only child of the first-name element is
a text node. The XSLT processor instantiates the text/attribute default template for this
text node, and this template copies the text to the result document. Now the result
document contains the following text:
Seven Years in Trenton Joe

The XSLT processor is finished with the first-name element, and it next processes the
which is the second child of the author element.

last-name element,

Illustration of Template Instantiations

As you can see from the description in the previous section, the XSLT processor iterates
through the process of searching for a matching template, instantiating one of the default
templates, and operating on the children of the node for which the template was
instantiated. The following figure shows the template instantiations through the second

Stylus Studio User Guide

409

Working with XSLT

book element. In the figure, each bracket encloses the instantiations that together compose

a complete instantiation for a particular element.

Instantiate root template for root node.
Instantiate root/element template for bookstore element.
Instantiate root/element template for first book element.
Instantiate root/element template for title element.
Instantiate text/attribute template for text node.
Instantiate root/element template for author element.
Instantiate root/element template for first-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for last-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for award element.
Instantiate text/attribute template for text node.
Instantiate root/element template for price element.
Instantiate text/attribute template for text node.
Instantiate root/element template for second book element.
Instantiate root/element template for title element.
Instantiate text/attribute template for text node.
Instantiate root/element template for author element.
Instantiate root/element template for first-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for last-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for publication element.
Instantiate text/attribute template for text node.
Instantiate root/element template for first-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for last-name element.
Instantiate text/attribute template for text node.
Instantiate root/element template for price element.
Instantiate text/attribute template for text node.
Instantiate root/element template for price element.
Instantiate text/attribute template for text node.
Instantiate root/element template for magazine element.

And so on.

Editing the Template That Matches the Root Node

This topic is part of a sequence that starts with Creating a New Sample Stylesheet on
page 402.
Begin writing your stylesheet by adding instructions to the template that explicitly
matches the root node in your source document:
In the XSLT editor, edit the contents of the root template so that it contains only the
following contents. As you type, Stylus Studio displays a pop-up menu that lists possible
410

Stylus Studio User Guide

Tutorial: Understanding How Templates Work

instructions. You can scroll the list and double-click the entry you want, or you can
continue typing. If you want, you can copy the text from here and paste it into the
Templates view.
<html>
<body>
<h3><center>Books in Stock</center></h3>
<table align="center" cellpadding="5">
<tr>
<th>Title</th>
<th>Author</th>
<th>Price</th>
</tr>
<xsl:apply-templates select="bookstore/book"/>
</table>
</body>
</html>

Ensure that you do one of the following:

Remove the xsl:apply-templates instruction that you inserted earlier.

Edit the xsl:apply-templates instruction to include the select attribute as shown

above, and place it in the correct location.

Creating a Template That Matches the book Element

This topic is part of a sequence that starts with Creating a New Sample Stylesheet on
page 402.
The template that matches the root node includes an xsl:apply-templates instruction that
selects book nodes for processing.
To define the template that matches the book element:
1.

In the XSLT editor source document tree pane, expand the bookstore element.

Double-click the book element.

Stylus Studio creates a template that matches the book element. The new template is
near the end of the stylesheet and has the form <xsl:template match=book>. In the
tree pane, the yellow check next to the book element indicates that there is a template
that matches this element.

Stylus Studio User Guide

411

Working with XSLT

In the XSLT editor pane, add the following instructions to the new templates body:
<tr>
<td><xsl:apply-templates select="title"/></td>
<td><xsl:apply-templates select="author"/></td>
<td align="right">
<xsl:apply-templates select="price"/>
</td>
</tr>

Press F5 to see the results. The result document looks like that shown in Figure 236:

Figure 236. Result of Applying XSLT

In the book template, the xsl:apply-templates instructions cause the XSLT processor to
instantiate the default templates. For the title and price elements, this works correctly
because those elements include only a text node. But for the author element, the use of
the default templates copies too much information to the result table. You need to
explicitly define a template for the author element.

Creating a Template That Matches the author Element

This topic is part of a sequence that starts with Creating a New Sample Stylesheet on
page 402.
To define a template that matches the author element:

412

In the XSLT editor source document tree pane, expand the book element.

Double-click the author element.

Stylus Studio creates a template that matches the author element, and places it near
the end of the stylesheet.

Stylus Studio User Guide

Working with Stylesheets

In the XSLT editor pane view, edit the template body so that it contains only the
following contents.
<xsl:value-of select="first-name"/>
 
<xsl:value-of select="last-name"/>

If you do not include the nonbreaking space entity, the first name and the last name
have no space between them. Press F5 to see the results of this change, as shown in
Figure 237.

Figure 237. Result of XSLT with an Author Template

Save the stylesheet by clicking Save

Close the stylesheet by clicking File > Close on the Stylus Studio menu bar.

Working with Stylesheets

This section provides instructions for performing the various tasks involving stylesheets.
See also Working with Templates on page 435. This section covers the following topics:

About the XSLT Editor on page 414

Creating Stylesheets on page 415

Creating a Stylesheet from HTML on page 415

Specifying Stylesheet Parameters and Options on page 416

Applying Stylesheets on page 419

Applying a Stylesheet to Multiple Documents on page 425

About Stylesheet Contents on page 426

Updating Stylesheets on page 427

Stylus Studio User Guide

413

Working with XSLT

Saving Stylesheets on page 429

Also, Stylus Studio provides a number of tools that help you debug stylesheets. See
Debugging Stylesheets on page 551.

About the XSLT Editor

The XSLT editor, which displays a stylesheet when you open it, has four tabs at the
bottom.

Figure 238. XSLT Editor

The XSLT Source, Mapper, and Params/Other tabs are always available.
Editing XSLT as XML
If you want, you can edit an XSLT file as an XML file. To do this, open the stylesheet in
the XML editor instead of in the XSLT editor. In the Open dialog box, click the down
arrow in the Open button. Click XML Editor in the drop-down menu. A document can be
open in the XML editor and in the XSLT editor at the same time.
414

Stylus Studio User Guide

Working with Stylesheets

Creating Stylesheets
To create a stylesheet:
1.

From the Stylus Studio menu bar, select File > New > XSLT Stylesheet.
Stylus Studio displays the Scenario Properties dialog box.

In the Scenario Name: field, type a name for the association between the new
stylesheet and a particular XML source document. You might want to use the
convention of specifying the name you want your result document to have. The result
document is the document that will contain the result of applying the stylesheet you
are about to create.

In the Source XML URL: field, type the name of an XML document or click Browse
to navigate to a document. Select a document you want to apply the new stylesheet
to. You are not limited to applying the new stylesheet to only this XML document.
You can create other scenarios later and specify other XML documents to which you
want to apply the same stylesheet.

Click OK. Stylus Studio displays an untitled stylesheet window. The default text in the
new stylesheet appears in the left pane. The schema for the XML source document
you specified in the scenario properties appears in the right pane.

To give the stylesheet a name, select File > Save.

Navigate to where you want to save the stylesheet.

In the URL: field, type the new stylesheets name.

Click Save.

Creating a Stylesheet from HTML

You can create an XSLT stylesheet from an HTML file using the HTML to XSLT
document wizard.
Tip Stylus Studio also has a document wizard that converts HTML to XML. See Creating

XML from HTML on page 140.

To run the HTML to XSLT document wizard:
1.

Select File > Document Wizards from the menu.

The Document Wizards dialog box appears.

Click the XSLT Editor tab.

Stylus Studio User Guide

415

Working with XSLT

Double-click HTML to XSLT (or select the HTML to XSLT icon and click OK).
The HTML to XML dialog box appears.

Figure 239. HTML to XML Dialog Box

Enter the name of the HTML file you want to convert to XSLT in the Choose HTML
File to Convert to XSLT field.

Click OK.
Stylus Studio opens the converted HTML file as an untitled XSLT file in the XSLT
Editor.

Specifying Stylesheet Parameters and Options

You can specify values for stylesheet parameters in the Parameter Values tab of the
Scenario Properties dialog box.
To specify XSLT stylesheet parameters:

416

Open the stylesheet for which you want to specify parameter values.

In the XSLT editor tool bar, click Browse

.
Stylus Studio displays the Scenario Properties dialog box.

Stylus Studio User Guide

Working with Stylesheets

Click the Parameter Values tab.

Stylus Studio displays a list of the parameters defined in your stylesheet, if any, with
any default values.

Figure 240. XSLT Scenario Parameter Values Tab

Click the third field in the line that displays the parameter for which you want to
define a value Parameter value to be used when processing.

Type the value of the parameter.

If you want Stylus Studio to pass this paramater as an XPath expression instead of as
a string, click the fourth field, which is a check box.
The default is that Stylus Studio passes a parameter as a string.

Click OK.

Stylus Studio User Guide

417

Working with XSLT

To view stylesheet parameters and and specify stylesheet options, click the
Params/Other tab in the stylesheet window.

In the XSLT Encoding field, you can specify the encoding you want Stylus Studio to use
when you save the stylesheet.

Figure 241. XSLT Parameters Tab

To display a list of the encodings supported by Stylus Studio, click the down arrow in the
XSLT Encoding field.
In the Output method field, you can specify the type of data you want the stylesheet to
generate. Choices include

xml

html Stylus Studio generates HTML that is compliant with HTML 4.0. This is
equivalent to inserting <xsl:output method="html"/> in a stylesheet.

text

unspecified

If you do not specify an xsl:output instruction in your stylesheet, Stylus Studio uses the
default output method you specify here. If you do specify an xsl:output instruction in
your stylesheet, that instruction overrides the default you specify here.
When the result of applying a stylesheet is XHTML, specify xml as the Output method.
Note, however, that Stylus Studio displays rendered HTML in the Preview in Browser
window.
In the Params/Other tab, in the Output Encoding field, you can specify the encoding you
want Stylus Studio to use in the document that is the result of applying the stylesheet.
When you apply a stylesheet, Stylus Studio uses this encoding for the output document.

418

Stylus Studio User Guide

Working with Stylesheets

You can change the encoding by changing the setting in the Params/Other tab or in the
initial processing instruction in the stylesheet. When you change the setting in one of
these places, Stylus Studio automatically changes it in the other. They are always the
same. In the Output Encoding field, click the down arrow to display a list of the supported
encodings.
If you want Stylus Studio to insert indents in the result document, select Indent.

Applying Stylesheets
In order to apply a stylesheet to an XML document, the stylesheet must be associated with
a scenario. See

Creating a Scenario on page 422

Cloning Scenarios on page 424

Saving Scenario Meta-Information on page 424

If your stylesheet is associated with a scenario, there are two ways to apply it:

Click Preview Result

, which appears in the top tool bar of the XSLT Source tab
of your stylesheet. This ignores any breakpoints that are set.

Press F5. Stylus Studio suspends processing if it reaches a breakpoint.

The following topics provide more information about how to apply stylesheets:

About Applying Stylesheets on page 419

Results of Applying a Stylesheet on page 420

Applying Stylesheets to Large Data Sets on page 422

Tip Stylus Studio provides a number of tools that help you debug stylesheets. See

Debugging Stylesheets on page 551.

About Applying Stylesheets

When you apply a stylesheet, Stylus Studio checks both the XML source document and
the XSLT stylesheet for correct syntax. If it detects any errors, it displays a message that
indicates what the error is. This message appears at the bottom of the XSLT editor. Stylus
Studio also displays and flags the line that contains the error.
Often, a stylesheet refers to other files, such as CSS stylesheets or images. For Stylus
Studio to display the complete result file in the Preview window, you must enter the path
for resolving any links. Do this in the Base URL for HTML links resolution field of the
Scenario Properties dialog box.
Stylus Studio User Guide

419

Working with XSLT

Ensure that the correct output type is set. To do this, click the Params/Other tab at the
bottom of the stylesheet and check the value of the Output Method field.
If your stylesheet is associated with more than one scenario, select the scenario you want
to use and then apply the stylesheet. To do this, click the down arrow to the right of the
scenario name field to display a list of scenarios. Click the scenario you want to use, and
. After you apply a stylesheet in a particular scenario, the
then click Preview Result
Preview window displays a tab for that scenario. To reapply the stylesheet in that scenario,
click Preview Result
in the left tool bar.
You might want to apply the same stylesheet to two different XML documents and
compare the results. To do this, create a scenario for each XML source document. Apply
the stylesheet in the context of each scenario. Stylus Studio displays a tab for each
scenario at the bottom of the Preview window. Click the tab to display the result document
for that scenario.
Stylus Studio does not support scenarios that consecutively apply multiple stylesheets to
one source document.

Results of Applying a Stylesheet

Stylus Studio applies the stylesheet to the XML source document specified in the current
scenario and refreshes the Preview window with the latest result document. If the Preview
window is not visible, select View > Preview from the Stylus Studio menu bar.
To toggle between viewing the text of the result and viewing what the result would look
or Preview Text
.
like in a browser, click Preview in Browser
Tip You can select and copy text in the Preview Text view.

420

Stylus Studio User Guide

Working with Stylesheets

If you click in the result document, Stylus Studio displays the Backmap Stack window,
which lists the XSLT instructions that generated the text you clicked.

Backmap Window

Figure 242. XSLT Backmap Window

Stylus Studio also flags the line in the stylesheet that contains the first instruction in the
Backmap Stack window.

If the result document is XML, in the Preview window, you can click Preview in Tree
to display the result of XSLT processing as an XML tree.

Figure 243. XML Tree View

The tree view provides

Scalability you can more easily view large result sets

Backmapping click on a result tree node and Stylus Studio displays the stylesheet
line that generated that node
To save the result of applying a stylesheet, click Save Preview
window. Stylus Studio displays the Save As dialog box.

Stylus Studio User Guide

in the Preview

421

Working with XSLT

The result document reflects any changes you made to either the XML source document
or the XSLT stylesheet. You do not need to explicitly save either the XML or XSLT file
to have changes to those documents appear in the result document. However, when you
apply a stylesheet, Stylus Studio does not also save the stylesheet. To save a stylesheet,
click Save
.

Applying Stylesheets to Large Data Sets

When you open a stylesheet or assign a source XML document to a scenario, Stylus
Studio loads the entire XML source document in memory. Stylus Studio requires the
source XML document in order to display

A preview of the result of applying the stylesheet

The source tree for the document the stylesheet will be applied to
If the source XML document is particularly large, loading it can take several minutes.
Each time you leave and return to Stylus Studio, Stylus Studio checks whether any open
documents have been modified. If the documents reside on remote servers, this can take
some time. If you want, you can turn off the check for modified documents.
To turn off the check for modified documents:
1.

In the Stylus Studio menu bar, select Tools > Options.

Stylus Studio displays the Options dialog box.

Click Application Settings.

Click the check box for Automatically check for externally modified files.

Creating a Scenario
A scenario allows you to preview the results of applying a stylesheet. Each scenario is for
a particular group of settings. These settings include the name of an XML source
document, the values of any parameters in the stylesheet, and the values of any encoding
settings. A scenario can include any setting that you can specify when you apply the
stylesheet.
A scenario can be associated with only one stylesheet and only one XML source
document. However, you can associate any number of scenarios with a stylesheet, and you
can associate any number of scenarios with an XML source document.
Tip If you start to create a scenario and then change your mind, click Delete and then OK.

422

Stylus Studio User Guide

Working with Stylesheets

To create a scenario:
1.

In the XSLT editor tool bar, click Browse

.
Stylus Studio displays the Scenario Properties dialog box.

In the Scenario Name: field, type the name of the new scenario.

In the Source XML URL: field, type the name of the XML file you want to apply the
stylesheet to, or click Browse
to navigate to an XML file and select it.

In the Output URL field, optionally type or select the name of the result document you
want the stylesheet to generate. If you specify the name of a file that does not exist,
Stylus Studio creates it when you apply the stylesheet.

In the Base URL For HTML Links Resolution field, optionally type the path for
resolving any links. For example, your stylesheet might have links to CSS stylesheets
or images.

If you want Stylus Studio to Store paths relative to XSLT document path, ensure that
this option is checked.

If you want to Preview result in an external application, ensure that this option is
checked. When this option is checked, Stylus Studio displays the result in the default
application for the output method specified for the scenario. For example, if the
output method for the scenario is HTML and if Internet Explorer is the default
application for displaying HTML files, Stylus Studio displays the resulting HTML in
Internet Explorer, as well as in the XSLT Preview window.

If you want to specify values for stylesheet parameters, click the Parameter Values
tab. Double-click the Value field for the parameter you want to specify a value for.

If you want to use an XSLT processor other than the Stylus Studio processor, click the
Processor tab and type the required information. See Using Third-Party XSLT
Processors on page 440.

10.

If you want to specify any post-processing, click the Post-process tab. See Postprocessing Result Documents on page 446.

11.

To define another scenario, click Add and enter the information for that scenario. You
can also copy scenarios. See Cloning Scenarios on page 424.

12.

Click OK.

Stylus Studio User Guide

423

Working with XSLT

Cloning Scenarios
When you clone a scenario, Stylus Studio creates a copy of the scenario except for the
scenario name. This allows you to make changes to one scenario and then run both to
compare the results.
Tip If you start to clone a scenario and then change your mind, click Delete and then OK.

To clone a scenario:
1.

Display the stylesheet in the scenario you want to clone.

In the XSLT editor tool bar, click Browse

dialog box.

In the Scenario Properties dialog box, in the Existing preview scenarios field, click
the name of the scenario you want to clone.

Click Clone.

In the Scenario name field, type the name of the new scenario.

Change any other scenario properties you want to change. See Creating a Scenario
on page 422.

Click OK.

to display the Scenario Properties

Saving Scenario Meta-Information

Stylus Studio can store scenario meta-information in two places:

In the stylesheet associated with the scenario, unless you turned off the Save scenario
meta-information in the stylesheet option.

In the project that the stylesheet belongs to, if the stylesheet belongs to a project.
When you save a stylesheet, Stylus Studio saves the scenario meta-information in the
stylesheet, but not in the project. When you select File > Save All or when you save the
project, Stylus Studio saves the scenario meta-information in the stylesheet and in the
project. To ensure that scenario meta-information in the project and in the stylesheet is
consistent

The project must be open when you save the stylesheet.

Ensure that you save the project after you modify scenario information. (If you close
a project without saving it, Stylus Studio prompts you to save it.)

424

Stylus Studio User Guide

Working with Stylesheets

Suppose you modify a scenario and save and close the associated stylesheet. If the
stylesheet belongs to the open project, when you save the project, Stylus Studio saves the
closed stylesheets scenario meta-information in the project.

Applying a Stylesheet to Multiple Documents

You can apply the same stylesheet to multiple documents

In separate operations

In a single operation

Applying the Same Stylesheet in Separate Operations

Scenarios make it easy to view results and apply the same stylesheet to multiple XML
documents. A stylesheet can have any number of scenarios. Each scenario is associated
with only one stylesheet. In addition to the stylesheet, a scenario is associated with a
source XML file. The same XML file can be associated with any number of scenarios.
You create an initial scenario when you create a stylesheet. You can create additional
scenarios at any time. See Creating a Scenario on page 422.
To view results for a particular scenario:
1.

Click the down arrow in the scenario field at the top of the stylesheet window.

Click the scenario you want to view.

Click Preview Result

, which is directly to the left of the scenario field. This
applies the stylesheet to the XML document specified in the selected scenario.

Each time you generate a different scenario, Stylus Studio displays a tab at the bottom of
the Preview window for that scenario. Click the tab for the scenario you want to view. This
allows you to compare results.

Applying a Stylesheet to Multiple Documents in One Operation

To apply a stylesheet to multiple documents in one operation, call the document() function
in the XPath expression of a template. This function allows you to access another XML
document and select nodes from that document for processing as source nodes. See
Accessing Other Documents During Query Execution on page 769.
For example, you can specify the following:
<xsl:apply-templates select="document('bookstore.xml')/bookstore"

Stylus Studio User Guide

425

Working with XSLT

This selects the bookstore root element of the bookstore.xml document.

Stylus Studio looks for the document in the directory that contains the stylesheet.
The document() function has a lot of overhead. You should call it once and assign the
result to a variable with the xsl:variable instruction.

About Stylesheet Contents

Stylesheets are XML documents. They can contain XSLT instructions and non-XSLT
elements and nodes. Stylus Studio automatically inserts some XSLT instructions. You can
add additional XSLT instructions, HTML markup, and any other XML data you want.
This section describes

Contents Provided by Stylus Studio on page 426

Contents You Can Add on page 426

Contents Provided by Stylus Studio

When Stylus Studio creates a stylesheet, it has the following contents:
<?xml version="1.0"?>
<xsl:stylesheet version='1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
</xsl:template>
</xsl:stylesheet>

The xsl:stylesheet instruction is required in every stylesheet that you use with Stylus
Studio.
Stylus Studio defines one template, which matches the root node. Of course, the two builtin templates are also defined, although they are not explicitly in the stylesheet. For
information about these templates, see Using Stylus Studio Default Templates on
page 437.
When Stylus Studio creates a stylesheet from an HTML file, the template that matches the
root node contains all HTML markup that was in the imported file.

Contents You Can Add

You can add to the stylesheet any XSLT instruction that Stylus Studio supports. See
XSLT Instructions Quick Reference on page 465. You can also add HTML markup and
any other XML-formatted data you require.

426

Stylus Studio User Guide

Working with Stylesheets

To obtain the XPath expression that retrieves a particular node in the source document you
want to apply the stylesheet to, see Obtaining the XPath for a Node on page 160.

Updating Stylesheets
You can edit a stylesheet in the XSLT Source tab in Full Source
mode or Template
mode. To display a particular template in either mode, click the down arrow in the
upper right corner of the editing pane. This displays a drop-down list of template match
patterns. Click the template you want to view.
The XSLT editor keeps track of your XSLT context. That is, it keeps track of template
match patterns, and any xsl:for-each element that affects the context on which the
stylesheet is working. The editor uses Stylus Studios Sense:X technology to help you
create XPath expressions whenever they are needed.
After you associate the stylesheet with a scenario, you can display the source tree for the
XML source document specified in the scenario. Click Source Tree
in the XSLT
editor tool bar. This tree provides a description of the structure of the XML source
document specified in the scenario. This tree does not include elements and attributes that
are not instantiated in the particular source document. However, the tree provides a
structure that you can examine to help you understand stylesheet behavior in a given
scenario.
The following sections describe the Stylus Studio editing tools:

Dragging and Dropping from Schema Tree into XSLT Editor on page 427

Using Sense:X Automatic Tag Completion on page 428

Using Sense:X to Ensure Well-Formed XML on page 428

Using Standard Editing Tools on page 429

Dragging and Dropping from Schema Tree into XSLT Editor

From the source tree of the XSLT editor, you can drag an element or attribute into the
XSLT Source pane. If you drop the node in the stylesheet so that it is in a template, Stylus
Studio displays the following choices:

xsl:for-each

xsl:value-of

xsl:apply-templates

node_name

Stylus Studio User Guide

427

Working with XSLT

Click the instruction you want to create. The XSLT context into which you drop the node
determines the value of the select attribute in the instruction you choose. The select
attribute always selects the node you dragged into the stylesheet. If you choose node_name,
Stylus Studio simply inserts the name of the element or attribute you dragged in. This is
convenient for pasting long element or attribute names.
If you drop the node in the stylesheet so that it is not in a template, Stylus Studio creates
a new template. In the new template, the value of the match attribute is the name of the
node you dragged into the stylesheet.
You can also create a new template by double-clicking a node in the source tree. The
difference between double-clicking a node and dragging a node is that when you doubleclick a node to create a template, Stylus Studio always inserts the template at the end of
the stylesheet. When you drag a node to create a template, you determine the location of
the template.

Using Sense:X Automatic Tag Completion

The Stylus Studio Sense:X automatic tag completion system helps you edit XSLT,
HTML, and FO (formatting objects) instructions. Stylus Studio has built-in knowledge of
all XSLT, HTML, and FO tags, as well as their attributes.
Tip For information about FO, see http://www.w3.org/TR/2001/REC-xsl20011015/slice6.html#fo-section.

As you type in the XSLT edit window, Stylus Studio prompts you with a list of tag or
attribute names that match the first few letters you typed. To complete the tag name you
are typing, scroll the list if necessary, and double-click the tag you want.
You can customize the Sense:X system. Edit languages.xml in the Stylus Studio
bin\Plugins\Configuration Files directory to customize the tag list.
To set options that specify Sense:X behavior, go to the Editor General page of the Options
dialog box.

Using Sense:X to Ensure Well-Formed XML

Sense:X also helps you write well-formed XML. There is an option in the Editor General
page that is set by default. This is Auto-Close Open Tag When Typing '</'. This means that
as soon as you type </, Stylus Studio immediately inserts the only tag that can possibly
be closed at that point.

428

Stylus Studio User Guide

Working with Stylesheets

If you prefer, you can turn off this option. Then, when you start to type a closing tag, the
Sense:X list displays the only valid closing tag. Double-click it to insert it.

Using Standard Editing Tools

Standard editing tools are available to you for updating stylesheets. From the Edit menu
or tool bar you can cut, copy, paste, replace, undo, redo, select all, and find. The usual
keyboard shortcuts work as well:

Ctrl+X cuts highlighted text.

Ctrl+C copies highlighted text.

Ctrl+V pastes text.

Ctrl+Z undoes the most recent action that has not already been undone.

Ctrl+Y redoes the most recently undone action that has not already been redone.
For additional shortcuts, see Keyboard Accelerators on page 1304.

Saving Stylesheets
When you save a stylesheet, Stylus Studio uses the encoding that is specified in the
Params/Other tab of the XSLT editor. You can change the encoding by changing the
setting in the Params/Other tab or in the initial processing instruction in the stylesheet.
When you change one of these, Stylus Studio automatically changes the other. They are
always the same.
To save an XSLT stylesheet, do one of the following:

Click Save
.

Press Ctrl+S.

Select File > Save from the Stylus Studio menu bar.
To save your stylesheet to another file, select File > Save As.
To save multiple files, select File > Save All. This saves all files that are open in Stylus
Studio.
Tip You can set an option that instructs Stylus Studio to save your modified documents every
few minutes. Go to the Applications Settings page on the Options dialog box.

Stylus Studio User Guide

429

Working with XSLT

Using Updated Stylesheets

Within a scenario, Stylus Studio automatically uses any updated files when you apply a
stylesheet. It does not matter whether you have explicitly saved a file in the scenario. If a
stylesheet includes or imports other stylesheets, Stylus Studio automatically uses any
updated versions of included or imported stylesheets even if you have not explicitly saved
them.
However, there is one situation in which Stylus Studio does not automatically use updated
stylesheets. Suppose that multiple stylesheets are open in Stylus Studio. Each stylesheet
generates a Web page, and the Web pages have links to each other. The stylesheets do not
include or import each other. You make changes in more than one of these stylesheets and
you do not explicitly save any changes. You apply one of the stylesheets, and in the
Preview window you click a link to another Web page generated by one of the other
stylesheets you updated. In this situation, Stylus Studio does not apply the updated
stylesheet. You must explicitly save the stylesheet to be able to use the updated version.

Specifying Extension Functions in Stylesheets

You can write XSLT extension functions in Java and invoke them in XPath expressions in
stylesheets. This section provides instructions for implementing and invoking extension
functions from your stylesheet.
This section covers the following topics:

Using an Extension Function in Stylus Studio on page 431

Basic Data Types on page 432

Declaring an XSLT Extension Function on page 432

Working with XPath Data Types on page 433

Declaring an Extension Function Namespace on page 433

Invoking Extension Functions on page 434

Finding Classes and Finding Java on page 434

Debugging Stylesheets That Contain Extension Functions on page 434

430

Stylus Studio User Guide

Specifying Extension Functions in Stylesheets

Using an Extension Function in Stylus Studio

The process of using an extension function in Stylus Studio involves three main steps:
1.

First, you need to write a Java class that can be used from within a stylesheet. In this
example, the SystemDate() method returns the system date and time as a string:
import java.util.Date;
public class SystemUtils
{
public Object SystemDate()
{
Date d = new Date();
String s = d.toString();
return s;
}
}

Second, compile your class and register it on the Stylus Studio host by copying the
.class file to a location defined in the hosts CLASSPATH environment variable.

Finally, specify information in the stylesheet so that Stylus Studo can use your class.
You do this with a namespace reference in the xsl:stylesheet tag. For example,
define a namespace as xmlns:Ext where Ext is the prefix to use when calling the class
methods. (Ext is not a predefined keyword; it can be replaced by any other legal
string.) The namespace reference then takes the class name as a value. In this
example, the whole reference looks like the following:
xmlns:Ext="SystemUtils"

The class is now available from within the stylesheet and can be used in a template such
as the following:
<xsl:template match="NODE">
<p><xsl:value-of select="Ext:SystemDate()"/></p>
</xsl:template>

Stylus Studio User Guide

431

Working with XSLT

The XSLT stylesheet might look like the following:

<?xml version="1.0" encoding="ISO-10646-UCS-2"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform"
xmlns:Ext="SystemUtils">
<xsl:param name="param">test</xsl:param>
<xsl:template match="*|/">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="text()|@*">
<xsl:value-of select="."/>
</xsl:template>
<xsl:template match="NODE">
<p><xsl:value-of select="Ext:SystemDate()"/></p>
</xsl:template>
</xsl:stylesheet>

Basic Data Types

XPath and XSLT data types map to Java data types according to Table 59:
Table 59. XPath/XSLT and Java Type Mappings
XPath/XSLT Type

Java Type

Node Set

org.w3c.dom.NodeList

String

java.lang.String

Boolean

boolean or Boolean

Number

double or Double

Result Tree Fragment

org.w3c.dom.DocumentFragment

Declaring an XSLT Extension Function

Extension functions must have one of the following signatures:
public
public
public
public

432

Object
Object
static
static

FxnName()
FxnName(Type1 var1, Type2 var2,...)
Object FxnName()
Object FxnName(Type1 var1, Type2 var2,...)

Stylus Studio User Guide

Specifying Extension Functions in Stylesheets

A class that contains an extension function might look like the following:
import org.w3c.dom.*;
import java.lang.Double;
public class NumberUtils
{
public Object Average(NodeList nl)
{
double nSum = 0;
for (int i = nl.getLength() - 1; i >= 0; i--)
{
nSum +=
Double.valueOf(nl.item(i).
getNodeValue()).doubleValue();
}
return new Double(nSum / nl.getLength());
}
}

Working with XPath Data Types

The XPath types Boolean and Number can map either to the corresponding Java primitive
types or to the corresponding Java object types. If the XPath processor is looking for a
function that accepts XPath parameters 3.2 and true, it looks first for a function that
accepts (double, boolean) and then (Double, Boolean). Functions that accept some
combination of primitive types and object types are not recognized by the XPath
processor.
The XPath processor determines the actual return type of a function at run time. For
example, the XPath processor treats the return type of the function in the preceding
section as an XPath Number because the object it returns is an instance of the Java class
Double. You must declare all functions to return type Object, regardless of the actual type
of the return value.

Declaring an Extension Function Namespace

In conformance with the XSLT specification, extension functions are accessed through a
unique namespace. The namespace declaration can be in any of the following locations:

xsl:stylesheet tag

Element that contains the XPath expression that invokes the extension function

Ancestor of the element that contains the XPath expression that invokes the extension
function
The XPath processor treats the namespace URI as a fully qualified class name. If the class
name is preceded by class:, all calls are to static methods only. Otherwise, an instance of

Stylus Studio User Guide

433

Working with XSLT

the class is created on first use and released when stylesheet processing is complete.
Performance is better when you use a static method because creation and deletion of an
instance of the class is not required.
You can separate package names with either a dot (.) or a forward slash (/). An sample
namespace declaration might look like the following:
<xsl:stylesheet xmlns:Ext="NumberUtils">

The XPath processor resolves namespace prefixes in names of extension functions

relative to the namespace declarations in the stylesheet.

Invoking Extension Functions

You use XSLT extension functions just like built-in XPath functions. For example:
<xsl:value-of select="Ext:Average(portfolio/stocks/last)"/>

Finding Classes and Finding Java

The XPath processor looks for extension classes by using the CLASSPATH environment
variable. Ensure that your CLASSPATH references any directories or .jar files that contain
extension classes.
The XPath processor tries to load the Sun Java Runtime Environment (JRE) 1.4.x or later.
If the XPath processor cannot find a suitable JRE, invoking Java extension functions
causes an error during stylesheet processing.
In Stylus Studio, classes are reloaded each time you refresh the preview output, so
changes in a class are reflected in subsequent preview output.

Debugging Stylesheets That Contain Extension Functions

Support for extensions debugging is available only in Stylus Studio XML
Enterprise Suite and Stylus Studio XML Professional Suite.
You can use Stylus Studio backmapping and debugging features on stylesheets tht invoke
extension functions. You must process the stylesheet with one of the following
processors:

Built-in Stylus Studio XSLT processor

Saxon processor

434

Stylus Studio User Guide

Working with Templates

The Saxon processor does not allow you to step into JavaScript extensions. You can step
into Java extensions, however.

Working with Templates

Templates define the actions that you want the XSLT processor to perform. When you
apply a stylesheet to an XML source document, the XSLT processor populates the result
document by instantiating a sequence of templates. This is illustrated in Understanding
How the Default Templates Work on page 405.
A template can contain elements that specify literal result nodes. It can also contain
elements that are XSLT instructions for creating result nodes. In a template, the template
rule is the pattern that the XSLT processor matches against (compares with) selected
nodes in the source document.
This section covers the following topics:

Viewing Templates on page 435

Using Stylus Studio Default Templates on page 437

Creating Templates on page 439

Applying Templates on page 440

Updating Templates on page 440

Deleting Templates on page 440

Viewing Templates
Stylus Studio provides different ways to display lists of templates, specific templates, as
well as ways to see if a given template generates any output.

Stylus Studio User Guide

435

Working with XSLT

Viewing a List of Templates

To view a list of the templates in the stylesheet:
1.

Click the down arrow in the upper right corner of the XSLT editing pane.

Figure 244. Choosing Available XSLT Templates

Stylus Studio displays a drop-down list of the first five match patterns in the
stylesheet. To limit the displayed list, type in the combo box to the left of the down
arrow. Stylus Studio displays only those patterns that match the character(s) you
typed.
A particular template might or might not have a match pattern (template rule). Named
templates do not necessarily specify match patterns.

Note

Click the match pattern for the template you want to view. It does not matter whether
the XSLT editor is in Full Source
mode or Template
mode.

Viewing a Specific Template

To view a particular template, double-click its matching element in the XML tree view,
which is displayed to the right of the editing pane. If the element has more than one
template, Stylus Studio displays a list of the templates. Click the one you want.

436

Stylus Studio User Guide

Working with Templates

Checking if a Template Generates Output

To see if a particular template generates any output:
1.

Select a template in the XSLT templates pane.

Click Refresh

In the XSLT Preview window, with output text displayed, scroll as necessary to find
text highlighted in gray. Text with a gray background was generated by the selected
template.

to apply the stylesheet.

Using Stylus Studio Default Templates

Every stylesheet in Stylus Studio can use two built-in templates, even though they are not
explicitly defined. This section covers the following topics to help you use these
templates:

Contents of a New Stylesheet Created by Stylus Studio on page 437

About the Root/Element Built-In Template on page 438

About the Text/Attribute Built-In Template on page 438

Contents of a New Stylesheet Created by Stylus Studio

When Stylus Studio creates a new stylesheet, the stylesheet includes the following builtin templates:
<xsl:template match="*|/">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="text()|@*">
<xsl:value-of select="."/>
</xsl:template>

Every XSLT stylesheet contains these templates whether or not they are explicitly
specified. In other words, the XSLT processor behaves as if they are there even when they
are not explicitly specified in the stylesheet.

Stylus Studio User Guide

437

Working with XSLT

About the Root/Element Built-In Template

The first built-in template matches *|/. This means it matches every element in the source
document and it matches the root node. This is the root/element built-in template.
This root/element built-in template contains only the xsl:apply-templates instruction.
The xsl:apply-templates instruction does not specify a select attribute, which means
that the XSLT processor operates on the children of the node for which the root/element
template was instantiated.
What does the XSLT processor do when it operates on these children nodes? It searches
for a template that matches each node. If there is no such template and if the node is an
element, the XSLT processor instantiates the root/element built-in template. If the node is
a text node and there is no matching template, the XSLT processor instantiates the
text/attribute built-in template.
If the node for which the root/element built-in template is instantiated has no children, the
XSLT processor does no processing for this node and proceeds to the next selected node.
The XSLT processor instantiates the root/element built-in template when it cannot find a
template that explicitly matches the root node or an element in the source document. As
you know, the XSLT processor always begins processing by instantiating the template that
matches the root node. If you do not define such a template in your stylesheet, the XSLT
processor begins processing by instantiating the root/element built-in template.

About the Text/Attribute Built-In Template

The second specified built-in template matches text()|@*. This means it matches the text
contents of every text node and every attribute in the source document. This is the
text/attribute template.
This template contains only the xsl:value-of instruction. Its select attribute specifies an
expression for selecting an XML node. The "." expression identifies the current node,
which is the node the template was instantiated for.
This template copies the text contained in the current text node or attribute to the result
document.

438

Stylus Studio User Guide

Working with Templates

Creating Templates
To do anything beyond copying the text from your XML document to the result document,
you must create templates. You can create new templates several ways:

In the source tree of the XSLT editor, double-click the element or attribute for which
you want to create a template. Stylus Studio creates an empty template that matches
the node you clicked. This template appears at the end of the stylesheet.

Click New Template

. Stylus Studio creates an empty template whose match
pattern is NewTemplate. Replace NewTemplate with a match pattern that has meaning
for your stylesheet. The new template appears at the end of the stylesheet.

Drag an element or node from the source tree in the XSLT editor to the Full Source
pane and drop it in a location that is not in a template. Stylus Studio creates a new
template that matches the node you dragged in.
Try creating a new template that matches an XML element in your document:
1.

Double-click an element in the tree view of your XML document.

Enter the following instruction in the new template:

In another template, ensure that there is an xsl:apply-templates instruction that

selects the new templates element for processing.

Press F5 to apply the stylesheet and refresh the current scenario in the Preview
window.

Notice that the text contents of the element for which you created the template are now
displayed in bold the XSL instruction is formatted with <b> and </b>. Also, the XSLT
processor does not process this element's children (if there are any) because the new
template you created does not specify <xsl:apply-templates/>.
By creating additional templates to style portions of your XML document, you can
completely control how the document appears.

Saving a Template
To save a template, save the stylesheet. Click Save
select File > Save from the Stylus Studio menu bar.

Stylus Studio User Guide

in the Stylus Studio tool bar, or

439

Working with XSLT

Applying Templates
The xsl:apply-templates instruction allows you to control the order of operations when
you apply a stylesheet. For an in-depth description of how the XSLT processor applies
templates, see How the XSLT Processor Applies a Stylesheet on page 385.
To apply a template so that you can see the output in the Preview window, you must apply
the entire stylesheet. Press F5 to apply the stylesheet and refresh the output. If Stylus
Studio detects any errors in the stylesheet or in the XML source document, it displays a
message that indicates the cause and location of the error.
In the Preview window, in the Text view, the text with a gray background was generated
by the template the cursor is in. If the editor is in Template mode, the text with the gray
background was generated by the currently visible template.

Updating Templates
When you want to update a template, you can use all features that are available when you
are updating a stylesheet. See Updating Stylesheets on page 427.

Deleting Templates
To delete a template:
1.

Select the text for the template you want to delete.

Right-click in the editor to display the shortcut menu.

Click Cut.

Using Third-Party XSLT Processors

Stylus Studio includes several third-party XSLT processors, including Saxon 9.x,
MSXML, and .NET. Note, however, that only the following XSLT processors support
Stylus Studio stylesheet debugging and back-mapping functionality:

Saxon 9.x

Microsoft .NET (XslTransform and XslCompiledTransform)

440

Stylus Studio User Guide

Using Third-Party XSLT Processors

Back-mapping and debugging are not supported by other XSLT processors, including
others bundled with Stylus Studio (MSXML 4.0, for example).
Note You can use only the built-in XML parser with Stylus Studio.

This section covers the following topics:

How to Use a Third-Party Processor on page 441

Setting Default Options for Processors on page 443

How to Use a Third-Party Processor

You specify XSLT processors for stylesheets individually. You can, of course, create
multiple scenarios for the same stylesheet, with each one using a different processor.
When you use a third-party XSLT processor, output from the processor appears in the
Preview window.
To use a third-party XSLT processor:
1.

Open the stylesheet.

In the XSLT Editor, in the scenario name field, click the down arrow to display the
scenarios associated with the stylesheet.

To use a third-party processor for an existing scenario, click the scenario name, and
then click
to display the Scenario Properties dialog box.
To create a new scenario, click Create Scenario. See Creating a Scenario on
page 422.

In the Scenario Properties dialog box that appears, click the Processor tab.

Select the XSLT processor you want to use from the Processor drop-down list.
Stylus Studio allow you to choose an MSXML option only if you have the MSXML
or MSXML .NET Framework (version 1.1 or 2.0) installed.

Note

Optionally, change the default settings for the processor you selected.

If you selected a standard XSLT processor, you are done. Click OK.
If you selected Use custom processor (%1 xml, %2 xslt, %3 output):
a.

In the Command line field, type the command line for invoking the processor you
want to run. You must specify the command line so that it is clear where to use
the three arguments. Following are two examples:

Stylus Studio User Guide

441

Working with XSLT

myparser %1 %2 %3
myparser -inputxslt %2 -inputxml %1 -out %3

In the Path field, specify any path that needs to be defined for the processor to
run. Typically, this is the location of the processor.

In the Classpath field, type any directories the external processor needs to access
that are not already specified in your CLASSPATH environment variable.

Click OK.

Using the Saxon Processor

Stylus Studio lets you execute XSLT transformations using either the Saxon-B (basic) or
Saxon-SA (schema-aware) processor. You specify which processor you want to use with
the Execution mode property in the Saxon XSLT Settings dialog box. Settings that have
command line equivalents in Saxon show the command in parentheses following the
property name. Some settings are available only if you are using Saxon-SA.
Stylus Studios Sense:X syntax coloring and auto-completion provides full support for
Saxon syntax, so long as the Saxon Logic XSLT processor is either associated with the
current XSLT scenario or has been set as the default XSLT processor.
If you want to use the Saxon processor:
1.

442

On the Processors tab, click Saxon.

The Settings button becomes active.

Stylus Studio User Guide

Using Third-Party XSLT Processors

Click the Settings button.

The Saxon XSLT Settings dialog box appears.

Figure 245. Saxon XSLT Settings Dialog Box

Complete the settings as desired. Press F1 to access the Stylus Studio online help, or
refer to the Saxon documentation for more information.

Click OK.

Passing Parameters
To pass parameters to the Microsoft .NET, Saxon, or MSXML processor, specify them in
the Parameters tab of the Scenario Properties dialog box. To pass parameters to a custom
external processor, you must specify them in the command line you enter.

Setting Default Options for Processors

If you want, you can set default values for XSLT processor options and designate a
processor other than the Saxon processor as the default processor used whenever you
create an XSLT scenario.
You can always override the default processor and individual processor settings at the
scenario level.
To set defaults for XSLT processors:
1.

From the Stylus Studio menu, select Tools > Options.

Stylus Studio User Guide

443

Working with XSLT

Stylus Studio displays the Options dialog box.

Select Module Settings > XSLT Editor > Processor Settings.

Figure 246. Options for XSLT Processors

444

Select the processor for which you want to specify default settings from the
Processor drop-down list.

If required, complete processor-specific settings. (Click the Settings button.)

If you want this processor to be used as the default processor for all XSLT scenarios,
click the Use as default processor check box.

Click OK.

Stylus Studio User Guide

Validating Result Documents

You can optionally validate the XML document that results from XSLT processing. You
can validate using the

Stylus Studio built-in validator (Xerces C++). If you use the Stylus Studio built-in
validator, you can optionally specify one or more XML Schemas against which you
want the result document to be validated.

Any of the customizable processors supported by Stylus Studio, such as the .NET
XML Parser and XSV.
All validation is done before any post-processing that you might have specified.
To validate XSLT scenario result documents:
1.

Open the stylesheet whose results you want to validate.

In the XSLT Editor (XSLT Source or Mapper tabs), in the scenario name field, click
the down arrow and click the name of the scenario for which you want to perform
validation.

Click Browse

Click the Validation tab.

to open the Scenario Properties dialog box.

Figure 247. Validation Tab for XSLT Scenarios

Click Validate stylesheet result.

Stylus Studio User Guide

445

Working with XSLT

If you are using Stylus Studios built-in validation engine, optionally, specify the
XML Schemas against which you want to validate the XML result document.
Otherwise, go to Step 7
a.

Click the Open file button ( ).

The Open dialog box appears.

Select the XML Schema you want to use for validation.

Click the Open button to add the XML Schema to the Validation tab.

Optionally, add other XML Schemas.

Go to Step 8.

Click the Use custom validator button, and select the validation engine you want to
use from the drop-down list box.

Click OK.

Post-processing Result Documents

You can use a scenarios post-processing settings to specify that you want Stylus Studio
to initiate processing on the result of applying a stylesheet. If you do, Stylus Studio
performs the post-processing before it displays the result in the Preview window.
For example, you can choose to run the Apache Software Organizations Formatting
Objects Processor (FOP) as a post-processor. You can run this on the result of stylesheets
that generate XML documents that contain FO. The Apache FOP included with Stylus
Studio converts FO XML into PDF and displays it in the Stylus Studio preview window.
See Generating Formatting Objects on page 447.
To specify post-processing:

446

Open the stylesheet whose result you want to process.

In the XSLT Editor (XSLT Source or Mapper tabs), in the scenario name field, click
the down arrow and click the name of the scenario in which you want to specify postprocessing.

Click Browse

Click the Post-process tab.

Click one of the following:

to open the Scenario Properties dialog box.

Stylus Studio User Guide

Generating Formatting Objects

Post Process With Apache FOP if you want Stylus Studio to initiate the Apache FOP.
You are done. Click OK.
Custom Post-Process if you want Stylus Studio to initiate a postprocess you define.
With this selection, you must also do the following:
a.

In the Command line field, type the command line for starting your
postprocessor. For example, mypostprocessor %1 %2. You can specify any
application or script that takes as input the result document generated by an XSLT
processor and generates a new file.

In the Generated File Extension field, type the extension on the file name of the
postprocessor output. For example, .pdf.

In the Additional Path field, optionally type any paths that need to be defined that
are not already defined in your PATH environment variable.

Click OK.

Generating Formatting Objects

You can use Stylus Studio to develop a stylesheet that generates XSL Formatting Objects
(FO). In the scenario in which you apply such a stylesheet, you can specify that Stylus
Studio should run a Formatting Objects Processor (FOP) on the stylesheets result
document. When you apply the stylesheet and preview the results, Stylus Studio displays
the formatted results.
Stylus Studio includes The Apache Software Organizations FOP, and it is configured to
always generate PDF. If you want to run a FOP to generate some other type of output, you
must specify some other FOP in the Custom post-process fields of the Post-process tab
of the Scenario Properties dialog box.
Stylus Studio includes two sample stylesheets that generate formatting objects. These
files are in the examples\XSLFormattingObjects directory of your Stylus Studio
installation directory.
This section covers the following topics:

Developing Stylesheets That Generate FO on page 448

Troubleshooting FOP Errors on page 448

Viewing the FO Sample Application on page 449

Deploying Stylesheets That Generate FO on page 451

Stylus Studio User Guide

447

Working with XSLT

Using Apache FOP to Generate NonPDF Output on page 452

Note FO is a W3C recommendation for an XML vocabulary that describes how to format text.

FO is one part of XSL. This section assumes that you are familiar with FO. For additional
information about FO, see http://www.w3.org/TR/2001/REC-xsl-20011015/.

Developing Stylesheets That Generate FO

To develop a stylesheet that generates FO:
1.

Define the scenario in which you want to apply the stylesheet that generates FO. See
Creating a Scenario on page 422.

In the Scenario Properties dialog box, in the Post-process tab, do one of the
following:

Select Postprocess with Apache FOP.

The Apache FOP included with Stylus Studio is configured to convert FO XML
into PDF. Stylus Studio then uses Acrobat Reader to display the PDF in the Stylus
Studio preview window.
Specify some other FOP in the Custom post-process fields. You must do this
when you want to generate output other than PDF. If you want to use the Apache
FOP included with Stylus Studio to generate a format other than PDF, you can do
that here.
See Post-processing Result Documents on page 446.

In the XSLT editor, define a stylesheet that generates FO. As soon as you type <fo:,
Stylus Studio displays a completion menu of FO that you can select from.

Apply the stylesheet to an XML document.

After Stylus Studio transforms the XML document to generate a result XML
document that contains formatting objects, Stylus Studio automatically runs the FOP
you specified on the result document. Stylus Studio then displays the postprocess
result in the XSLT Preview window.

Troubleshooting FOP Errors

If the transformation works well, but the FOP generates an error, obtain a copy of
RenderXs Unofficial DTD for XSL Formatting Objects. You can find this at
http://www.renderx.com. Although this DTD is not official (it is more limited than what
the W3C XSL recommendation defines), it is a helpful debugging tool.
448

Stylus Studio User Guide

Generating Formatting Objects

To validate the generated XML against this DTD:
1.

Copy the DTD to a location such as C:\fo.dtd.

Include a document type declaration, such as the following, in your generated

document:
<!DOCTYPE fo:root SYSTEM "/fo.dtd">

Turn off post-processing.

Apply the stylesheet.

Save the resulting XML document.

Open the saved XML document in Stylus Studio.

Click Validate Document

Viewing the FO Sample Application

To view the FO sample application included with Stylus Studio:
1.

In Stylus Studio, open the examples\XSLFormattingObjects\minimal-catalog.xsl file

in your Stylus Studio installation directory.
Alternative: If the Stylus Studio examples project is open, you can access this file from
the Project window. To open the examples project, open examples.prj in the Stylus
Studio examples directory.
The video scenario has already been defined. In the Post-process tab of the Scenario
Properties dialog box, Postprocess with Apache FOP is selected.
In this scenario, Stylus Studio selects elements to operate on from three different
documents. These documents are in the examples directory of the Stylus Studio
installation directory. They are also in the examples project. The documents are:

VideoCenter\videos.xml

simpleMappings\books.xml

simpleMappings\catalog.xml

Stylus Studio User Guide

449

Working with XSLT

Click Preview Result

. As you can see, the Output Window shows some postprocessing information messages.

Figure 248. Example of XSLT FO Processing

After a few seconds, the Preview window displays the PDF result in Acrobat Reader.
The result contains a few lines of text for each video and book found in the XML
source documents. The title, author or director, and the description is included for
each item. It is hard to see where information for one item ends and another begins.

450

Examine the stylesheet. It contains the minimum FO instructions required to generate

FO. There is no formatting to make the result document easier to read. You can use
this stylesheet as a skeleton for creating your own stylesheets that generate FO.

Now open the examples\XSLFormattingObjects\catalog.xsl stylesheet.

Stylus Studio User Guide

Generating Formatting Objects

Click Preview Result

Figure 249. Another Example of XSLT FO Processing

This time the PDF result in the Preview window is nicely formatted. The catalog.xsl
stylesheet adds some basic formatting, as well as images, to the minimal-catalog.xsl
stylesheet. Now it is easy to distinguish the title, author or director, and description
for each video or book.

Deploying Stylesheets That Generate FO

When your stylesheet is complete, the process for creating a final document, such as a
PDF document, from an XML document is as follows:
1.

Apply a stylesheet to an XML document. This results in an XML document that

contains XSL FO.

Run a FOP, such as Apaches FOP, and use the generated XML as input.

Example
You can accomplish both steps with a single invocation of FOP on the command line. For
example:
java -cp "C:\Program Files\StylusStudio\bin\Plugins\Fop\fop.jar;"
org.apache.fop.apps.Fop -xml ..\VideoCenter\videos.xml -xsl
catalog.xsl -pdf multimediacatalog.pdf

Stylus Studio User Guide

451

Working with XSLT

Replace C:\Program
Studio is installed.

Files\StylusStudio with

the name of the directory in which Stylus

Using Apache FOP to Generate NonPDF Output

The Apache FOP included with Stylus Studio is configured to output PDF.
To use this FOP to generate some other type of output:
1.

Open the stylesheet whose results you want to postprocess with the Apache FOP.

Create or open a scenario in which to do the post-processing. See Creating a

Scenario on page 422. Stylus Studio displays the Scenario Properties dialog box.

In the Scenario Properties dialog box, click the Post-process tab.

Select Custom post-process.

In the Command line field, enter something like the following:

java -cp "C:\Program Files\StylusStudio\bin\Plugins\Fop\fop.jar"
org.apache.fop.apps.Fop -fo %1 -svg %2

Modify this sample command line according to where Stylus Studio is installed and
what kind of output you want the FOP to generate. The last option, -svg in the
example, can be any of the following:
Table 60. FOP Output Options

452

Setting

Output

-mif

MIF file

-pcl

PCL file

-txt

Text file

-svg

SVG slides file

-at

XML (representation of an area tree)

-pdf

PDF file

In the Generated file extension field, specify the extension that indicates the type of
output you want. For example, specify .txt if you want the FOP to generate a text file.

Stylus Studio User Guide

Generating Scalable Vector Graphics

If there is additional path information that the FOP will require to execute
successfully, type it in the Additional path field.

Click OK.

Generating Scalable Vector Graphics

The procedure for defining a stylesheet that generates an XML document that containts
Scalable Vector Graphics (SVG) is the same as for any other stylesheet. Simply create a
stylesheet that specifically creates SVG elements. You can then use Stylus Studio to
display the rendered SVG.
Note SVG is a W3C recommendation for an XML vocabulary that describes two-dimensional

graphics. It is assumed that you are familiar with SVG. For additional information about
SVG, see http://www.w3.org/Graphics/SVG.

About SVG Viewers

If you have an installed SVG viewer, Stylus Studio automatically displays the rendered
SVG when you apply the stylesheet.
If you do not have an installed SVG viewer, you can still define a styelesheet that
generates SVG. However, when you try to preview the result of the stylesheet, Stylus
Studio displays the generated XML. You can download an SVG viewer from Adobe
Systems Incorporated at http://www.adobe.com/support/downloads/main.html. Under
Readers, select the SVG Viewer for Windows. After you install an SVG viewer, you must
restart Stylus Studio and Internet Explorer to be able to view the rendered graphics.

Running the SVG Example

To run the SVG example that is included in Stylus Studio:
1.

In Stylus Studio, open the examples\SVG\chart.xsl file in your Stylus Studio

installation directory.
Alternative: If the Stylus Studio examples project is open, you can access this file from
the Project window. To open the examples project, open examples.prj in the Stylus
Studio examples directory.

Stylus Studio User Guide

453

Working with XSLT

The SalesFigures scenario has already been defined. In this scenario, the stylesheet
operates on elements in the chart.xml source document. This file is also in the
examples project, and in the examples\SVG directory.
2.

Click Preview XSLT Result

. Stylus Studio automatically uses your installed
SVG viewer to render the resulting XML and display the SVG.
If you do not have an SVG viewer installed, Stylus Studio displays the resulting
XML.

Generating Java Code for XSLT

Java code generation is available only in Stylus Studio XML Enterprise Suite.

You can generate Java code for XSLT transformations in Stylus Studio. This section
describes the generated code, scenario settings that affect the generated code, as well as
procedures for generating, compiling, and running generated code.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Java Code Generation video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

What Does Stylus Studio Generate?

Scenario Properties Used for Generating Code

Java Code Generation Settings

How to Generate Java Code for XSLT

Compiling Generated Code

Deploying Generated Code

Tip You can also generate:

454

C# code for XSLT. See Generating C# Code for XSLT

Java code for XQuery. See Generating Java Code for XQuery

Stylus Studio User Guide

Generating Java Code for XSLT

What Does Stylus Studio Generate?

Stylus Studio generates a complete Java application that implements the XSLT
represented by the current XSLT transformation using settings from the current scenario.
The Java code can be compiled and run within Stylus Studio.

Scenario Properties Used for Generating Code

When you generate code for XSLT, Stylus Studio uses some of the information associated
with the active XSLT scenario, as specified in the Scenario Properties dialog box.
The following tables summarizes the scenario properties that affect code generation.
Table 61. Scenario Properties that Affect Code Generation
Tab

Comment

General

The Code Generation wizard uses only the Source XML URL and the
Output URL field, if specified. All other properties on this page are
ignored.

Processor

You can use the following XSLT processors for generating Java code:

Saxon

Java built-in

If the Stylus Studio URI Resolver property is selected, the generated

code includes lines that import and register ConverterFactory and
ConverterResolver classes from DataDirect XML Converters.
Note: If the scenario specifies an XSLT processor for which Java code
generation is not supported, Stylus Studio uses the Java built-in processor
for code generation purposes. The processor specified in the scenario is not
changed.
Parameter Values

By default, parameter values are treated as a literal string. If you prefer to

have parameter values treated as XPath expressions in the generated code,
check the Parameter value is an XPath expression (not a string)
checkbox.

Profiling Options

Ignored.

Stylus Studio User Guide

455

Working with XSLT

Table 61. Scenario Properties that Affect Code Generation
Tab

Comment

Validation

You can use the following validation engines for validating your XSLT Java
code:

Saxon

Java built-in

If you choose a validation engine that is not supported, Stylus Studio uses
the Java built-in validation engine.
Post-process

Only post-processing using Apache FOP and RenderX XEP is specified in

the generated code. Resulting PDF is written to the output URL specified
on the General tab.

Java Code Generation Settings

When you generate Java code for an XSLT transformation, Stylus Studio displays the
Java Code Generation dialog box.

Figure 250. Java Code Generation Dialog Box

You use this dialog box to specify

456

Stylus Studio User Guide

Generating Java Code for XSLT

The default is a \sources directory created in your Windows user data directory
C:\Documents and Settings\sula\My Documents\Stylus Studio\sources , for
example.
Optionally, a package name. If you specify a package name, this name is used for a
subfolder created in the target directory you specify. If you specify myPackage as the
package name, for example, the generated code is written to
c:\temp\myJavaCode\myPackage. (Though optional, it is considered good practice to
create a package name.)
The class name. Stylus Studio also uses the class name for the .java file created by
the Code Generation wizard. For example, if you provide the name myClass, Stylus
Studio creates c:\temp\myJavaCode\myPackage\myClass.java.
The default class name is taken from the XSLT file name.
Whether or not you want to add the generated code to the current Stylus Studio
project. If you choose to add the generated code to the project, it creates a folder using
the package name you specify and places the .java file in that folder. If you do not
specify a package name, the .java file is added directly below the project root in the
Project window.

How to Generate Java Code for XSLT

To generate Java code for XSLT:
1.

Open the XSLT file for which you want to generate Java code.

Define at least one scenario. The scenario must use the Saxon or Java built-in
processor. See Scenario Properties Used for Generating Code on page 455 for more
information.

Select the scenario for which you want to generate Java code.

Close the Scenario Properties dialog box.

Select XSLT > Generate Code > Generate Java Code from the Stylus Studio menu.
The Generate Java Code dialog box appears. (See Figure 250 on page 456.)

Specify the settings you want for the target directory, package and class names, and
so on. See Java Code Generation Settings if you need help with this step.

Click OK.

Stylus Studio User Guide

457

Working with XSLT

Stylus Studio generates Java code for the XSLT. When the code generation is
complete, the resulting file (classname.java) is opened in the Stylus Studio Java
Editor.

458

Stylus Studio User Guide

Generating Java Code for XSLT

Compiling Generated Code

The generated code contains a commented list of the DLL files required in order to
compile.

How to Compile and Run Java Code in Stylus Studio

To compile Java code in Stylus Studio:
1.

Make sure the Java Editor is the active window.

Click the Compile button (

).
Alternatives: Press Ctrl + F7, or select Java > Compile from the Stylus Studio menu.
Stylus Studio compiles the Java code. Results are displayed in the Output window.

To run Java code in Stylus Studio:

Make sure the Java Editor is the active window.

Click the Run button ( ).

Alternatives: Press Ctrl + F5, or select Java > Run from the Stylus Studio menu.
If the code has not been compiled, Stylus Studio displays a prompt asking if you want
to compile the code now. Otherwise, Stylus Studio runs the Java code. Results are
displayed in the Output window.

Deploying Generated Code

If your XSLT uses built-in DataDirect XML Converters to convert CSV or EDI to
XML, for example you need to purchase licenses for the DataDirect XML Converters
you wish to use if you wish to deploy your code in any environment on a machine (such
as a test or application server) that does not have a license for the DataDirect XML
Converters. Licenses for DataDirect XML Converters are purchased separately from
Stylus Studio X14 XML Enterprise Suite.
Write Stylus Studio at [email protected], or call 781.280.4488 for more
information.

Stylus Studio User Guide

459

Working with XSLT

Generating C# Code for XSLT

C# code generation is available only in Stylus Studio XML Enterprise Suite
.
You can generate C# code for XSLT transformations in Stylus Studio. This section
describes the generated code, scenario settings that affect the generated code, as well as
procedures for generating, compiling, and running generated code.
This section covers the following topics:

What Does Stylus Studio Generate?

Scenario Properties Used for Generating Code

C# Code Generation Settings

How to Generate C# Code for XSLT

Compiling Generated Code

Deploying Generated Code

Tip You can also generate:

Java code for XSLT. See Generating Java Code for XSLT
C# code for XQuery. See Generating C# Code for XQuery

What Does Stylus Studio Generate?

Stylus Studio generates a C# application that implements the XSLT represented by the
current XSLT transformation using settings from the current scenario. The C# code can
be compiled and run within Stylus Studio.

Scenario Properties Used for Generating Code

When you generate code for XSLT, Stylus Studio uses some of the information associated
with the active XSLT scenario, as specified in the Scenario Properties dialog box.

460

Stylus Studio User Guide

Generating C# Code for XSLT

The following tables summarizes the scenario properties that affect code generation.
Table 62. Scenario Properties that Affect Code Generation
Tab

Comment

General

The Code Generation wizard uses only the Source XML URL and the
Output URL field, if specified. All other properties on this page are
ignored.

Processor

You can use the following XSLT processors for generating Java code:

Microsoft XslCompiledTransform

Saxon

Note: If the scenario specifies an XSLT processor for which C# code

generation is not supported, Stylus Studio uses the Microsoft
XslCompiledTransform processor for code generation purposes. The
processor specified in the scenario is not changed.
Parameter Values

By default, parameter values are treated as a literal string. If you prefer to

have parameter values treated as XPath expressions in the generated code,
check the Parameter value is an XPath expression (not a string)
checkbox.

Profiling Options

Ignored.

Validation

You can use the following validation engines for validating your XSLT C#
code:

.NET XML Parser

Saxon

If you choose a validation engine that is not supported, Stylus Studio uses
the .NET XML parser.
Post-process

Stylus Studio User Guide

Only post-processing using Apache FOP and RenderX XEP is specified in

the generated code. Resulting PDF is written to the output URL specified
on the General tab.

461

Working with XSLT

C# Code Generation Settings

When you generate C# code for an XSLT transformation, Stylus Studio displays the C#
Code Generation dialog box.

Figure 251. C# Code Generation Dialog Box

You use this dialog box to specify

The target directory in which you want the C# code created. c:\temp\myC#Code, for
example. If the directory you name does not exist, Stylus Studio creates it when you
run the Code Generation wizard.
The default is a \sources directory created in your Windows user data directory
C:\Documents and Settings\sula\My Documents\Stylus Studio\sources , for
example.

Optionally, a namespace name. If you specify a namespace name, this name is used
for a subfolder created in the target directory you specify. If you specify
myNamespace as the package name, for example, the generated code is written to
c:\temp\myC#Code\myNamespace. (Though optional, it is considered good practice to
create a namespace name.)

462

Stylus Studio User Guide

Generating C# Code for XSLT

The class name. Stylus Studio also uses the class name for the .cs file created by the
Code Generation wizard. For example, if you provide the name myClass, Stylus
Studio creates c:\temp\myC#Code\myNamespace\myClass.cs.
the default class name.
The location of Saxon .NET on your system. Stylus Studio adds this URL to the
Microsoft Visual Studio 2005 project, allowing the generated C# code for .NET to
compile.
Whether or not you want the resulting .cs file to contain a static void Main(String
[ ] args) method.
Whether or not you want to open the generated code in a third-party development
tool, like Microsoft Visual Studio, for example.
Whether or not you want add the class to a new Visual Studio 2005 project or update
an existing one. If a new project is created, it is automatically opened with whatever
application is registered to open .csproj files. The .csproj file contains all the
necessary references to the generated .cs file, as well as all the .dll files that the .cs
file requires.
To run the .cs file, simply press Ctrl+F5 in Visual Studio.

How to Generate C# Code for XSLT

To generate C# code for XSLT:
1.

Open the XSLT for which you want to generate C# code.

Define at least one scenario for the XSLT transformation. The scenario must use the
Saxon processor. See Scenario Properties Used for Generating Code for more
information.

Select the scenario for which you want to generate C# code.

Close the Scenario Properties dialog box.

Select XSLT > Generate Code > Generate C# Code from the Stylus Studio menu.
The Generate C# Code dialog box appears. (See Figure 251 on page 462.)

Specify the settings you want for the target directory, package and class names, and
so on. See C# Code Generation Settings if you need help with this step.

Click OK.

Stylus Studio User Guide

463

Working with XSLT

Stylus Studio generates C# code for the XSLT. When the code generation is complete,
the resulting file (classname.cs) is opened in a third-party editor if you chose the
Open the generated file option.

464

Stylus Studio User Guide

XSLT Instructions Quick Reference

Compiling Generated Code

The generated code contains a commented list of the DLL files required in order to
compile.

Deploying Generated Code

XSLT Instructions Quick Reference

This section provides a quick reference for the XSLT instructions supported by the Stylus
Studio XSLT processor.
For more information on

XSLT 1.0, go to http://www.w3.org/TR/xslt

XSLT 2.0, go to http://www.w3.org/TR/xslt/20

This section covers the following instructions:

xsl:apply-imports on page 467

xsl:apply-templates on page 467

xsl:attribute on page 468

xsl:attribute-set on page 469

xsl:call-template on page 471

xsl:character-map on page 471

xsl:choose on page 474

xsl:comment on page 475

xsl:copy on page 475

xsl:copy-of on page 476

Stylus Studio User Guide

465

Working with XSLT

466

xsl:decimal-format on page 477

xsl:element on page 478
xsl:fallback on page 479
xsl:for-each on page 479
xsl:for-each-group on page 481
xsl:function on page 482
xsl:if on page 483
xsl:import on page 484
xsl:import-schema on page 484
xsl:include on page 486
xsl:key on page 487
xsl:message on page 488
xsl:namespace-alias on page 489
xsl:number on page 489
xsl:otherwise on page 490
xsl:output on page 490
xsl:output-character on page 493
xsl:param on page 493
xsl:preserve-space on page 495
xsl:processing-instruction on page 495
xsl:sequence on page 496
xsl:sort on page 496
xsl:strip-space on page 498
xsl:stylesheet on page 499
xsl:template on page 499
xsl:text on page 501
xsl:transform on page 502
xsl:value-of on page 502
xsl:variable on page 503
xsl:when on page 504
xsl:with-param on page 504

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:apply-imports
Invokes overridden template rules.
Stylus Studio does not support the xsl:apply-imports instruction.

xsl:apply-templates
Selects source nodes for processing.

Format
<xsl:apply-templates [select="pattern"][mode="qname"]>
[<xsl:sort/>]
[<xsl:with-param/>
</xsl:apply-templates>

Description
If you specify the select attribute, specify a pattern that resolves to a set of source nodes.
For each source node in this set, the XSLT processor searches for a template that matches
the node. When it finds a matching template, it instantiates it and uses the node as the
context node. For example:
<xsl:apply-templates select="/bookstore/book">

When the XSLT processor executes this instruction, it constructs a list of all nodes that
match the pattern in the select attribute. For each node in the list, the XSLT processor
searches for the template whose match pattern best matches that node.
If you do not specify the select attribute, the XSLT processor uses the default pattern,
"node()", which selects all child nodes of the current node.
If you specify the mode attribute, the selected nodes are matched only by templates with a
matching mode attribute. The value of mode must be a qualified name or an asterisk (*). If
you specify an asterisk, it means continue the current mode, if any, of the current template.
If you do not specify a mode attribute, the selected nodes are matched only by templates
that do not specify a mode attribute
By default, the new list of source nodes is processed in document order. However, you can
use the xsl:sort instruction to specify that the selected nodes are to be processed in a
different order. See xsl:sort on page 496.
Tip You can create an xsl:apply-templates element automatically using the XSLT mapper.

Stylus Studio User Guide

467

Working with XSLT

Example
In the previous example, the XSLT processor searches for a template that matches
/bookstore/book. The following template is a match:
<xsl:template match="book">
<tr>
<td><xsl:value-of select="title"/></td>
<td><xsl:value-of select="author"/><td>
<td><xsl:value-of select="price"/><td>
</tr>
</xsl:template>

The XSLT processor instantiates this template for each book element.

xsl:attribute
Creates an attribute.

Format
<xsl:attribute name="qualified_name">
attribute_value
</xsl:attribute>

Description
You can specify the xsl:attribute instruction in the

Contents of a stylesheet element that creates a result element

Contents of an xsl:attribute-set instantiation

In a stylesheet element that creates a result element, the xsl:attribute instruction causes
an attribute to be added to the created result element.
The prefix part of the name attribute value becomes the prefix for the attribute you are
creating. The local part of the name attribute value becomes the local name of the attribute
you are creating.
The XSLT processor interprets the name attribute as an attribute value template. The string
that results from instantiating the attribute value template must be a qualified name. If it
is not, the XSLT processor reports an error.
The result of instantiating the content of the xsl:attribute instruction is used as the value
of the created attribute. It is an error if instantiating this content generates anything other
than characters.

468

Stylus Studio User Guide

XSLT Instructions Quick Reference

If you add an attribute to an element and that element already has an attribute with the
same expanded name, the attribute you are creating replaces the existing attribute.

Example
<xsl:attribute name="library:ISBN"
namespace="http://www.library.org/namespaces/library">
1-2222-333-4
</xsl:attribute>

If this instruction is inside a book element, the resulting book element would include the
following attribute:
library:ISBN="1-22222-333-4"

The XSLT processor reports an error if you try to do any of the following:

Add an attribute to a node that is not an element.

Add an attribute to an element that already has child nodes.

Create anything other than characters during instantiation of the contents of the
xsl:attribute element.

xsl:attribute-set
Defines a named set of attributes.

Format
<xsl:attribute-set name="set_name">
<xsl:attribute name="attr_name">attr_value</xsl:attribute>
<xsl:attribute name="attr_name">attr_value</xsl:attribute>
...
</xsl:attribute-set>

Description
The name attribute specifies the name of the attribute set. This must be a qualified name.
The contents of the xsl:attribute-set element consists of zero or more xsl:attribute
elements. Each xsl:attribute element specifies an attribute in the set.
To use an attribute set, specify the use-attribute-sets attribute in one of the following
elements:

xsl:element

xsl:copy

Stylus Studio User Guide

469

Working with XSLT

xsl:attribute-set

The value of the use-attribute-sets attribute is a white-space-separated list of names of

<xsl:output-character character=""
string="<img src='special1.gif' />" />
<xsl:output-character character=""
string="<img src='special2.gif' />" />
...
</xsl:character-map>

Stylus Studio User Guide

473

Working with XSLT

xsl:choose
Selects one template to instantiate from a group of templates.

Format
<xsl:choose>
<xsl:when test="expression1">
template_body
</xsl:when>
[<xsl:when test="expression2">
template_body
</xsl:when>] ...
[<xsl:otherwise>
template_body
</xsl:otherwise>]
</xsl:choose>

Description
An

element contains one or more xsl:when elements followed by zero or one

xsl:otherwise element. Each xsl:when element contains a required test attribute, whose
value is an expression. Each xsl:when and xsl:otherwise element contains a template.
xsl:choose

When the XSLT processor processes an xsl:choose element, it starts by evaluating the
expression in the first xsl:when element. The XSLT processor converts the result to a
Boolean value. If the result is true, the XSLT processor instantiates the template
contained by that xsl:when element. If the result is false, the XSLT processor evaluates
the expression in the next xsl:when element.
The XSLT processor instantiates the template of only the first xsl:when element whose
test expression evaluates to true. If no expressions evaluate to true and there is an
xsl:otherwise element, the XSLT processor instantiates the template in the
xsl:otherwise element.
If no expressions in xsl:when elements are true and there is no xsl:otherwise element,
the xsl:choose element has no effect.
Tip You can create an xsl:choose element automatically using the XSLT mapper.

474

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:comment
Adds a comment node to the result tree.

Format
<xsl:comment>
comment_text
</xsl:comment>

Description
The XSLT processor instantiates the contents of the instruction to generate the text of the
new comment.
The XSLT processor reports an error if instantiating the contents of the xsl:comment
instruction creates anything other than characters, or if the resulting string contains the
substring "--" or ends with "-".

Example
The following instruction creates a comment in the result document:
<xsl:comment>Unique Irish band</xsl:comment>

The comment is

xsl:copy
Adds a copy of the current node to the result tree.

Format
<xsl:copy>copy_contents</xsl:copy>

Description
The copy includes the current nodes namespace information but does not include the
current nodes attributes or children. The contents of the xsl:copy element is a template
for the attributes and children of the node being created. If the current node cannot have

Stylus Studio User Guide

475

Working with XSLT

attributes or children (that is, if it is an attribute, text, comment, or processing instruction

node), the content of the instruction is ignored.
If the current node is the root node, the XSLT processor does not create a root node.
Instead, it uses copy_contents as a template.

Example
Following is an example from the W3C XSLT Recommendation. It generates a copy of
the source document.
<xsl:template match="@* | node() ">
<xsl:copy>
<xsl:apply-templates select="@* | node() " />
</xsl:copy>
</xsl:template>

xsl:copy-of
Inserts the value of an expression into the result tree, without first converting it to a string.

Format
<xsl:copy-of select = "expression" />

Description
The required select attribute contains an expression. When the result of evaluating the
expression is a result tree fragment, the XSLT processor copies the complete fragment
into the result tree. When the result is a node set, the XSLT processor copies all nodes in
the set, together with their contents, in document order into the result tree. When the result
is of any other type, the XSLT processor converts the result to a string and then inserts the
string into the result tree in the same way that xsl:value-of does.
Tip You can also use xsl:sequence to add atomic values to a sequence. See xsl:sequence on

page 496 for more information.

476

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:decimal-format
Declares a decimal format.

Format
<xsl:decimal-format
name = qname
decimal-separator = char
grouping-separator = char
infinity = string
minus-sign = char
NaN = string
percent = char
per-mille = char
zero-digit = char
digit = char
pattern-separator = char />

Description
The xsl:decimal-format instruction declares a decimal format, which controls the
interpretation of a format pattern that is used by the format-number() function.
If there is a name attribute, the element declares a named decimal format. Otherwise, it
declares the default decimal format. The value of the name attribute is a qualified name.
The other attributes on xsl:decimal-format correspond to the methods on the JDK
DecimalFormatSymbols class. For each get/set method pair, there is an attribute defined for

the xsl:decimal-format instruction.

The following attributes control the interpretation of characters in the format pattern and
specify characters that can appear in the result of formatting the number:

decimal-separator specifies the character used for the decimal sign; the default value
is the dot character (.).

grouping-separator specifies the character used as a grouping (for example,

thousands) separator; the default value is the comma character (,).

percent specifies the character used as a percent sign; the default value is the percent
character (%).

per-mille specifies the character used as a per mille sign; the default value is the
Unicode per mille character (#x2030).

zero-digit specifies the character used as the digit zero; the default value is the digit
zero (0).
The following attributes control the interpretation of characters in the format pattern:
Stylus Studio User Guide

477

Working with XSLT

digit specifies the character used for a digit in the format pattern; the default value is

the number sign character (#).

pattern-separator specifies the character used to separate positive and negative
subpatterns in a pattern; the default value is the semicolon character (;).

The following attributes specify characters or strings that can appear in the result of
formatting the number:

infinity specifies the string used to represent infinity; the default value is the string
"Infinity".

minus-sign specifies the character used as the default minus sign; the default value is
the hyphen (minus) character (-, #x2D).

NaN specifies the string used to represent the NaN value; the default value is the string
"NaN".

xsl:element
Adds an element to the result tree.

Format
<xsl:element name="qualified_name">
element_contents
</xsl:element>

Description
The XSLT processor uses the contents of the xsl:element instruction as a template for the
attributes and contents of the new element.
The prefix part of the name attribute becomes the prefix for the element you are creating.
The local part of the name attribute becomes the local name of the element you are
creating.
The XSLT processor interprets the name attribute as an attribute value template. The string
that results from instantiating the attribute value template must be a qualified name. If it
is not, the XSLT processor reports an error.

478

Stylus Studio User Guide

XSLT Instructions Quick Reference

Example
<xsl:element name="audio:CD">
<xsl:element name="audio:title">Celtic Airs</xsl:element>
<xsl:element name="audio:artist">Chieftains</xsl:element>
</xsl:element>

The result of this instruction looks like the following:

<audio:CD>
<audio:title>Celtic Airs</audio:title>
<audio:artist>Chieftains</audio:artist>
</audio:CD>

xsl:function
Allows the creation of user-defined stylesheet function that can be called from any XPath
expression within the stylesheet in which the function is defined. This instruction is
supported in XSLT 2.0 only.

Format
<xsl:function name=Qname" as=sequence type [override=yes | no]>
function_body
</xsl:function>

Description
The value of the name attribute, Qname, is a qualified name and takes the form prefix:name.
The prefix is required in order to avoid possible conflicts with any functions in the default
function namespace. The prefix cannot refer to a reserved namespace.
The function_body contains zero or more xsl:param elements that specify the formal
arguments of the function. These xsl:param elements are followed by a sequence
constructor that defnes the value to be returned by the function. The xsl:param elements
within an xsl:function element must be empty; they cannot have a select attribute
because they must be specified.
An xsl:function declaration can only appear as a top-level element in a stylesheet.

482

Stylus Studio User Guide

XSLT Instructions Quick Reference

Example
Here is an example from the W3C XSLT Working Draft of a simple function that reverses
the order of the words in a sentence.
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:str="http://example.com/namespace"
version="2.0"
exclude-result-prefixes="str">
<xsl:function name="str:reverse" as="xs:string">
<xsl:param name="sentence" as="xs:string"/>
<xsl:sequence
select="if (contains($sentence, ' '))
then concat(str:reverse(substring-after($sentence, ' ')),
' ',
substring-before($sentence, ' '))
else $sentence"/>
</xsl:function>
<xsl:template match="/">
<output>
<xsl:value-of select="str:reverse('DOG BITES MAN')"/>
</output>
</xsl:template>
</xsl:transform>

xsl:if
Conditionally instantiates the contained template body.

Format
<xsl:if test = "expression">
template_body
</xsl:if>

Description
The XSLT processor evaluates the expression and converts the result to a Boolean value.
If the result is true, the XSLT processor instantiates template_body. If the result is false,
the xsl:if element has no effect.

Stylus Studio User Guide

483

Working with XSLT

Example
This following example formats a group of names as a comma-separated list:
<xsl:template match="namelist/name">
<xsl:value-of select="." />
<xsl:if test="not(position()=last())">, </xsl:if>
</xsl:template>

If you want the XSLT processor to choose which template to instantiate from several
possibilities, specify the xsl:choose instruction. See xsl:choose on page 474.

xsl:import
Imports a stylesheet into the stylesheet containing this instruction.

Format
<xsl:import href="stylesheet_path">
stylesheet_path specifies

the stylesheet you want to import. Specify a URL, a relative

path, or a DOS-style path.

Description
An XSLT stylesheet can import another XSLT stylesheet by using an xsl:import
instruction. Importing a stylesheet is the same as including it, except that definitions and
template rules in the importing stylesheet take precedence over template rules and
definitions in the imported stylesheet.
The xsl:import element is only allowed as a top-level element. The xsl:import element
children must precede all other element children of an xsl:stylesheet element, including
any xsl:include element children. When xsl:include is used to include a stylesheet, any
xsl:import elements in the included document are moved up in the including document
to after any existing xsl:import elements in the including document.
When you use the xsl:import instruction, templates have an importance property.

xsl:import-schema
Identifies schema components (top-level type definitions and top-level element and
attribute declarations) that need to be available statically, that is, before any source

484

Stylus Studio User Guide

XSLT Instructions Quick Reference

document is available. Allows you to extend XSLT built-in types with the types defined
in the imported XML Schema.

Format
<xsl:import-schema
namespace = uri-reference
schema-location = uri-reference>

</xsl:import-schema>

Description
The xsl:import-schema declaration identifies a namespace containing the names of the
components to be imported (or indicates that components whose names are in no
namespace are to be imported). The effect is that the names of top-level element and
attribute declarations and type definitions from this namespace (or non-namespace)
become available for use within XPath expressions in the stylesheet, and within other
stylesheet constructs such as the type and as attributes of various XSLT elements.
The same schema components are available in all stylesheet modules; importing
components in one stylesheet module makes them available throughout the stylesheet.
The namespace and schema-location elements are optional. The namespace attribute
indicates that a schema for the given namespace is required by the stylesheet. This
information may be enough on its own to enable an implementation to locate the required
schema components. The namespace attribute may be omitted to indicate that a schema for
names in no namespace is being imported. The zero-length string is not a valid namespace
URI, and is therefore not a valid value for the namespace attribute.
The schema-location attribute is a URI Reference that describes where a schema
document or other resource containing the required definitions may be found. It is likely
that a schema-aware XSLT processor will be able to process a schema document found at
this location.
The use of a namespace in an xsl:import-schema declaration does not by itself associate
any namespace prefix with the namespace. If names from the namespace are used within
the stylesheet module then a namespace declaration must be included in the stylesheet
module, in the usual way.
You can also define an inline schema document using the xs:schema element as a child of
xsl:import-schema. An inline schema document has the same status as an external schema
document, in the sense that it acts as a hint for a source of schema components in the

Stylus Studio User Guide

485

Working with XSLT

relevant namespace. To ensure that the inline schema document is always used, it is
advisable to use a target namespace that is unique to this schema document.

Example
The following example shows an inline schema document defined using the xs:schema
subelement. This schema declares a simple type local:yes-no, which the stylesheet then
uses in the declaration of a variable. The example assumes the namespace declaration
xmlns:local="http://localhost/ns/yes-no".
<xsl:import-schema>
<xs:schema targetNamespace="http://localhost/ns/yes-no">
<xs:simpleType name="local:yes-no">
<xs:restriction base="xs:string">
<xs:enumeration value="yes"/>
<xs:enumeration value="no"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
</xs:import-schema>
<xs:variable name="condition" select="'yes'" as="local:yes-no"/>

xsl:include
Specifies an XSLT stylesheet that is included in and combined with the stylesheet that
specifies xsl:include.

Format
<xsl:include href="stylesheet_path">

Description
The xsl:include instruction must be a child of an xsl:stylesheet element. The XSLT
processor effectively replaces the xsl:include instruction with the children of the root
xsl:stylesheet element of the included stylesheet. If the root element of the included
stylesheet is a literal result element, the XSLT processor effectively replaces the
xsl:include instruction with the following new element whose only child is that literal
result element:
<xsl:template match="/">

A stylesheet cannot include itself directly or indirectly.

486

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:key
Declares a key for a document.

Format
<xsl:key name="qname"
match = "pattern"
use = "use" />

Description
Keys provide a way to work with documents that contain an implicit cross-reference
structure. A stylesheet declares a key for a document with the xsl:key instruction.
The xsl:key instruction must be a top-level element. It has no contents, but it specifies
three attributes.
Replace qname with the name of the key. You must specify a qualified name.
Replace pattern with a pattern that identifies one or more nodes that have this key. In
other words, the nodes in the document that match the pattern are included in the key. The
default is node().
Replace use with an expression that you want to use for the key values. The XSLT
processor evaluates the expression once for each node in the set identified by pattern.
Each key name represents a separate, independent set of identifiers. Each node included
in a key is associated with a set of string key values. These values result from evaluating
the use expression with that node as the current node.
A document can contain multiple keys with the same node and the same key name, but
with different key values. A document can contain multiple keys with the same key name
and value, but with different nodes. In other words:

A node can be included in more than one key.

For a given key, a key value can be associated with more than one node.

The same key value can be associated with different nodes in different keys.
The value of a key can be an arbitrary string. It need not be a name.
Use the XSLT key() function to retrieve the list of nodes included in a given key that have
given key values. See Finding an Element with a Particular Key on page 767.
You cannot specify multiple declarations for the same key in a stylesheet. Stylus Studio
expects to remove this restriction in a future release.
Stylus Studio User Guide

487

Working with XSLT

xsl:message
Sends a message in a way that is dependent on the XSLT processor.

Format
<xsl:message terminate="yes" | "no">

</xsl:message>

Description
The content of the xsl:message instruction is a template. If the value of the terminate
attribute is yes, the XSLT processor instantiates the template to create text. The processor
aborts stylesheet processing and sends the text as part of the error message that indicates
that stylesheet processing has terminated.
The default value of the terminate attribute is no. If you specify terminate="no" or if you
do not specify the terminate attribute,

488

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:namespace-alias
Causes the namespace URI to be changed in the output.

Format
<xsl:namespace-alias
stylesheet-prefix = prefix | "#default"
result-prefix = prefix | "#default" />

Description
Declares that one namespace URI is an alias for another namespace URI. When a literal
namespace URI has been declared to be an alias for another namespace URI, then the
namespace URI in the result tree is the namespace URI that the literal namespace URI is
an alias for, instead of the literal namespace URI itself.

xsl:number
Inserts a formatted number into the result tree.

Format
<xsl:number
[level = "single" | "multiple" | "any"]
[count = pattern]
[from = pattern]
[value = number-expression]
[format = {string}]
[lang = {nmtoken}]
[letter-value = {"alphabetic" | "traditional"}]
[grouping-separator = {char}]
[grouping-size = {number}]/>

Description
You can use the value attribute to specify an expression for the number to be inserted. The
XSLT processor evaluates the expression. The resulting object is converted to a number
as if by a call to the number() function. The processor rounds the number to an integer and
then uses the specified attributes to convert it to a string. The value of each attribute is
interpreted as an attribute value template. After conversion, the resulting string is inserted
in the result tree.
The following attributes control how the current node is to be numbered:

Stylus Studio User Guide

489

Working with XSLT

The level attribute specifies what levels of the source tree should be considered. The
default is single.
The count attribute is a pattern that specifies what nodes should be counted at those
levels.
The from attribute is a pattern that specifies where counting starts.
The value attribute can specify an expression that represents the number you want to
insert. If no value attribute is specified, the XSLT processor inserts a number based
on the position of the current node in the source tree.
The format attribute specifies the format for each number in the list. The default is 1.
The lang attribute specifies which languages alphabet is to be used.
The letter-value attribute distinguishes between the numbering sequences that use
letters.
The grouping-separator attribute specifies the separator used as a grouping (for
example, thousands) separator in decimal numbering sequences.
The grouping-size attribute specifies the size of the grouping. Normally, this is 3.

Example
The following example numbers a sorted list:
<xsl:template match="items">
<xsl:for-each select="item">
<xsl:sort select="."/>
<p>
<xsl:number value="position()" format="1. "/>
<xsl:value-of select="."/>
</p>
</xsl:for-each>
</xsl:template>

xsl:otherwise
See xsl:choose on page 474.

xsl:output
Specifies the output for the result tree.

Format
<xsl:output attribute_list />

490

Stylus Studio User Guide

XSLT Instructions Quick Reference

Description
The xsl:output instruction specifies how you want the result tree to be output. However,
if you use the XSLT processor to format the result as a string, or to generate DOM nodes,
the xsl:output instruction has no effect.
If you specify the xsl:output instruction, the XSLT processor outputs the result tree
according to your specification. If you specify it, the xsl:output instruction must be a
top-level element.
The attribute list can include the method attribute. The method attribute identifies the
overall method you want the XSLT processor to use to output the result tree. The value
must be xml, html, or text.

xml formats the result tree as XML.

html formats the result tree as HTML. The stylesheet applies special formatting rules
for empty tags, binary attributes, and character escaping, among other things. The
values of the attributes named href and src are URL encoded.

text concatenates the text nodes in the result tree. The concatenated string does not
include any tags.
Note that the XSLT processor formats the results of applying the stylesheet. If your
stylesheet generates XML or HTML that does not follow all syntax rules, the XSLT
processor does not do anything to fix this. For example, if a stylesheet generates multiple
root elements, the XSLT processor neither fixes this nor generates an error. You receive a
string, and it is only upon examination or use of the string that you would learn that it is
not well-formed XML.
If you do not specify an xsl:output instruction that includes the method attribute, the
XSLT processor chooses a default as follows:

html is the default output method if the name of the first element child of the root node
is html.

text is the default output method if the root node has no element child nodes.

xml is the default output method in all other cases.

The other attributes that you can specify in attribute_list provide parameters for the
You can specify the following attributes:

doctype-public specifies the public identifier to be used in the document type

declaration.

doctype-system specifies the system identifier to be used in the document type

declaration.
output method.

Stylus Studio User Guide

491

Working with XSLT

encoding specifies

the preferred character encoding that the XSLT processor should

use to encode sequences of characters as sequences of bytes.
indent specifies whether the XSLT processor can add additional white space when
outputting the result tree. The value must be yes or no.
media-type specifies the media type (MIME content type) of the data that results from
outputting the result tree. Do not explicitly specify the charset parameter. Instead,
when the top-level media type is text, add a charset parameter according to the
character encoding actually used by the output method.
omit-xml-declaration specifies whether the XSLT processor should omit or output an
XML declaration. The value must be yes or no. If you do not specify this attribute,
whether or not the output contains an XML declaration depends on the output
method.

If the output method is html, the XSLT processor does not insert an XML
declaration.

If the output method is xml, the XSLT processor inserts an XML declaration.
The XSLT processor ignores this attribute when the output method is text.
standalone specifies whether the XSLT processor should output a stand-alone
document declaration. The value must be yes or no.
use-character-map specifies the name, if any, of the character map you want to use
for the output. A character map substitutes characters based on character/string
mappings declared in the xsl:character-map element.

A stylesheet can include multiple xsl:output elements. The XSLT processor effectively
merges multiple xsl:output elements into one xsl:output element. If there are multiple
values for the same attribute, the XSLT processor uses the last specified value.
In this release, the XSLT processor ignores the following attributes:

cdata-section-elements specifies a list of the names of elements whose text node

children should be output using CDATA sections.

version specifies the version of the output method.

492

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:output-character
Declares character/string mappings used by the xsl:character-map declaration.
xsl:output-character is supported in XSLT 2.0 only.

Format
<xsl:output-character
character = char
string = string />

Description
The character map that is passed as a parameter to the serializer contains a mapping for
the character specified in the character attribute to the string specified in the string
attribute.

Example
See xsl:character-map on page 471.

xsl:param
Declares a parameter for a stylesheet or template, and specifies a default value for the
parameter.

Format
<xsl:param name="parameter_name"
[select = "expression1"]
[expr = "expression2"]>
[template_body]
</xsl:param>

Description
The xsl:param instruction declares a parameter and specifies its default value. Another
value can be passed to this parameter when the template or stylesheet that contains this
xsl:param instruction is invoked.
The xsl:param element must be a child of either an xsl:stylesheet or
element.

Stylus Studio User Guide

xsl:template

493

Working with XSLT

The name attribute is required, and it must be a string. The value of the name attribute is a
qualified name.
The value that you bind to a parameter can be an object of any of the types that are
returned by expressions. You can specify the value of the parameter in several ways:

Specify the select attribute. The value of the select attribute must be an expression.
The XSLT processor evaluates the expression, and the result is the default value of the
parameter. If you specify the select attribute, the XSLT processor ignores any value
you might specify for the expr attribute, and also ignores any contents of xsl:param.

Specify the expr attribute. The expr attribute allows computation of an expression.
For example:
<xsl:param name="query" expr="//VEHICLE[MAKE='{$make}']"/>

The XSLT processor interprets the value of the expr attribute as an attribute value
template and uses the resulting string as if it were the value of the select attribute. If
you specify the expr attribute, the XSLT processor ignores any contents of xsl:param.
The use of the expr attribute is an extension to the XSLT specification.
Specify template_body. The XSLT processor instantiates this template to obtain the
default value of the parameter.
If you do not specify the select attribute, the expr attribute, or template_body, the
default value of the parameter is an empty string.

For any use of the xsl:param element, there is a region of the stylesheet tree within which
the binding is visible. This region includes the siblings that follow the xsl:param
instruction together with their descendants. Within this region, any binding of the
parameter that was visible on the xsl:param element itself is hidden. Thus, only the
innermost binding of a parameter is visible. The set of parameter bindings in scope for an
expression consists of those bindings that are visible at the point in the stylesheet where
the expression occurs.
The xsl:param instruction can be a top-level element. If it is, it declares a global parameter
that is visible to the entire stylesheet. When the XSLT processor evaluates the select or
expr attribute in a top-level xsl:param instruction, the current node is the root node of the
document.

Passing parameters to templates

Use the xsl:with-param instruction to pass a value for a parameter to a template. See
xsl:with-param on page 504.

494

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:preserve-space
The xsl:preserve-space instruction is not supported by Stylus Studio. If this instruction
is in a stylesheet, it is ignored.

xsl:processing-instruction
Adds a processing instruction node to the result tree.

Format
<xsl:processing-instruction name = "pi_name">
processing_instruction
</xsl:processing-instruction>

Description
The XSLT processor interprets the name attribute as an attribute value template, and uses
the resulting string as the target of the created processing instruction. The XSLT processor
then instantiates the contents of xsl:processing-instruction to generate the remaining
contents of the processing instruction.
Errors are reported under the following conditions:

If the string that results from evaluating the name attribute is not both an NCName and a
PITarget (see the XSLT Recommendation). Also, the value of the name attribute
cannot be xml.

If instantiation of the contents of the xsl:processing-instruction element creates

anything other than characters or if the resulting string contains the substring "?>".

Example
<xsl:processing-instruction name = "xml-stylesheet">
href="book.css" type="text/css"
</xsl:processing-instruction>

This instruction creates the following processing instruction in the result document:
<?xml-stylesheet href="book.css" type="text/css"?>

Stylus Studio User Guide

495

Working with XSLT

xsl:sequence
Used within a sequence constructor to construct a sequence of nodes or atomic values.
The sequence is returned as a result of the instruction.

Format
<xsl:sequence
select = expression>
[xsl:fallback]
</xsl:sequence>

Description
Unlike most other instructions, xsl:sequence can return a sequence containing existing
nodes, rather than constructing new nodes. The items comprising the result sequence are
selected using the select attribute. When xsl:sequence is used to add atomic values to a
sequence, the effect is very similar to the xsl:copy-of instruction.
Any optional xsl:fallback instructions are ignored by XSLT 2.0 processors, but they can
be included to define fallback behavior for XSLT 1.0 processors.

Example
This code produces the output, 37.
<xsl:variable name="values" as="xs:integer*">
<xsl:sequence select="(1,2,3,4)"/>
<xsl:sequence select="(8,9,10)"/>
</xsl:variable>
<xsl:value-of select="sum($values)"/>

xsl:sort
Sorts the set of nodes selected by an xsl:apply-templates or xsl:for-each instruction.

Format
<xsl:sort
[select="expression" | expr="expression"]
[optional_attribute]/>

496

Stylus Studio User Guide

XSLT Instructions Quick Reference

Description
The xsl:sort instruction must be the child of an xsl:apply-templates or xsl:for-each
instruction. Each xsl:apply-templates and xsl:for-each instruction can contain more
than one xsl:sort instruction. The first xsl:sort child specifies the primary sort key. The
second xsl:sort child, if any, specifies the secondary sort key, and so on.
When an xsl:apply-templates or xsl:for-each element contains an xsl:sort instruction,
the selected nodes are processed in the order specified by the xsl:sort instructions. When
xsl:sort elements are in an xsl:for-each element, they must appear first before all other
child elements.
You can specify the sort key by using the select attribute, whose value is an expression.
For each node selected by the xsl:apply-templates or xsl:for-each instruction, the XSLT
processor evaluates the expression using the node as the context node. The resulting string
is the sort key for that node. If you do not specify the select attribute, the XSLT processor
uses the string value of the node as the sort key.
When all sort keys for two nodes are equal, nodes remain in document order.
The following optional attributes on xsl:sort determine how the XSLT processor sorts
the list of sort keys. The XSLT processor interprets each of these attribute values as an
attribute value template.

data-type specifies the data type of the strings. The following values are allowed:

text specifies that the sort keys should be sorted lexicographically. All text
sorting is based on Unicode text values.

number specifies that the sort keys should be converted to numbers and then sorted
according to the numeric value. Sort keys that are strings that do not match the
syntax for numbers are sorted as zeros.
The default value is text.

order specifies whether the strings should be sorted in ascending or descending order.
The default is ascending. If the value of the data-type attribute is text, ascending
means that keys are sorted in alphabetical order, and descending means that keys are
sorted in reverse alphabetical order. If the value of data-type is number, ascending
means that keys are sorted in increasing order, and descending means that keys are
ordered in descending order.
The XSLT processor can evaluate xsl:sort order at run time by using an attribute
value template. For example:
<xsl:sort order="{$order)"

Stylus Studio User Guide

497

Working with XSLT

$order is

a run-time specified attribute value template.

The XSLT processor ignores the lang and case-order attributes.

Example
The following example is from the W3C XSLT Recommendation. Suppose an employee
database has the following form:
<employees>
<employee>
<name>
<first>James</first>
<last>Clark</last>
</name>
...
</employee>
</employees>

The following stylesheet fragment sorts the list of employees by name:

<xsl:template match="employees">
<ul>
<xsl:apply-templates select="employee">
<xsl:sort select="name/last"/>
<xsl:sort select="name/first"/>
</xsl:apply-templates>
</ul>
</xsl:template>
<xsl:template match="employee">
<li>
<xsl:value-of select="name/first"/>
<xsl:text> </xsl:text>
<xsl:value-of select="name/last"/>
</li>
</xsl:template>

xsl:strip-space
The xsl:strip-space instruction is not supported by Stylus Studio. If this instruction is in
a stylesheet, it is ignored.

498

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:stylesheet
Specifies the start of a stylesheet.

Format
<xsl:stylesheet
xmlns:xsl="http:///www.w3.org/1999/XSL/Transform" version="1.0" >
stylesheet_body
</xsl:stylesheet>

Description
A stylesheet must specify the xsl:stylesheet element unless it contains only a literal
result element as the root element. The xsl:transform instruction is a synonym for
xsl:stylesheet.
All XSLT elements must appear between the <xsl:stylesheet> and </xsl:stylesheet>
tags. An element that is a child of an xsl:stylesheet element is a top-level element.

xsl:template
Specifies a template rule.

Format
<xsl:template
[match = "pattern"]
[name = "qname"]
[mode = "mode"]
[priority = "priority"]>
template_body
</xsl:template>

Description
The match attribute is required except when you specify the name attribute. The pattern you
specify for the match attribute identifies the source node or set of source nodes to which
the template rule applies.
The optional name attribute specifies a name for the template. You can use the name of a
template to invoke it with the xsl:call-template instruction. The value you specify for
name must be a qualified name. If you specify a name attribute, a match attribute is not
required.

Stylus Studio User Guide

499

Working with XSLT

The optional mode attribute prevents the template from matching nodes selected by an
xsl:apply-templates instruction that specifies a different mode. The value of mode must
be a qualified name or an asterisk (*). If you specify an asterisk, it means match any node.
If an xsl:apply-templates instruction contains a mode attribute, the xsl:apply-templates
instruction can apply to only those xsl:template instructions that specify a mode attribute
with the same value. If an xsl:apply-templates instruction does not contain a mode
attribute, the xsl:apply-templates instruction can apply to only those xsl:template
instructions that do not specify a mode attribute.
If you specify the match and mode attributes, they have no effect if the template is
instantiated by the xsl:call-template instruction. If you specify the name attribute, you
can still instantiate the template as a result of an xsl:apply-templates instruction.
If two or more templates have the same name, Stylus Studio uses the template that appears
last in the stylesheet.
The template body contains literal results and XSLT instructions. The XSLT processor
instantiates the template body for each node identified by pattern. This means the XSLT
processor copies literal results to the result document and executes the XSLT instructions.
If there is more than one matching template rule, the XSLT processor chooses the
matching template rule with the higher priority. If both have the same priority, the XSLT
processor chooses the one that occurs last in the stylesheet.
For examples and additional information about templates, see Working with Templates
on page 435.
Tip You can create an xsl:template element automatically using the XSLT mapper.

500

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:text
Adds a text node to the result tree.

Format
<xsl:text [disable-output-escaping="yes|no"]>
text_node_contents
</xsl:text>

Description
The XSLT processor reports an error if instantiating text_node_contents results in
anything other than characters.
You can also add text nodes to result documents by embedding the text in elements that
you define.
You can specify the disable-output-escaping attribute of the xsl:text instruction. The
allowed values are yes or no. The default is no. If the value is yes, the text node generated
by instantiating the xsl:text element is output without any escaping. For example:
<xsl:text disable-output-escaping="yes"><</xsl:text>

This instruction generates the single character <.

Examples
The following fragment adds two text nodes by embedding text.
<xsl:template match = "/">
<html>
<head><title>Authors and Their Books</title></head>
<body>
<intro>Books in stock are listed here.</intro>
...
</body>
</html>
</xsl:template>

The next example specifies the xsl:text instruction:

<xsl:text>Following is a list of authors.</xsl:text>

Stylus Studio User Guide

501

Working with XSLT

xsl:transform
The xsl:transform instruction is a synonym for xsl:stylesheet. See xsl:stylesheet on
page 499.

xsl:value-of
Creates a new text node that contains the string value of an expression.

Format
<xsl:value-of select="expression"
[disable-output-escaping="yes|no"]/>

Description
The XSLT processor evaluates expression and converts the result to a string. If the string
is not empty, a text node is created and added to the result. If the string is empty, the
xsl:value-of instruction has no effect.
You can specify the disable-output-escaping attribute of the xsl:value-of instruction.
The allowed values are yes and no. The default is no. If the value is yes, the text node
generated by instantiating the xsl:value-of element is output without any escaping.
Tip You can create an xsl:value-of element automatically using the XSLT mapper.

Example
<xsl:template match = "author">
<p>
<xsl:value-of select = "first-name"/>
<xsl:text> </xsl:text>
<xsl:value-of select = "last-name"/>
</p>
</xsl:template>

This example creates an HTML paragraph from an author element. The author element
has first-name and last-name children. The resulting paragraph contains the value of the
first first-name child element of the current node, followed by a space, followed by the
value of the first last-name child element of the current node.

502

Stylus Studio User Guide

XSLT Instructions Quick Reference

xsl:variable
Declares a variable and binds a value to that variable.

Format
<xsl:variable name="variable_name"
[select = "expression2"]
[expr = "expression3"]>
template_body
</xsl:variable>

Description
The name attribute is required, and it must be a string. The value of the name attribute is a
qualified name.
The value that you bind to a variable can be an object of any of the types that are returned
by expressions. You can specify the value of the variable in several ways:

Specify the select attribute. The value of the select attribute must be an expression.
The XSLT processor evaluates the expression, and the result is the value of the
variable. If you specify the select attribute, you must not specify any contents for the
xsl:variable instruction. In other words, do not specify template_body.

Specify the expr attribute. It is interpreted as an attribute value template. It allows

computation of the value expression.
The expr attribute of the xsl:variable instruction is an extension of the XSLT
standard. If you want to use an XSLT processor other than the Stylus Studio
processor, you cannot specify the expr attribute in your stylesheet.

Specify template_body. The XSLT processor instantiates this template to obtain the
value of the variable. If you specify template_body, you must not specify the select
attribute.

Specify none of the above. In this case, the value of the variable is an empty string.
The difference between the xsl:param and xsl:variable instructions is that
defines a default value while xsl:variable defines a fixed value.

xsl:param

For any use of the xsl:variable element, there is a region of the stylesheet tree within
which the binding is visible. This region includes the siblings that follow the
xsl:variable instruction together with their descendants. Within this region, any binding
of the variable that is visible on the xsl:variable element itself is hidden. Thus, only the
innermost binding of a variable is visible. The set of variable bindings in scope for an

Stylus Studio User Guide

503

Working with XSLT

expression consists of those bindings that are visible at the point in the stylesheet where
the expression occurs.
The xsl:variable instruction can be a top-level element. If it is, it declares a global
variable that is visible to the entire stylesheet. When the XSLT processor evaluates the
select or expr attribute in a top-level xsl:variable instruction, the current node is the root
node of the document. The xsl:variable instruction is also allowed anywhere in a
template that an XSLT instruction is allowed.

xsl:when
See xsl:choose on page 474.

xsl:with-param
Passes a parameter value to a template.

Format
<xsl:with-param name = "parameter_name"
[select = "expression1]"
</xsl:with-param>

Description
The xsl:with-param instruction passes a parameter value to a template. If the template has
no matching xsl:param declaration, the XSLT processor ignores the parameter. The value
of parameter_name is a qualified name.
The name attribute is required, and it must be a string. The value of the name attribute is a
qualified name.
The value that you pass to a template can be an object of any of the types that are returned
by expressions. You can specify the value of the parameter in several ways:

Specify the select attribute. The value of the select attribute must be an expression.
The XSLT processor evaluates the expression, and the result is the value of the
parameter. If you specify the select attribute, you must not specify any contents for
the xsl:with-param instruction. In other words, do not specify parameter_value.

Specify the expr attribute. It is interpreted as an attribute value template. It allows

computation of the value expression.

504

Stylus Studio User Guide

XSLT Instructions Quick Reference

The

Specify parameter_value. If you specify parameter_value, you must not specify the
select or expr attribute.
Specify none of the above. In this case, the value of the parameter is an empty string.
xsl:with-param element

must be a child of xsl:apply-templates or xsl:call-

template.

You can specify the xsl:with-param instruction in

template instructions.

xsl:call-template and xsl:apply-

Example
Suppose you specify the following parameter for a template:
<xsl:template name="Appendix">
<xsl:param name = "heading"> 1. </xsl-param>
...
</xsl:template>

You can pass another value for this variable as follows:

<xsl:call-template name = "Appendix">
<xsl:with-param name = "heading"> A. </xsl:with-param>
</xsl:call-template>

Stylus Studio User Guide

505

Working with XSLT

506

Stylus Studio User Guide

Chapter 6

Creating XSLT Using the XSLT Mapper

The XSLT Mapper is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
In addition to writing XSLT manually in the XSLT text editor, Stylus Studio provides a
graphical tool, the XSLT mapper, that allows you quickly compose XSLT without writing
any code. This chapter describes the XSLT mapper, how to use it, and its relationship to
the XSLT displayed on the XSLT Source tab.
For a brief introduction to the mechanics of using the XSLT mapper and some of its
features, see Using the XSLT Mapper Getting Started on page 44.
This chapter covers the following topics:

Overview of the XSLT Mapper on page 508

Source Documents on page 516

Target Structures on page 523

Mapping Source and Target Document Nodes on page 526

Working with XSLT Instructions in XSLT Mapper on page 528

Processing Source Nodes on page 534

Creating and Working with Templates on page 541

Creating an XSLT Scenario on page 543

Stylus Studio User Guide

507

Creating XSLT Using the XSLT Mapper

Overview of the XSLT Mapper

The XSLT mapper helps you compose XSLT that aggregates data from one or more
source documents, regardless of their origin or XML. For example, an inventory
application might use information from multiple vendors, each of whom organizes
invoices in a different way. You can use the XSLT mapper to identify source documents,
map the relevant nodes from each to a target document, and in doing that define any
required XSLT instructions, XPath or Java functions, and logical operators graphically.
To use the XSLT mapper to create an XSLT stylesheet, you start by specifying one or
more source documents and one target document.

Figure 252. Example of XSLT Mapper

The Mapper tab consists of these areas:

Source document pane, in which you add one or more source documents.

Target structure pane, in which you specify the structure of the result you want the
XSLT to return.

Mapper canvas, on which you can define conditions, functions, and operations for
source document nodes to filter return values that are then mapped to the target node.

508

Stylus Studio User Guide

Overview of the XSLT Mapper

Source code pane (not shown in Figure 252). The source code pane allows you to
view the source code while using the mapper. This is a great way to see how changes
to the mapper affect the source, without the need to switch to the XSLT Source tab.
Of course, the XSLT Source tab is available if you prefer working with the source
using a full-page view. All views Mapper tab, XSLT Source tab, and the source pane
are synchronized. When displayed, the source pane spans the width of the XSLT
editor.

As you link elements and define XSLT instruction and function blocks in the mapper,
Stylus Studio composes XSLT for you, which is visible (and editable) any time you click
the XSLT editors XSLT Source tab. When you have finished mapping, you can apply the
stylesheet to XML documents that have the same schema as the source document. The
result document also has the same schema as the destination document.
As with the XSLT Source tab, you can preview XSLT results from the Mapper tab by
clicking the Preview Result button ( ). Debugging, however, can be performed from the
XSLT Source tab only.
This section covers the following topics:

Example on page 509

Graphical Support for Common XSLT Instructions and Expressions on page 510

Setting Options for the XSLT Mapper on page 511

Simplifying the Mapper Canvas Display on page 512

Exporting Mappings on page 514

Searching Document Panes on page 515

Ensuring That Stylesheets Output Valid XML on page 515

Example
Suppose you open the XML mapper and select books.xml as the source document and
catalog.xml as the target document. You then map elements in the books.xml document
or structure to elements in the catalog.xml document or structure. The result is a
stylesheet that you can apply to books.xml and to other files that have a structure similar
to that of books.xml. When you apply this stylesheet, the result is an XML document
whose structure is consistent with that of catalog.xml.
Now suppose you want to apply a stylesheet to catalog.xml and output an XML file that
has a structure similar to books.xml. To do this, you must use the XSLT mapper to create
a second stylesheet. This time, catalog.xml is the source document and books.xml is the

Stylus Studio User Guide

509

Creating XSLT Using the XSLT Mapper

destination document. The result of this mapping is a stylesheet that you can apply to
documents that have a structure similar to that of catalog.xml.

Graphical Support for Common XSLT Instructions and

Expressions
The XSLT mapper has graphical support for

XSLT instructions

XPath functions

Logical operators

Java functions
Note The availability of specific XSLT functions is determined by the version of XSLT

specified in the stylesheet. XSLT 2.0 has a much more extensive set of built-in functions
than XSLT 1.0.
Using special symbols, called blocks, you can quickly and easily create complex XSLT
without writing any code, as shown in Figure 253:

Figure 253. XSLT Operation, Function, and Logical Operator Blocks

Blocks can be created

Automatically, when you link one node to another. For example, if you link repeating
elements in the source and target documents, Stylus Studio automatically creates an
xsl:for-each instruction block in the mapper.

510

Stylus Studio User Guide

Overview of the XSLT Mapper

Manually, by selecting the instruction or expression you want to create from the
shortcut menu on the mapper canvas (right click on the mapper canvas to display this
menu).
By reverse-engineering the XSLT that you write on the XSLT Source tab when you
click the Mapper tab, XSLT that can be represented graphically is displayed on the
mapper canvas.

See Working with XSLT Instructions in XSLT Mapper and Processing Source Nodes to
learn more about working with blocks in the XSLT mapper.

Setting Options for the XSLT Mapper

There are a few options you can set that affect the XSLT stylesheets generated by the
XSLT mapper. To display the Options dialog box, in the Stylus Studio tool bar, select
Tools > Options.
Under Module Settings > XSLT Editor, click Mapper. The mapper has an option that
determines whether Stylus Studio creates empty elements for unlinked nodes when the
associated schema specifies that the elements are required. You might want to select this
option to help ensure that your XSLT generates valid XML by ensuring that all required
elements are accounted for.
Tip A red check appears on the symbol for required nodes in the target document tree

displayed in the structure pane.

Among other options under the XSLT Editor heading, consider clicking XSLT Settings and
specifying whether or not you want Stylus Studio to save scenario metainformation in the
stylesheet. Scenario metainformation includes anything specified in the Scenario
Properties dialog box source and output URLs, parameter values, post-processing
options, and so on.
Note If you select this option, Stylus Studio also saves mapper metainformation in the

stylesheet; mapper metainformation includes the names of source files, node mapping
information, and so on.
If you choose not to save scenario metainformation in the stylesheet, and if the stylesheet
belongs to a project, Stylus Studio saves mapper metainformation in the project. If the
stylesheet does not belong to a project, and you choose not to save metainformation in the
stylesheet, mapping metainformation is not saved.

Stylus Studio User Guide

511

Creating XSLT Using the XSLT Mapper

Simplifying the Mapper Canvas Display

By default, the XSLT Mapper displays all links between source and target document
nodes, regardless of whether or not the node associated with a link is currently visible in
the Source Document or Target Document pane. Further, as your XSLT code becomes
more complex, the mapper canvas can become dense with graphical representations of the
functions defined in the code and the links that represent them. Consider this example of
sample2Video.xsl, one of the sample XSLT stylesheets in the Examples project installed
with Stylus Studio.

Figure 254. Mapper Shows Links to All Nodes, Visible or Not

512

Stylus Studio User Guide

Overview of the XSLT Mapper

You can hide links for nodes that are not currently visible in the Source Document or
Target Document pane by clicking the Hide Links for Nodes that are not Visible button,
as shown in Figure 255:

Figure 255. Simply the Mapper by Hiding Links

When you use this feature, Stylus Studio displays

Links in the Mapper canvas only if both nodes are currently visible in the document
panes

Green arrows (like the ones shown in Figure 256) in the document panes if only one
of two linked nodes is currently visible.

Figure 256. Arrows Identify Partially Available Links

Stylus Studio User Guide

513

Creating XSLT Using the XSLT Mapper

Other Mapper Display Features

In addition to displaying links for only those nodes that are visible in both document
panes, you can use the document node shortcut menu (right-click on a node in a document
pane) to

Show links to a specific node

Hide links to a specific node

Show/hide all links

Exporting Mappings
You can export a mapping source and target document trees and Mapper canvas contents
as an image file. The default image format is JPEG (.jpg), but you can choose from
other popular image file formats such as .bmp and .tiff.
The exported image reflects the document trees at the time you export the image if you
have collapsed a node in Stylus Studio, for example, that node is also collapsed in the
exported image. However, the exported image includes the entire document tree and
Mapper canvas, not just what is currently visible on the Mapper tab.
By default, all source-target document links are displayed. However, if you have chosen
to hide or show links for only certain nodes, the exported image reflects that choice and
displays only the links for the nodes as you have specified. See Simplifying the Mapper
Canvas Display on page 512 for more information on hiding and showing links.
To export an XSLT mapping:

514

Optionally, hide links for any nodes in the source or target documents that you do not
want to appear in the exported image.

Select XSLT > Export Mapping as Image from the Stylus Studio menu.
Stylus Studio displays the Save As dialog box.

Specify a URL for the file.

Optionally, change the image type. (The default is JPEG; .bmp and .tiff are also
available.)

Click Save.

Stylus Studio User Guide

Overview of the XSLT Mapper

Searching Document Panes

You can search document panes using the Find dialog box.

Figure 257. You Can Search Document Panes

You can restrict your search to elements and/or attributes, and you can even search using
regular expressions to define your match pattern.
To display the Find dialog box:
1.

Right-click in the document pane.

Select Find from the shortcut menu.

Ensuring That Stylesheets Output Valid XML

Stylus Studio cannot automatically generate a stylesheet that will always generate a valid
XML document. As defined by the W3C, an XML document is considered to be valid if
it conforms to the DTD with which it is associated.
For example, consider a stylesheet that has required attributes. In order to specify
meaningful values for them, you need to have insight as to the semantics of the operation
the stylesheet is performing, and it is difficult for any application to infer this type of
information. Always check to see that the stylesheets you create using the XSLT mapper
generate valid input.

Steps for Mapping XML to XML

To create an XSLT stylesheet using the XSLT mapper:
1.

From the Stylus Studio menu bar, select File > New > XSLT: Mapper.
Stylus Studio displays the XSLT editor with the Mapper tab selected.

Select one or more source documents and a target document.

Stylus Studio User Guide

515

Creating XSLT Using the XSLT Mapper

In both the source and the target panes, click the root element and then press the
asterisk key (*) in the numeric key pad to expand the schema tree.

Map nodes in the source documents to nodes in the target document, define XSLT
instructions and functions, and create named and matched templates using the
mappers graphical tools.
Consider working through the source document in document order as you map source
and target elements.

Tip

Check the XSLT Source view from time to time. This allows you to confirm that the
stylesheet is doing what you expect it to do (and it is also a good way to teach yourself
XSLT). Changes you make directly to the source are reflected on the Mapper tab, and
vice versa.

Each of these steps is described in greater detail in the following sections.

Source Documents
In Stylus Studio, a source document in the XSLT mapper can be one or more of the
following:

An XML document

An XML Schema (XSD)

A document type definition (DTD)

Zip Archive formatted documents (Microsoft Office Open XML, OpenDocument

Format, and .zip)
The role of a source document is to provide Stylus Studio with a structure that it can use
to compose the XSLT stylesheet, based on how you map individual source document
elements and attributes to nodes in the target structure. Stylus Studio infers the target
structure from the document (XML, XSD, or DTD) you specify and displays this structure
on the Mapper tab.
This section covers the following topics:

Choosing Source Documents

Source Documents and XML Instances

How to Add a Source Document

How to Remove a Source Document

How Source Documents are Displayed

516

Stylus Studio User Guide

Source Documents

For information on using Zip Archive formatted documents as source documents, see
Working with Zip Archive Format Files as Data Sources on page 862.

Choosing Source Documents

You can use one or more source documents to build a stylesheet in the Stylus Studio XSLT
mapper. You might want to select more than one document if you need their elements or
attributes to fully describe the target structure or the desired XSLT result content, or if you
want to aggregate multiple sources in a single document, for example.
If you choose an XSD or DTD document, you must also choose an XML instance
document to associate with it. Stylus Studio uses the instance document associated with
an XSD or DTD source document to generate the XPath document() function in the
finished XSLT. As a result, it is this document that is used to preview XSLT results.
Tip If you want to examine the contents of the XML document specified as the source file in
the scenario, click Open XML From Scenario
, which is at the top of the XML mapper

window. Stylus Studio displays the source document in the XML editor.
See Source Documents and XML Instances to learn more about how Stylus Studio treats
source documents. See Creating an XSLT Scenario to learn more about XSLT scenarios.

Source Documents and XML Instances

As described previously, Stylus Studio uses the source documents you specify to display
a structure you can use to create mappings to the target structure. In addition to the
document structure, Stylus Studio needs document content information in order to
compose a correct XSLT stylesheet. You provide this information by associating a XML
instance to each source document you specify.

Types of associations
Source documents can have one of three associations, each of which has implications for
the XPath expressions written by Stylus Studio, which uses these documents when it
composes the XSLT stylesheet. A source document can be associated with

Stylus Studio User Guide

517

Creating XSLT Using the XSLT Mapper

Itself. That is, the document represented by structure displayed on the Mapper tab and
the XML instance are one in the same. In this situation, Stylus Studio generates the
document() function in the XSLT stylesheet. For example:
document("file://c:\Program Files\Stylus
Studio\examples\simpleMappings\catalog.xml")/books/book

The previous example shows the XSLT that results when an XML document is used
to specify the source structure. This is not possible with XSD or DTD source
documents.

Note

The XML document specified in the XSLT scenario. Only one source document can
be associated with the XSLT scenario. In this situation, Stylus Studio does not
generate the document() function in the XSLT stylesheet. In this situation, the
document() function is not necessary because Stylus Studio uses the XSLT input
document specified in the Scenario Properties dialog box.
By default, Stylus Studio uses the first XML document you add to the XSLT mapper
as the source XML for the XSLT scenario, as shown here:

Figure 258. XSLT Scenario

518

Stylus Studio User Guide

Source Documents

The document specified in the Source XML URL field on the Scenario Properties
dialog box is the document to which the XSLT is applied when you preview the
XSLT. You can select this association for another XML document if you choose, but
only one source document may have this association.
If you specify an XML document as the first source document, Stylus Studio creates
a scenario for you automatically, using that document as the scenarios source XML.
If you specify some other type of document (XSD or DTD), Stylus Studio prompts
you to create a scenario and to specify an XML document as the source when you
preview the XSLT. See Creating an XSLT Scenario.

Note

Some other XML instance. A XSD or DTD document used as a mapper source
document must always be associated with an XML instance. In this situation, Stylus
Studio generates the document() function in the XSLT stylesheet when accessing
nodes of the document structure.

Source document icons

Stylus Studio uses different document icons to indicate how a source document structure
is related to corresponding XML document content.
Table 63. Source Document Icons
Icon

Meaning
The source document is associated with itself. This is the default for
most XML documents (and XML documents only).
The source document is associated with default XML document
specified in the Source XML URL field in the XSLT scenario. This
is the case with the first XML document you add to XSLT mapper, but
you can change this association manually if you choose. See How to
change a source document association.
The source document is associated with a separate XML document
instance. XSD and DTD source documents are always associated with
an XML instance.

Stylus Studio User Guide

519

Creating XSLT Using the XSLT Mapper

How to change a source document association

To change a source document association:
1.

Click the Mapper tab if necessary.

Right click the source document whose association you want to change.
The source document shortcut menu appears.

Click Associate With, and then select the document you want to associate with the
source document.

How to Add a Source Document

To add a source document to XSLT mapper:
1.

Click the Mapper tab if necessary.

Click the Add Source Document button at the top left of the Mapper tab.
The Open dialog box appears.

Select the document you want to use as the source document to map to the target
document.

Click Open.
If you selected an XML document in Step 3, the document appears in the source
document pane of the Mapper tab. Go to Step 5.
If you selected an XSD or DTD document, Stylus Studio displays the Choose Root
Element dialog box.

Figure 259. Choose Root Element Dialog Box

520

Stylus Studio User Guide

Source Documents

You use the Associate With field to associate the XSD or DTD with an XML instance.
The Associate With field appears only when you add a second document to the XSLT
mapper source and that document is an XSD or DTD. You use it to specify the XML
instance that you want to associate with the XSD or DTD. This field does not appear
if the XSD or DTD is the first source document you add to the XSLT mapper Stylus
Studio uses the XML Source document specified in the Scenario Properties dialog
box as the XML instance in this case.

Note

Select the element from the XSD or DTD document that you want to use as the
root element. The Choose root element drop-down list displays elements defined
in the document you selected in Step 3.

Use the Browse (

) button to specify the XML instance to which you want to
associate the document you have chosen as your structure. The root element of
the XML document you select should be the same as the element you selected as
the root element from the XSD or DTD document.

Click OK.
The document appears in the source document pane of the Mapper tab. Go to
Step 5.

To add another source document, return to Step 2.

How to Remove a Source Document

Note A source document cannot be removed from XSLT mapper if it is mapped to the target

structure. See Removing Source-Target Maps.

To remove a source document from the XSLT mapper:
1.

Click the Mapper tab if necessary.

Remove any maps from the source document to the target schema. (See Removing
Source-Target Maps if you need help with this step.)

Right click on the source document.

The source document shortcut menu appears.

Select Remove Schema.

Stylus Studio User Guide

521

Creating XSLT Using the XSLT Mapper

How Source Documents are Displayed

A source document is represented in the mapper using a document icon; its name is
displayed using a different color to help distinguish the document from elements and
attributes. The document icon is modified based on the source documents association
with other documents. See Source Documents and XML Instances for more information
on this topic.
By default, only the file name itself is displayed; if you want, you can display the
documents full path by selecting Show Full Path on the documents shortcut menu.
(Right-click on the document name to display the shortcut menu.)

Figure 260. Source Document Display

Source documents are displayed using the tree view; you can use your standard
keyboards *, +, and - number pad keys to expand and collapse selected documents.

Document structure symbols

Stylus Studio uses the following symbols to represent nodes in both source and target
document structures
Table 64. Document Structure Symbols
Symbol

Meaning
Repeating element
Element
Attribute

See Source document icons to learn about the different ways source document icons are
depicted.

522

Stylus Studio User Guide

Target Structures

Getting source document details

If you want details about the source document that are not available in tree view, you can
open the document by selecting Open from the documents shortcut menu. When you
open a document this way, Stylus Studio displays it in the XML editor. XSD and DTD
documents are displayed on the XML editors Schema tab.

Target Structures
There are two ways to specify an XSLT target structure:

You can build a structure from scratch, starting with the root element and defining
other elements and attributes as needed. Nodes for target structures you define are
displayed in red.
This section covers the following topics:

Using an Existing Document

Building a Target Structure

Modifying the Target Structure

Using an Existing Document

To use an existing document to provide the XSLT target structure:
1.

Click the Mapper tab if necessary.

Click the Set Target Document button at the top left of the Mapper tab.
The Open dialog box appears.

Select the document you want to use to provide the target structure for defining the
mapping (XML, XSD, or DTD).

Click Open.
The structure of the document you select appears in the target document pane of the
Mapper tab.

Stylus Studio User Guide

523

Creating XSLT Using the XSLT Mapper

Building a Target Structure

To build a target structure from scratch, you first create a root element, and then define
child elements and attributes as needed.
How to create a root element
To create a root element:
1.

Click the Mapper tab if necessary.

Right click the area underneath the Set Target Document button.
The target document shortcut menu appears.

Select Create Root Element.

The Name dialog box appears.

Figure 261. Name Dialog Box

Type a name for the root element and click OK.

The root element you specified appears in the target document pane of the Mapper tab.

How to create elements and attributes

You can create elements and attributes in a new or existing target structure.
To create elements and attributes:

524

Click the Mapper tab if necessary.

Select the attribute or element to which you want to add a child element or attribute.
If you have just created a root element, select the root element.

Right click the area underneath the Set Target Document button.
The target document shortcut menu appears.

Choose one of the following:

Add Attribute

Add Child Element

Stylus Studio User Guide

Target Structures

Insert Element After (This choice is not applicable to the root element; it creates

the element as a sibling of the selected element.)

The Name dialog box appears.

Figure 262. Name Dialog Box

Type a name for the node and click OK.

The node you specified is added to the target structure in the Mapper tab.

Modifying the Target Structure

This section describes the techniques you can use to modify the structure and content of
an XSLT mapper target structure. It covers the following topics:

Adding a Node

Removing a Node

Adding a Node
See How to create elements and attributes.

Removing a Node
Note Before you can remove a node, you must delete any links to that node. See Removing

Source-Target Maps.
To remove a node from the target structure:
1.

Remove any links to the node you want to remove from the target structure. See
Removing Source-Target Maps if you need help with this step.

Select the node and press the Delete key.

Alternative: Right-click the node and select Remove Node from the shortcut menu.

Stylus Studio User Guide

525

Creating XSLT Using the XSLT Mapper

Mapping Source and Target Document Nodes

You map a source document node to a target structure node using drag and drop to create
a link between the two nodes. Stylus Studio composes XSLT based on these maps.
This section covers the following topics:

Preserving Mapper Layout

Left and Right Mouse Buttons Explained

How to Map Nodes

Removing Source-Target Maps

Tip You can also map source document nodes to XSLT instruction blocks, XPath and Java

function blocks, and logical operators. See Working with XSLT Instructions in XSLT
Mapper and Processing Source Nodes.

Preserving Mapper Layout

As you add function blocks to the XSLT mapper, Stylus Studio places them in the center
of the mapper canvas. You can change the default placement of function blocks by
dragging and drag and dropping them where you like. Stylus Studio preserves the
placement you select within and across sessions (as you toggle between the mapper and
the XSLT Source tab, for example).
As you use the splitter in the XSLT mapper to widen the source and target document
panes, the size of the mapper canvas is reduced. The Fit in Mapper Canvas button (
),
located at the top of the XSLT mapper, redraws the diagram in whatever space is currently
available to the mapper canvas. This feature is also available from the mapper short-cut
menu (right-click anywhere on the mapper canvas to display the short-cut menu).

Left and Right Mouse Buttons Explained

You can use either the left or the right mouse button to perform the drag and drop
operation used to create source-target mappings in the XSLT mapper.
If you use the left mouse button to perform the drag operation, the link always maps the
source node to the target node without making any changes to the target structure. If you

526

Stylus Studio User Guide

Mapping Source and Target Document Nodes

use the right mouse button, Stylus Studio displays a shortcut menu that provides you with
alternatives for modifying the target structure.

Figure 263. Shortcut Menu for Target Document Operations

Using this menu, you can

Map a source document node to an existing target structure node this menu choice,
Map to This Node, is the same as creating the link using the left mouse button.

Add a source document node (element or attribute) as an attribute of the target

structure node you select and map the two nodes.

Add a source document node as a child element of the target structure node you select
and map the two nodes.

Add a source document node as a sibling of the target structure node you select and
map the two nodes.

Copy the entire source document node its structure and its content to the target
structure and map it.

How to Map Nodes

To map nodes:
1.

Using either the left or right mouse button, drag the source document element or
attribute to the appropriate node on the target structure.
If you need help with this step, see Left and Right Mouse Buttons Explained.

Tip
2.

When the pointer is on the appropriate target element, release the mouse button to
complete the link.

Stylus Studio User Guide

527

Creating XSLT Using the XSLT Mapper

Stylus Studio draws a link between the source and target nodes you chose is Step 1.
If you linked two repeating elements, Stylus Studio displays a symbol representing
the xsl:for-each instruction. See Working with XSLT Instructions in XSLT Mapper
on page 528.

Removing Source-Target Maps

To remove a map from a source document node to a target element node:
1.

Select the line that represents the map you want to delete.
Select the portion of the line that is drawn on the XSLT mapper canvas.

Tip
2.

Press the Delete key.

Alternative: Select Delete from the line shortcut menu (right click on the line to
display the shortcut menu).

Working with XSLT Instructions in XSLT Mapper

As described in Graphical Support for Common XSLT Instructions and Expressions on
page 510, you can create and work with XSLT instructions in the XSLT mapper using
symbols called blocks. Each supported instruction is represented by a different block
(symbols distinguish one block from another), and you complete the instructions
definition graphically, using drag and drop.
This section identifies the XSLT instructions supported by the mapper, their features, and
how to use them. It covers the following topics:

What XSLT Instructions Are Represented Graphically on page 529

Instruction Block Ports on page 529

Understanding Input Ports on page 530

The Flow Port on page 531

Adding an Instruction Block to the XSLT Mapper on page 532

xsl:if and xsl:choose on page 533

528

Stylus Studio User Guide

Working with XSLT Instructions in XSLT Mapper

What XSLT Instructions Are Represented Graphically

The XSLT mapper represents the following XSLT instructions:
Table 65. XSLT Instruction Blocks in XSLT Mapper
XSLT Instruction

Representation in the XSLT Mapper

xsl:value-of
xsl:for-each
xsl:if
xsl:choose
xsl:apply-templates
xsl:call-template

Note You can create any XSLT instruction in the XSLT source, but only the instructions in

Table 65 are represented graphically in the XSLT mapper. XSLT instructions that are not
supported by the mapper have no graphical representation.

Instruction Block Ports

All XSLT instruction blocks have at least three connectors, called ports. Look at the
xsl:value-of instruction block shown in Figure 264.

Figure 264. Example of an XSLT xsl:value-of Instruction Block

You use these ports to link source and target nodes, to perform processing on source
document nodes, and to provide flow control as the result of a xsl:choose or xsl:if.
Ports are also part of XPath and Java function blocks, logical operator blocks, and text
blocks. (See Processing Source Nodes on page 534 for information on working with these
types of blocks.)

Stylus Studio User Guide

529

Creating XSLT Using the XSLT Mapper

Specifying Values for Ports

After you have added an instruction block to the XSLT mapper, you need to complete its
definition. You do this by linking the instruction blocks input, output, and, optionally,
flow ports to nodes and other blocks in the mapper.
The way you specify values for ports varies slightly between input ports and flow and
output ports, but, generally speaking, you can either

Dragging a link from the port to a target document node or to the flow port on another
instruction block.

Double-click the port and typing a value (a string or an XPath expression, for
example) in the Value dialog box.
Tip To see the XSLT that is being generated based on the XSLT instruction you are creating,
right click the instruction and select Go To Source from the shortcut menu.

Understanding Input Ports

Stylus Studio interprets input ports differently for different XSLT instructions, as shown
in Table 66:
Table 66. XSLT Instruction Blocks in XSLT Mapper
XSLT Instruction

Meaning of Input Port

xsl:value-of

Used to define the value of the select attribute. For example:

<xsl:value-of select=Owen>

xsl:for-each

Used to define the XPath expression for the select attribute. For
example:
<xsl:for-each select=books/book>

xsl:if

Used to define the value of the test attribute. For example:

<xsl:if test=authors/author= 'Henry>

See xsl:if and xsl:choose on page 533 to learn more about when to
use this instruction.
xsl:choose

Used to define the value of the test attribute of the nested

xsl:when element. For example:
<xsl:when test="contains(authors/author,'Marchese')">

See xsl:if and xsl:choose on page 533 to learn more about when to
use this instruction.

530

Stylus Studio User Guide

Working with XSLT Instructions in XSLT Mapper

Table 66. XSLT Instruction Blocks in XSLT Mapper
XSLT Instruction

Meaning of Input Port

xsl:apply-templates

Used to define the value of the select attribute. For example:

<xsl:apply-templates select="subject"/>

xsl:call-template

Used to define the value of the name attribute. For example:

<xsl:call-template name="newAuthorsTemplate"/>

Specifying Values for Input Ports

You can specify values for input ports by:

Dragging a link from a source document node or from the output port of another block
(like that of an XPath function or If block, for example).

Double-clicking the port and typing a value (a string or an XPath expression, for
example) in the Value dialog box.
When you mouse over an input port, Stylus Studio displays the value associated with
that port.

Tip

Red Input Ports

If an xsl: instructions attribute takes a literal or string value (such as xsl:value-of
select="'Recommended'"/, for example) and a value has been provided for the attribute,
Stylus Studio fills the input port associated with that attribute with a deep red to indicate
that a value has been specified.

The Flow Port

Output ports for any of the following xsl: instructions can be linked to the flow port of
an instruction block:

xsl:if

The xsl:when element of xsl:choose

xsl:for-each

You might decide you want a particular xsl:for-each instruction executed only after
performing a certain function, for example.

Stylus Studio User Guide

531

Creating XSLT Using the XSLT Mapper

Adding an Instruction Block to the XSLT Mapper

Tip If you enter an XSLT instruction in the XSLT source and that instruction can be

graphically represented in the mapper, the instruction, including appropriate links to

source and target nodes, appears the next time you display the Mapper tab.
To add an instruction block to the XSLT mapper
1.

Right click on the mapper canvas.

The shortcut menu appears.

Select XSLT Instructions from the shortcut menu.

The XSLT Instructions submenu appears.

Select the instruction you want to add to your XSLT.

The block for the instruction you selected appears in the mapper canvas.

Provide a value for the input port(s). See Specifying Values for Ports on page 530 if
you need help with this step.

Link the output port(s).

Optionally, link the flow port.

Notes About Creating Instruction Blocks

Be aware of the following when working with XSLT instruction blocks in the XSLT
mapper:

To simplify the mappers appearance, Stylus Studio sometimes removes blocks from
the mapper canvas and replaces them with a simple link. For example, imagine
creating an xsl:value-of instruction block and linking source and target document
nodes. Stylus Studio displays the instruction block, but if you leave the Mapper and
later return to it, the block symbol for the xsl:value-of instruction is replaced by a
link with a small circle at its center, link the one shown in Figure 265.

Figure 265. xsl:value-of in XSLT Mapper

If you mouse over the circle, Stylus Studio displays the XSLT represented by the link
(xsl:value-of select=/books/book/@pubdate/, for example).
This behavior also exists for text blocks created in the mapper that are not also linked
to other blocks in the mapper. See Setting a Text Value on page 538.

532

Stylus Studio User Guide

Working with XSLT Instructions in XSLT Mapper

If you type an XSLT instruction in the XSLT source that is not represented by the
XSLT mapper, no representation of that XSLT instruction is displayed on the Mapper
tab. The code remains as part of the XSLT source, however.
If you start creating an XSLT instruction in the mapper but do not completely define
it (say you specify only the input port for an xsl:for-each instruction, for example),
it is not represented in the XSLT source, and it is removed from the XSLT mapper if
you leave the Mapper tab and then return to it.

xsl:if and xsl:choose

The xsl:if instruction cannot express an else condition. It has a single input port, and a
single output port, as shown in Figure 266.

Figure 266. xsl:if Instruction Block

Once fully defined, the xsl:if block generates code like the following:
<Review>
<xsl:if test="authors/author= 'Minollo'">
<xsl:value-of select="'Recommended'"/>
</xsl:if>
<xsl:if test="contains(authors/author,'Pedruzzi')">
<xsl:value-of select="'A best buy'"/>
</xsl:if>
</Review>

If you need to express an else condition, use the xsl:choose instruction block. This
instruction block has two output ports by default, one for the xsl:when test= attribute, and
one for the one xsl:otherwise element.

Figure 267. xsl:choose Instruction Block

Stylus Studio User Guide

533

Creating XSLT Using the XSLT Mapper

The xsl:choose instruction block generates code like the following:

If you need to define more than one xsl:when test= attribute, use the xsl:choose shortcut
menu (right click) and select Add When Port.
Note Stylus Studio generates the xsl:otherwise element by default for all xsl:choose

instructions.

Processing Source Nodes

You can use any of the following to combine nodes or process nodes in the source
document and map the result to a node in the target document:

XPath Function Blocks on page 534

Logical Operators on page 537

Setting a Text Value on page 538

Defining Java Functions in the XSLT Mapper on page 540

XPath Function Blocks

Stylus Studio supports standard XPath functions defined by the W3C. This section
describes how to work with function blocks in XSLT mapper and covers the following
topics:

Parts of a Function Block

Types of Function Blocks

Creating a Function Block

Deleting a Function Block

534

Stylus Studio User Guide

Processing Source Nodes

Parts of a Function Block

Function blocks are drawn as a purple block with an italic f at its center, and connectors,
called ports, placed along the blocks border. Input ports (one or more depending on the
function) on the left, the flow port at the top, and the output port on the right:

Figure 268. Function Block

Input ports
Input ports are on the left side of the function block. The number and definition of input
ports varies from function to function. To specify a value for an input port, you can

Drag a source document element or attribute to the port and release it

Double-click the port and enter the function in the Value dialog box
Flow port
Flow ports on the top of function blocks are generally used only when a function is used
in a direct link between a source and target node.
Output port
The output port is on the right side of the function block. You use the output port to map
the function result directly to a target structure element or attribute, or to an IF, condition,
or another function block.

Types of Function Blocks

The XPath functions available in XSLT mapper include the following:

boolean

ceiling

concat

contains

count

floor

format

Stylus Studio User Guide

535

Creating XSLT Using the XSLT Mapper

last

local-name

mod

name

normalize-space

number

position

round

starts-with

string

string-length

substring

substring-after

substring-before

sum

translate

XPath Mathematical Functions

In order to simplify the graphical presentation in the XSLT mapper, the following XPath
mathematical functions are not graphically represented:

add

div

multiply

subtract

You can easily express these functions by typing them in the Value dialog box displayed
when you double-click an input port.

536

Stylus Studio User Guide

Processing Source Nodes

Creating a Function Block

To create a function block:
1.

In the XSLT editor, in the Mapper tab, right-click mapper canvas.

In the shortcut menu that appears, click XPath Functions and slide to the submenu.

Click the function you want to use. Stylus Studio displays a function block for the
function you selected.

Deleting a Function Block

To delete a function block:

Select it and press the Delete key.

If the function block is part of a link, deleting the function block also deletes the link.

Logical Operators
The Stylus Studio XSLT mapper allows you to graphically define the following types of
conditions:

Equal (=)

Less than (<)

Greater than (>)

Less than or equal to (<=)

Greater than or equal to (>=)

and (&)

or (||)
All condition blocks have two input ports and a single output port, as shown in this
example of a greater than block.

Figure 269. Greater Than Block

You can map the return port to a target structure element or attribute, or to the input port
on an XSLT instruction, XPath function, or another condition block.

Stylus Studio User Guide

537

Creating XSLT Using the XSLT Mapper

Setting a Text Value

You can set text values for target structure elements and attributes. You might want to do
this if you are composing a mapping whose target structure contains an element or
attribute that requires a fixed value, instead of using a value gathered from an input XML
document.

Example
Here is the XSLT code Stylus Studio generates for the Title element when a text value is
specified for it:
<Book>
<Title>Confederacy of Dunces</Title>
</Book>

Stylus Studio displays a red letter T for nodes for which you define a text value:

Figure 270. Symbols for Nodes With Text Values

There are two ways to set a text value:

On the mapper canvas

On the target node

How to Set a Text Value on the Mapper Canvas

To set a text value on the mapper canvas:
1.

Right-click on the mapper canvas.

The shortcut menu appears.

Select Text Block from the shortcut menu.

The text block appears on the mapper.

Figure 271. Text Block

538

Stylus Studio User Guide

Processing Source Nodes

Double-click the text block to display the Value dialog box.

Figure 272. Value Dialog Box

You can also display the Value dialog box by selecting Properties from the text block
shortcut menu (right click).

Tip

Type a value and click OK.

Drag a link from the text blocks output port to the target node to which you want to
assign the text value.

Note Unless the text block is linked to another block (such as a logical operator or an XPath

function), Stylus Studio removes it from the mapper canvas if you leave and then return
to the Mapper tab. In this case, a red T is displayed next to the target nodes name.

How to Set a Text Value on the Target Node

To set a text value on a target node:
1.

Right-click the node for which you want to set the text value.
The shortcut menu appears.

Select Set Text Value from the shortcut menu.

The Value dialog box appears.

Figure 273. Value Dialog Box

Type the string you want to use as the text value and click OK.

Stylus Studio User Guide

539

Creating XSLT Using the XSLT Mapper

Defining Java Functions in the XSLT Mapper

You can write your own Java functions and use them when you map nodes.
To define your own functions:
1.

Ensure that a Java virtual machine is running locally.

Create the class file for your function. See About Adding Java Class Files on
page 540 for more help with this step.

Display the Mapper tab in the XSLT editor, if necessary.

Right-click the mapper canvas.

In the pop-up menu that appears, select Java Functions > Register Java Extension
Class.

In the Java Class Browser dialog box that appears, navigate to and select the Java
class that provides your function.

Click OK in the Java Class Browser dialog box.

Now when you select Java Functions from the mapper short-cut menu, the list of
functions includes the function you registered.

About Adding Java Class Files

The class file must be in your CLASSPATH environment variable or in the Stylus Studio
ClassPath. To add it to the Stylus Studio ClassPath, select Tools > Options from the
Stylus Studio menu bar. In the Options dialog box, expand Application Settings and click
Java Virtual Machine.

540

Stylus Studio User Guide

Creating and Working with Templates

A stylesheet can contain more than one template. This section describes Stylus Studios
features for creating and working with named and matched templates in XSLT mapper.

What Happens When You Create a Template

When you create a template, Stylus Studio switches the XSLT mapper to the new
template. The attributes identifying the template you are currently viewing are displayed
in the template drop-down list at the top of the mapper canvas.

Figure 274. Drop-down List Shows Current Template

You can change the template view at any time, by selecting the template from the dropdown list, as shown in Figure 275.

Figure 275. Display Different Templates Using the Drop-down List

Tip At any time, the mapper shows only the links that have been defined for the current

template.

Stylus Studio User Guide

541

Creating XSLT Using the XSLT Mapper

How to Create a Named or Matched Template

To create a named or matched template:
1.

Right-click the XSLT mapper canvas.

Select Create Template > Named Template or > Matched Template from the shortcut
menu.
Stylus Studio displays the Named Template (or Matched Template) dialog box. (The
Named Template dialog box is shown in Figure 276.)

Figure 276. Named Template Dialog Box

You can use a mode to define the conditions under which a template will be applied
by a stylesheet.

Tip

542

Enter a name and, optionally, a mode.

Optionally, create one or more parameters:

Click the Add button.

The Name column becomes editable.

Type a parameter name and press Enter.

The Default Value field becomes editable.

Type a default value.

If you want to define another parameter, click ADD; otherwise, go to Step 5.

Click OK to finish creating the template.

Stylus Studio User Guide

Creating an XSLT Scenario

An XSLT scenario is a group of settings that Stylus Studio uses to process the XSLT when
you click the Preview Result button (
). Examples of scenario settings include the
XML document to which the XSLT will be applied, whether you want to perform any
post-processing, and the values of any parameters you might have defined. You can create
multiple scenarios that use the same XSLT, and choose different settings for each. This
flexibility can aid the XSLT development process as it enables you to easily test different
applications of the XSLT before you put it online.
Even if you do not explicitly create a scenario, Stylus Studio uses default scenario settings
in order to preview the XSLT. For example, Stylus Studio uses the first source document
you specify as the document to which the XSLT is applied. (If the first source document
is an XSD or DTD, Stylus Studio prompts you to provide an XML document for the
scenario when you preview the XSLT.)
This section covers the following topics:

Overview of Scenario Features

How to Create a Scenario

How to Run a Scenario

How to Clone a Scenario

Overview of Scenario Features

This section describes the main features of XSLT scenarios. It covers the following topics:

XML Source Documents

Global Parameters

XSLT Processors

Performance Metrics Reporting

Result Document Validation

Post-Processing Result Documents

XML Source Documents

The main benefit of the XSLT scenario feature is that it lets you specify the XML
document against which you want to run your XSLT. By default, Stylus Studio uses the
first source document you add using the XSLT mapper as the XML source document for

Stylus Studio User Guide

543

Creating XSLT Using the XSLT Mapper

the scenario. You can specify the XML source document setting on the General tab of the
Scenario Properties dialog box.

Figure 277. General Tab of XSLT Scenario Properties Dialog Box

See Source Documents to learn more about the process of selecting and working with
source documents in XSLT mapper.

Global Parameters
The Parameter Values tab of the Scenario Properties dialog box displays any global
parameters you have defined in the XSLT source and allows you to

Specify an alternate value to use when running the scenario

Indicate whether the value is an XPath expression or a string

For example, imagine the following parameter defined in the XSLT source:
<xsl:param name="my_title" select="'Confederacy of Dunces'"/>

544

Stylus Studio User Guide

Creating an XSLT Scenario

This parameter is displayed on the Parameter Values tab as follows:

Figure 278. Specifying Alternate Values for XSLT Parameters

If you want to specify an alternate parameter value for this scenario, click the Parameter
value to be used when processing entry field. If the alternate value you enter is an XPath
expression, click the associated check box.
By default, values entered in the Paramter value to be used when processing field are
interpreted as strings. However, you can indicate that you want the value to be interpreted
as an XPath expression by selecting the check box in the Parameter value is an XPath
expression (not a string) field. This allows you to enter expressions such as the following:
document("books.xml")/books/book[1]

Tip All global parameters you define for a stylesheet are displayed on the Params/Other tab
of the XSLT Editor. Parameters displayed on the Params/Other tab are read-only.

Stylus Studio User Guide

545

Creating XSLT Using the XSLT Mapper

XSLT Processors
By default, Stylus Studio uses the Saxon processor to process XSLT documents. You can
change the processor on the Processor tab of the Scenario Properties dialog box.

Figure 279. Changing the Default XSLT Processor

You can choose from a number of third-party processors that are bundled with Stylus
Studio, or you can specify your own custom processor.
Note Not all third-party processors, including any custom processors you might specify,

support back-mapping and debugging.

See How to Use a Third-Party Processor on page 441 for more information.

Performance Metrics Reporting

Performance metrics reporting is available only in Stylus Studio XML Enterprise
Suite.
Stylus Studio can generate an HTML report that contains information about how your
XSLT is being processed. This option is off by default, but you can enable it, and choose
options for the report, on the Profiling Options tab.
See Profiling XSLT Stylesheets to learn more about the different ways in which Stylus
Studio can provide you with XSLT performance metrics.
546

Stylus Studio User Guide

Creating an XSLT Scenario

Result Document Validation

You can optionally validate the XML document that results from XSLT processing using
the XML validator you specify. You can use

The Stylus Studio built-in XML validator. If you use the Stylus Studio built-in
validator, you can optionally specify one or more XML Schemas against which you
want the result document to be validated.

Any of the customizable validation engines supported by Stylus Studio, such as the
.NET XML Parser and XSV.
All validation is done before any post-processing that you might have specified.
See Validating Result Documents on page 445.

Post-Processing Result Documents

You can use the Post-process tab to specify any optional processing you want performed
on the XML after it has been transformed by the XSLT. You might want to use FOP to
render XML as PDF, for example.

How to Create a Scenario

To create a scenario:
1.

In the XSLT Editor tool bar, click

.
Alternative: Select Create Scenario from the scenario drop-down list at the top of the
editor window.
Stylus Studio displays the Scenario Properties dialog box.

In the Scenario name: field, type the name of the new scenario.

In the Source XML URL (optional): field, type the name of the XML file to which you
want to apply the XSLT, or click Browse
to navigate to an XML file and select it.
If the first document you added to the XSLT mapper is an XML document, Stylus
Studio uses that document as the XML source for the scenario and displays it in this
field.

Note

In the Output URL field, optionally type or select the name of the result document you
want the XSLT document to generate. If you specify the name of a file that does not
exist, Stylus Studio creates it when you preview the XSLT.

Stylus Studio User Guide

547

Creating XSLT Using the XSLT Mapper

If you want Stylus Studio to Store paths relative to XSLT document path, ensure that
this option is checked.

If you check Preview result in an external application, Stylus Studio displays the result
Internet Explorer. In addition, Stylus Studio always displays XSLT results in the
Preview window

Optionally, configure settings for global parameters, the XSLT processor you want to
use, whether or not you want to run a profiling report, and whether or not you want to
perform any post-processing on the XSLT result. See Overview of Scenario Features
on page 543 for more information.

To define another scenario, click Add and enter the information for that scenario. You
can also copy scenarios. See How to Clone a Scenario on page 549.

Click OK.

If you start to create a scenario and then change your mind, click Delete and then OK.

How to Run a Scenario

To run a scenario:
1.

548

Select a scenario from the scenario drop-down list at the top of the editor window.
Alternative:
a.

In the XSLT Editor tool bar, click

.
Stylus Studio displays the Scenario Properties dialog box.

On the General tab, select the scenario you want to run from the Existing
Scenarios list.

Click OK.

Click the Preview Result button (

Stylus Studio User Guide

Creating an XSLT Scenario

How to Clone a Scenario

When you clone a scenario, Stylus Studio creates a copy of the scenario except for the
scenario name. This allows you to make changes to one scenario and then run both to
compare the results.
To clone a scenario:
1.

Display the XSLT in the scenario you want to clone.

In the XSLT editor tool bar, click

In the Scenario Properties dialog box, in the Existing preview scenarios field, click
the name of the scenario you want to clone.

Click Clone.

In the Scenario name field, type the name of the new scenario.

Change any other scenario properties you want to change. See How to Create a
Scenario on page 547.

Click OK.

to display the Scenario Properties dialog box.

If you change your mind and do not want to create the clone, click Delete and then OK.

Stylus Studio User Guide

549

Creating XSLT Using the XSLT Mapper

550

Stylus Studio User Guide

Chapter 7

Debugging Stylesheets

Stylus Studio provides several tools that allow you to follow XSLT processing and detect
errors in your stylesheets. To use these tools, you must use the processors displayed in the
Debug and back-mapping enabled section of the Processors page on the Scenario
Properties dialog box. These processors include Stylus Studios XSLT processor,
MSXML .Net, and Saxon 6 and 8. If you use the MSXML XSLT processor or some other
XSLT processor, you cannot use the Stylus Studio debugging and backmapping tools.
You can also use the Stylus Studio debugger to analyze Java files, or applications that
include both stylesheets and Java files. In addition, you can use Stylus Studio to debug
JavaScript and VBScript extension functions. See the Microsoft documentation for
information about these extension functions.
This section discusses the following topics:

Steps for Debugging Stylesheets on page 552

Using Breakpoints on page 552

Viewing Processing Information on page 553

Using Bookmarks on page 556

Determining Which Template Generated Particular Output on page 557

Determining the Output Generated by a Particular Template on page 557

Profiling XSLT Stylesheets on page 558

Handling Parser and Processor Errors on page 561

Debugging Java Files on page 561

Stylus Studio User Guide

551

Debugging Stylesheets

Steps for Debugging Stylesheets

Stylus Studio provides tools for debugging transformations.
To debug a stylesheet:
1.

Open a stylesheet.

Set up a scenario or select the scenario you want to use. See Applying Stylesheets
on page 419.

Set one or more breakpoints. See Using Breakpoints on page 552.

Apply the stylesheet by pressing F5, not clicking Preview Result. If you click Preview
Result, Stylus Studio applies the stylesheet without invoking the debugger.

Examine the information in the debugging tools and in the Preview window.

Run and examine the information XSLT Profiler report.

Iteratively step through the stylesheet or program and examine the information in the
debugging tools.

You can include msxml:script elements in XML documents in Stylus Studio. The msxml
prefix must indicate the Microsoft urn:schemas-microsoft-com:xslt namespace.
The following sections provide the details for performing each of these steps.

Using Breakpoints
The Stylus Studio debugger allows you to interrupt XSLT or Java processing to gather
information about variables and processor execution at particular points.

Inserting Breakpoints
To insert a breakpoint:

552

In the XSLT stylesheet or Java file in which you want to set a breakpoint, place your
cursor where you want the breakpoint to be.

Click Toggle Breakpoint

or press F9. Stylus Studio inserts a blank stop sign
to the left of the line with the breakpoint.

Stylus Studio User Guide

Viewing Processing Information

Removing Breakpoints
To remove a breakpoint:
1.

Click in the line that has the breakpoint.

Press F9 or click Toggle Breakpoint.

Alternative: In the Stylus Studio tool bar, click
Breakpoints to display a list of
breakpoints in all open files. You can selectively remove one or more, remove them
all, or jump to one of them.

Start Debugging
When your stylesheet or Java file has one or more breakpoints set, start processing by
or pressing F5. When Stylus Studio reaches the first
clicking Start Debugging
breakpoint, it suspends processing and activates the debugging tools. After you examine
the information associated with that breakpoint (see Viewing Processing Information
on page 553) you can choose to

Step into. Click

or press F11.

Step over. Click

or press F10.

Step out. Click

or press Shift+F11.

Run to cursor. Click

Continue processing. Press F5.

Stop processing. Click Stop Debugging

in the Stylus Studio tool bar, or click
Cancel in the lower right corner of the stylesheet editor, or press Shift+F5.
Note You can also click Pause

to suspend XSLT processing. Stylus Studio flags the line

it was processing when you clicked Pause.

Viewing Processing Information

Stylus Studio provides several tools for viewing processing information when you
suspend processing. The tools become active when processing reaches a breakpoint. This
section discusses the following topics:

Watching Particular Variables on page 554

Evaluating XPath Expressions in the Current Processor Context on page 554

Obtaining Information About Local Variables on page 554

Stylus Studio User Guide

553

Debugging Stylesheets

Determining the Current Context in the Source Document on page 555

Displaying a List of Process Suspension Points on page 555
Displaying XSLT Instructions for Particular Output on page 556

Watching Particular Variables

Use the Watch window to monitor particular variables. To display the Watch window,
in the Stylus Studio tool bar. This button is active when Stylus Studio
click Watch
suspends processing because it reached a breakpoint. Stylus Studio displays the Watch
window only when processing is suspended.
Enter the names of the variables you want to watch. You can enter as many as you like. In
a Java program, you can double-click a symbol and drag it to the Watch window to enter
it as a variable you want to watch. When Stylus Studio suspends processing, it displays
the current values for any variables listed in the Watch window. You can expand and
collapse complex structures as needed.
Another way to obtain the value for a variable is to hover over the symbol in your
stylesheet or Java program. Stylus Studio displays a pop-up box that contains the current
value.
During XSLT debugging, you can enter XPath expressions in the Watch window fields.
Stylus Studio uses the current context to evaluate these expressions, and displays the
results with the same kind of interface Stylus Studio uses for nodeList and node variables.

Evaluating XPath Expressions in the Current Processor Context

When you suspend processing, you can evaluate an XPath expression in the context of the
in the Stylus Studio tool
suspended process. You do this in the Watch window. Click
bar to display the Watch window. Click in an empty name field and enter an XPath
expression. As soon as you press Enter, Stylus Studio displays the results of the evaluation
in the Value field of the Watch window.

Obtaining Information About Local Variables

Display the Variables window to obtain information about local variables. To display the
Variables window, click Variables
in the Stylus Studio tool bar.This button is active
when Stylus Studio suspends processing because it reached a breakpoint. Stylus Studio
displays the Variables window only when processing is suspended.

554

Stylus Studio User Guide

Viewing Processing Information

For stylesheets, Stylus Studio displays

A path that shows which node in the stylesheet was being processed when processing
was suspended

Local and global XSLT parameter values

Local and global XSLT variable values

Also, you can navigate the structure associated with a variable, a parameter, or the current
context if it is a node list or a node.
For Java classes, Stylus Studio displays

Local variables that are defined at that point in the processing and their values.

Function parameters and their values.

A special variable named this. The this variable represents the object being
processed. It allows you to drill down and obtain additional information.
You can expand and collapse complex structures as needed.

Determining the Current Context in the Source Document

When you are debugging a stylesheet, the Variables window displays a path for the
current context. This is the set of nodes that the XSLT processor is currently working
through. This allows you to examine the nodes that lead to the context node.

Displaying a List of Process Suspension Points

Display the Call Stack window to view a list of the locations at which processing was
in the Stylus Studio
suspended. To display the Call Stack window, click Call Stack
tool bar. This button is active when Stylus Studio suspends processing because it reached
a breakpoint. Stylus Studio displays the Call Stack window only when processing is
suspended.
For stylesheets, Stylus Studio displays the template name and line number. For Java
classes, Stylus Studio displays the class name, function name, parameters, and line
number.
When processing is complete, the call stack is empty.
When execution is suspended you can use the Call Stack window to jump directly to the
XSLT or Java source. Double-click on a stack line to go to that location. A green triangle
appears to indicate this location in the source file.

Stylus Studio User Guide

555

Debugging Stylesheets

The Call Stack window and the Backmap Stack window provide the same kind of
information. However, the Backmap Stack window never shows Java entries, and the
contents of the Backmap Stack window can be different from the Call Stack window
according to where you click in the output to enable backmapping.

Displaying XSLT Instructions for Particular Output

After you apply a stylesheet, or during debugging of a stylesheet, Stylus Studio can
display the XSLT instruction or the sequence of XSLT instructions that generate a
particular part of a result document. This can be particularly helpful when the result is not
quite what you want.
To view XSLT instructions:
1.

Open a stylesheet.

Apply the stylesheet.

In the Preview window, in either the text view or the browser view, click on the output
for which you want to display the XSLT calls.

Stylus Studio displays the Backmap Stack window, which lists one or more XSLT
instructions. Also, Stylus Studio flags the line in the stylesheet that contains the first
instruction in the list. To find the location of another listed instruction, click that
instruction in the Backmap Stack window.
The Call Stack window and the Backmap Stack window provide the same kind of
information. However, the Backmap Stack window never shows Java entries, and the
contents of the Backmap Stack window can be different from the Call Stack window
according to where you click in the output to enable backmapping.

Using Bookmarks
When you are editing or debugging a long file, you might want to repeatedly check certain
lines in the file. To quickly focus on a particular line, insert a bookmark for that line. You
can insert any number of bookmarks. You can insert bookmarks in any document that you
can open in Stylus Studio.
To insert a bookmark:
1.

556

Click in the line that you want to have a bookmark.

Stylus Studio User Guide

Determining Which Template Generated Particular Output

Click Toggle Bookmark

in the Stylus Studio tool bar. Stylus Studio inserts a
turquoise box with rounded corners to the left of the line that has the bookmark.

To remove a bookmark:
1.

Click in the line that has the bookmark you want to remove.

Click Toggle Bookmark in the Stylus Studio tool bar. Stylus Studio removes the
turquoise box.

To remove all bookmarks in a file, click Clear All Bookmarks

To move from bookmark to bookmark, click Next Bookmark

Bookmark
.

or Previous

Determining Which Template Generated Particular

Output
In Stylus Studio, you can easily determine which template is responsible for generating
any particular portion of the HTML output.
Click anywhere in the Preview in tree, Preview in Browser, or Preview Text view of the
Preview window. In the XSLT Source tab, Stylus Studio points to the line that generated
that portion of the HTML output. This is the Stylus Studio backmapping feature.
Note It is possible for backmapping to point to the wrong line if you made changes in the XSLT

source and did not preview the results.

Determining the Output Generated by a Particular

Template
In the XSLT Source pane, if the cursor is in a template, the output from that template has
a gray background in the Preview Text view of the Preview window. In the Preview in tree
view of the Preview window, the contents generated by the template are highlighted.
In the Preview in Browser view of the Preview window, there is no gray shading to
indicate the output from the currently displayed template.

Stylus Studio User Guide

557

Debugging Stylesheets

Profiling XSLT Stylesheets

The XSLT Profiler is available only in Stylus Studio XML Enterprise Suite.
In addition to debugging tools for XSLT, Stylus Studio provides the XSLT Profiler, a tool
that helps you evaluate the efficiency of your XSLT. By default, the performance metrics
gathered by the XSLT Profiler are displayed in a preformatted report, like the one shown
Figure 280:

Figure 280. XSLT Profiler Report

The report format is controlled by the default XSLT stylesheet, profile.xsl, in the \Stylus
You can customize this stylesheet as required. You can save XSLT
Profiler reports as HTML.

Studio\bin directory.

Note XSLT and XQuery Profiler reports use the same XSLT stylesheet.

558

Stylus Studio User Guide

Profiling XSLT Stylesheets

In addition to generating the standard XSLT Profiler report, you can save the raw data
generated by the Profiler and use this data to create your own reports. See Enabling the
Profiler on page 559 for more information about this procedure.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XSLT Profiling video.
A complete list of all the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.

About Metrics
The XSLT Profiler can record three different levels of performance metrics:

A call tree of execution times

Execution times by XSLT element, and

A detailed log of step-by-step element execution

Note Displaying the report for a step-by-step log can take significantly longer than evaluating

the XSLT itself. Consider using the Profiler with the first two performance metric
options. You can also use the Limit Trace To fields to further restrict the Profilers scope.
If you find you need still more detail (while troubleshooting a performance bottleneck,
for example), use the step-by-step setting.

Enabling the Profiler

The XQuery Profiler is off by default. You enable the Profiler on the Profiling Options tab
of the XSLT Scenario Properties dialog box.
To enable the XSLT Profiler:
1.

Open the Scenario Properties dialog box for the XSLT stylesheet. (Click Browse
at the top of the XSLT editor window.)

Stylus Studio User Guide

559

Debugging Stylesheets
2.

Click the Profiling Options tab.

Figure 281. Profiling Options

Select the settings for the performance metrics you want the Profiler to capture.

Optionally, save the raw Profiler data to a separate file.

This option is available only after you select one or more performance metrics
settings.

Note

Click OK.
The next time you preview the XSLT results, the performance metrics you selected
are available to you in the XSLT Profiler report (and as raw data if you selected that
setting and specified a file).

Displaying the XSLT Profiler Report

To display the XSLT Profiler report:

560

Ensure that the Profiler is enabled. (See Enabling the Profiler on page 559 if you
need help with this step.)

Click the Preview Result button (

Click the Show Profiling Report button (

).
The XSLT Profiler report appears in the Preview window.

Stylus Studio User Guide

Handling Parser and Processor Errors

When you refresh stylesheet output, Stylus Studio parses and processes your XML
document and XSLT stylesheet. If the processor encounters a parser or processing error,
Stylus Studio displays a message that indicates the nature and location of the error. Stylus
Studio prompts you to indicate if you want to jump to the error location in your stylesheet.

Debugging Java Files

Support for debugging Java extensions is available only in Stylus Studio XML
Enterprise Suite and Stylus Studio XML Professional Suite.
The Stylus Studio debugger allows you to follow Java processing as well as XSLT
processing. With the Stylus Studio debugger, you can observe the interaction between
your Java code and XML data.
When you debug a transformation, the transformation can include the processing of Java
files. Such Java files might be servlets, server extensions, extension functions, or other
kinds of Java programs that involve stylesheets. If you need to make a change to your Java
file, you can compile it right in Stylus Studio. Click Compile
in the upper left corner
of the Java file window. Stylus Studio automatically saves the file before it compiles it.
This section discusses the following topics:

Requirements for Java Debugging on page 561

Setting Options for Debugging Java on page 562

Using the Java Editor on page 563

Stylus Studio and the JVM on page 564

Example of Debugging Java Files on page 564

Requirements for Java Debugging

If you want to use Stylus Studio to debug Java code, you must have the Sun Java Runtime
Environment (JRE) 1.4.x installed. If you want to use Stylus Studio to assist you in editing
and compiling Java code, you must have the Sun JDK 1.4.x installed.
You can download the Sun Java products from http://www.javasoft.com/j2se/.
After you install the JRE, you must run the Stylus Studio auto-detect feature. For more
information, see Configuring Java Components.

Stylus Studio User Guide

561

Debugging Stylesheets
To run the auto-detect feature:
1.

Select Tools > Options from the Stylus Studio menu bar.

In the Options dialog box, click Java Virtual Machine.

In the Java Virtual Machine page, click Auto detect.

Also, in the Parameters field of the Java Virtual Machine page, there should be something
like the following:
-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,
server=y,suspend=n,address=8000 -Djava.compiler=NONE

To confirm that your set up is correct, select Help > About Stylus Studio from the Stylus
Studio menu bar. The Java Virtual Machine field in the About Stylus Studio dialog box
should indicate that the JVM is running in debug mode.

Setting Options for Debugging Java

You can specify the following options when you use Stylus Studio to debug Java code:

Source Path is the path that Stylus Studio uses to locate the source files during
debugging.

Prompt user for source file path confirmation indicates that if Stylus Studio cannot
find the source files you are debugging, it prompts you to specify the source file path.
If you do not set this option, and Stylus Studio cannot find a source file, the behavior
varies according to what the debugger is trying to do. For example, if the debugger is
stepping into an instruction that calls a function that is defined in a Java file that Stylus
Studio cannot find, the debugger steps over the instruction.

562

Never step into classes starting with one of the following strings of characters:

contains a list of classes, one on each line, that you do not want to step into. For
example, these might be classes that are part of the core language, or classes that you
do not have source files for. If you specify java.lang, the debugger skips all classes
whose names start with java.lang, for example, java.lang.String and
java.lang.Object.
JVM communication time out indicates the amount of time that Stylus Studio waits
for a response from the JVM. If Stylus Studio does not receive a response in the
specified amount of time, it stops trying to communicate with the JVM. The default
is 5 seconds.

Stylus Studio User Guide

Debugging Java Files

Show JDWP Events in the Output Window indicates whether you want Stylus Studio
to log all communication events in the Stylus Studio Output Window during a

debugging session.
Stylus Studio also allows you to set options that specify the Java virtual machine (JVM)
you use. You can specify the run-time library, the home directory, and parameters for
starting the JVM. Select Tools > Options from the Stylus Studio menu bar.
See Specifying Stylus Studio Options on page 120 for instructions for setting these
options.

Using the Java Editor

To use the Stylus Studio Java editor, open a Java file in Stylus Studio.
To specify arguments that Stylus Studio uses to run the active Java class, select Java >
Class Properties from the Stylus Studio menu bar. Stylus Studio displays the Class
Properties dialog box. Enter the arguments required to run your code. (You must have a
Java file open in Stylus Studio for Java to appear in the menu bar.)
The same debugging capabilities that are available when you are debugging XSLT
stylesheets are available when you are debugging stand-alone Java applications.
When you use the Java editor, the Sense:X auto-completion feature is available. The Java
editor browses your import directives to gather information about the packages you are
using and provides auto-completion when using methods or data members defined in
imported classes. The auto-completion mechanism also provides you with tips about the
signature of the class method and its required arguments. The same applies to the classes
that you are editing. Also, the CLASSPATH is used to help you auto-complete import
directives. Type Ctrl+Space if you want Stylus Studio to auto-complete keywords and
class names that are defined in java.lang.package.
The Stylus Studio Java editor also does background error checking. As you type Java
code, Stylus Studio displays red lines that indicate syntax errors. Move the cursor over the
red line to display a pop-up error message.
When you use the Java editor, you can configure the character encoding that Stylus Studio
uses to save and load files. To do this, ensure that a Java file is the active file. Then select
Edit > Change Encoding from the Stylus Studio menu bar.
Context-sensitive help for your Java classes is available in the Java editor. The directory
that contains the javadoc-generated documentation must be in the Stylus Studio class path
(in the Stylus Studio menu bar select Tools > Options > Java Virtual Machine) or in your

Stylus Studio User Guide

563

Debugging Stylesheets
CLASSPATH environment

variable. You can then press F1 when your cursor is on a class

name in the Java editor. Stylus Studio opens the related javadoc-generated
documentation.

Stylus Studio and the JVM

Stylus Studio allows you to debug a running application. You can attach Stylus Studio to
a local or remote Java Virtual Machine (JVM), and run your application in debug mode.
In the Stylus Studio tool bar, click Attach
to debug a standalone Java program that is
running an external JVM. (Attach is not for debugging Java extensions.)
To execute a class, open the Java source in Stylus Studio and press F5. Of course, the class
must be in your CLASSPATH environment variable or in the Stylus Studio ClassPath (select
Tools > Options > Java Virtual Machine).
To verify the JVM that Stylus Studio is trying to load:
1.

Select Tools > Options from the Stylus Studio menu bar.

In the Options dialog box that appears, click General > Java Virtual Machine.

The Home Directory field indicates the version of the JVM.

When you suspend processing, display the Output Window to view any output from the
in the
Java virtual machine. To display the Output Window, click Output Window
Stylus Studio tool bar.

Example of Debugging Java Files

Stylus Studio includes sample files that you can experiment with to learn how to use the
debugger with an application that includes stylesheets and Java files. To get you started,
this section provides step-by-step instructions for using the debugger with these sample
files. You should perform the steps in each topic in the order of the topics.
For complete information about how to use the debugger, see Debugging Stylesheets on
page 551.
This section includes the following topics:

Setting Up to Debug Sample Java/XSLT Application on page 565

Inserting a Breakpoint in the Sample Java/XSLT Application on page 565

Gathering Debug Information About the Sample Java/XSLT Application on

page 566

564

Stylus Studio User Guide

Debugging Java Files

Setting Up to Debug Sample Java/XSLT Application

To set up Stylus Studio to debug the sample Java/XSLT application:
1.

From the Stylus Studio menu bar, select Tools > Options.

In the Options dialog box that appears, click Java Virtual Machine.

If the examples\javaExtension directory is already in the ClassPath field, click OK.

If the examples\javaExtension directory is not in the ClassPath field, click Browse
next to the ClassPath field. In the Browse for Folder dialog box that appears,
navigate to and select the javaExtension directory, which is in the examples directory
of your Stylus Studio installation directory. Click OK. Restart Stylus Studio. For
ClassPath changes to take effect, you must restart Stylus Studio whenever you modify
the ClassPath field.

In the File Explorer, navigate to the examples\javaExtension directory in your Stylus

Studio installation directory.

Double-click IntDate.xsl.
Stylus Studio opens the IntDate.xsl stylesheet in the XSLT editor. The tree for the
XML source document, IntDate.xml, also appears.

In the XSLT editor tool bar, click Preview Result

.
The IntDate scenario has already been defined. Stylus Studio applies the stylesheet
and displays the results (a list of dates) in the Preview window.

Inserting a Breakpoint in the Sample Java/XSLT Application

This topic is part of a sequence that starts with Setting Up to Debug Sample Java/XSLT
Application on page 565.
To insert a breakpoint in the sample stylesheet:
1.

In the XSLT editor, examine the template that matches the date element.
As you can see, the select attribute in the xsl:value-of instruction invokes the
IntDate Java extension function.

In the body of the template, click just before the xsl:value-of instruction.

In the Stylus Studio tool bar, click Toggle Breakpoint

Press F5 to apply the stylesheet.

Alternative: In the Stylus Studio tool bar, click Start Debugging

Stylus Studio User Guide

.
.
565

Debugging Stylesheets

The XSLT processor suspends processing at the breakpoint, displays a yellow triangle
to indicate where processing has been suspended, and displays a message in the
Preview window.

Gathering Debug Information About the Sample Java/XSLT Application

This topic is part of a sequence that starts with Setting Up to Debug Sample Java/XSLT
Application on page 565.
To obtain debug information:

566

In the Stylus Studio tool bar, click Step into

or press F11.
Stylus Studio opens and displays the Java source file that contains the IntDate
extension function. Now the Variables window displays a list of the variables in the
extension function. There is still no output in the Preview window.
Stylus Studio might display the Browse For Folder dialog box. It is prompting you to
specify where it can find the Java source file that contains the extension function
invoked in the line that has the breakpoint. Stylus Studio does not display the Browse
for Folder dialog box when the .java file is in the same directory as the .class file.
Click the javaExtension directory and click OK.

In the Stylus Studio tool bar, click Output Window

.
Stylus Studio displays the Output Window, which displays output from the Java
virtual machine.

In the Stylus Studio tool bar, click Step Over

or F10 to move to the next line of
Java code.
The yellow triangle moves to show the new location. If the values of the variables
change, the Variables window reflects this.

Press Step Out

to return to the stylesheet.
The Variables window now displays only the context node. Processing was suspended
when the second date child element of the doc document element was the context
node.
The Preview window now displays a few lines of HTML.

In the Preview window, click in the first line of text.

Stylus Studio displays the Backmap Stack window, which contains a list of the XSLT
instructions that have been executed. Also, in the XSLT Source tab, Stylus Studio
displays a blue triangle that indicates the line in the stylesheet that generated the
output line you clicked in.
Stylus Studio User Guide

Chapter 8

Defining XML Schemas

This section provides information about how to use Stylus Studio to define an XML
Schema. Although some information about XML Schema tags is provided, familiarity
with the W3C XML Schema Recommendation is assumed.
Many of the examples in this chapter are based on the purchaseOrder.xsd document,
which is installed with other sample files in the examples\simpleMappings directory of
your Stylus Studio installation directory. Consider having this file open as you read
through the examples in this chapter.
This section covers the following topics:

What Is an XML Schema? on page 568

Creating an XML Schema in Stylus Studio on page 568

Working with XML Schema in Stylus Studio on page 581

Getting Started with XML Schema in the Tree View on page 592

Defining simpleTypes in XML Schemas on page 599

Defining complexTypes in XML Schemas on page 609

Defining Elements and Attributes in XML Schemas on page 619

Defining Groups of Elements and Attributes in XML Schemas on page 628

Adding Comments, Annotation, and Documentation Nodes to XML Schemas on

page 632

Defining Notations on page 635

Referencing External XML Schemas on page 636

Generating Documentation for XML Schema on page 643

About XML Schema Properties on page 648

Stylus Studio User Guide

567

Defining XML Schemas

What Is an XML Schema?

An XML Schema conforms with the W3C XML Schema Recommendation. The XML
Schema Recommendation defines an XML markup vocabulary for specifying the structure
of an XML document. An XML Schema serves the same purpose as a DTD. The most
visible difference is that an XML Schema is in XML, while a DTD is not.
Like a DTD, an XML Schema describes the structure of a document. However, an XML
Schema contains more specialized types of nodes than a DTD schema. For example, in an
XML Schema, you can define nodes of type group and attributeGroup. These nodes
contain groups of elements and attributes, respectively.
In an XML Schema, elements that contain subelements or attributes are called
complexTypes. Elements that contain data but do not contain subelements or attributes are
simpleTypes. Attributes are always simpleTypes. In your XML Schema, along with
elements and attributes, you define complexTypes and some simpleTypes. In addition,
many simpleTypes are part of the XML Schema grammar.

Reference Information
The World Wide Web Consortium (W3C) provides information about XML Schema,
including the following:

XML Schema Part 0: Primer at http://www.w3.org/TR/xmlschema-0/

Glossary of XML Schema terms at http://www.w3.org/TR/2001/REC-xmlschema-120010502/#normative-glossary

Reference information for simpleTypes and their facets at

http://www.w3.org/TR/xmlschema-0/#SimpleTypeFacets

Reference information for XML Schema elements and attributes at

http://www.w3.org/TR/xmlschema-0/#index

Creating an XML Schema in Stylus Studio

There are several ways to create an XML Schema in Stylus Studio, including building
your own XML Schema from scratch, and creating an XML Schema based on an existing
DTD or from an XML document.
This section covers the following topics:

Creating Your Own XML Schema on page 569

Creating XML Schema from a DTD on page 569

568

Stylus Studio User Guide

Creating an XML Schema in Stylus Studio

Creating XML Schema from an XML Document on page 574

You can also create XML Schema from EDI message types and transactions, like those in
EDIFACT, X12, and IATA dialects. See Creating XML Schema from EDI on page 577.

Creating Your Own XML Schema

To create an XML Schema, select File > New > XML Schema from the menu bar.

Stylus Studio displays a new XML document in the XML Schema Editor Diagram tab;
the text pane displays the following contents:
<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
</xsd:schema>

When you create an XML Schema in Stylus Studio, the default namespace is specified as
http://www.w3.org/2001/XMLSchema. If you choose to you specify the XML Schema
namespace, be sure to specify one of the following:

http://www.w3.org/2001/XMLSchema

http://www.w3.org/2001/XMLSchema-instance

Creating XML Schema from a DTD

Stylus Studio has two document wizards you can use to create an XML Schema from a
DTD. One uses a built-in processor; the other uses the Trang schema converter from Thai
Open Source Software Center (www.thaiopensource.com). Using the Trang converter gives
you more control over both the input file and output characteristics (such as whether or
not you want to indent the XML Schema).

Using the DTD to XML Schema Document Wizard

To use the DTD to XML Schema wizard:
1.

From the Stylus Studio menu bar, select File > Document Wizards.
The Document Wizards dialog box appears.

Stylus Studio User Guide

569

Defining XML Schemas

In the XML Editor tab, click DTD to XML Schema, and click OK.
The Convert DTD to XML Schema dialog box appears.

Figure 282. Convert DTD to XML Schema Dialog Box

In the DTD URL field, type or select the absolute path for the DTD from which you
want to create an XML Schema.
The DTD must be encoded in UTF-8.

Note
4.

If you want to specify a target namespace for the resulting XML Schema, select the
Use a Target Namespace check box and type a target namespace URL.

Click OK.
Stylus Studio displays the new XML Schema in the XML Schema Editor.

Using the DTD to XML (Trang) Document Wizard

The following table describes the fields in the DTD to XML (Trang) dialog box, which is
displayed when you run the DTD to XML (Trang) document wizard. This document
wizard was created using Stylus Studio Custom Document Wizard (see Custom
Document Wizards on page 1176 for more information).
Table 67. DTD to XML (Trang) Document Wizard Fields

570

FIeld

Description

Input file (required)

The name and location of the DTD file you want to

convert to XSD. You can type the file name or use the
Browse button to browse a file system for the source
DTD file.

[input] xmlns=<uri>

The default namespace; used for unqualified element

names.

Stylus Studio User Guide

Creating an XML Schema in Stylus Studio

Table 67. DTD to XML (Trang) Document Wizard Fields
FIeld

Description

[input] xmlns:<prefix=uri>

The namespace for the element and autoboot names

using prefix.

[input] colonreplacement=<chars>

The character that is used to replace colons in element

names. Used when constructing the names of
definitions used to represent the element and attribute
list declarations in the DTD. Trang generates a
definition for each element declaration and attlist
declaration in the DTD. The definition name is based on
the element name. In RELAX NG, the definition names
cannot contain colons; colons are allowed in element
names in DTDs. Trang first tries to use the element
names without prefixes. If this results in a conflict,
Trang replaces the colon with the chars specified. If no
chars is specified, a period is used.

[input] element-define=<namepattern>

Specifies how to construct the name of the definition

representing an element declaration from the name of
the element. The name-pattern must contain exactly
one percent character (%). This character is replaced by
the name of the element, after colon replacement, and
the result is used as the name of the definition.

[input] inline-attlist / noinline-attlist

inline-attlist specifies not to generate definitions for

attribute list declarations. Instead, attributes in attribute

list declarations are moved into the definitions
generated for element list declarations.
no-inline-attlist generates a distinct definition (with
combine=interleave)

for each attribute list

declaration in the DTD; each element declaration
definition references the definition for the
corresponding attribute list declaration.

Stylus Studio User Guide

571

Defining XML Schemas

Table 67. DTD to XML (Trang) Document Wizard Fields

572

FIeld

Description

[input] attlist-define=<namepattern>

Specifies how to construct the name of the definition

representing an attribute list declaration from the name
of the element. The name-pattern must contain exactly
one percent character (%). This character is replaced by
the element name, after colon replacement, and the
result is used as the name of the definition.

[input] any-name=<name>

Specifies the name of the definition generated for the

content of elements declared in the DTD as having a
content model of ANY.

[input] strict-any

Preserves the exact semantics of ANY content models

by using an explicit choice of references to all declared
elements. By default, Trang uses a wildcard that allows
any element.

[input] annotationprefix=<prefix>

Default values are represented using an annotation

attribute prefix:defaultValue where prefix is bound
to http://relaxng.org/ns/compatibility/annotations/1.0
as defined by the RELAX NG DTD Compatibility
Committee Specification. By default, Trang uses a for
prefix unless that conflicts with a prefix used in the
DTD.

[input] generate-start / nogenerate-start

Specifies whether or not Trang should generate a start

element. DTDs do not indicate what elements are
allowed as document elements. Trang assumes that all
elements that are defined but never referenced are
allowed as document elements.

[output] encoding=<name>

Uses name as the encoding for output files.

[output] indent=<n>

Indents each indent level in the output file by n spaces.

[output] disable-abstractelements

Disables the use of abstract elements and substitution

groups in the generated XML schema.

Stylus Studio User Guide

Creating an XML Schema in Stylus Studio

Table 67. DTD to XML (Trang) Document Wizard Fields
FIeld

Description

[output] any-processcontents=strict|lax|skip

Specifies the value for the processContents attribute of

any elements. The default is strict, which corresponds to
DTD semantics.

[output] any-attribute-processcontents=strict|lax|skip

Specifies the value for the processContents attribute of

anyAttribute elements. The default is skip, which
corresponds to RELAX NG semantics.

To use the DTD to XML Schema (Trang) wizard:

From the Stylus Studio menu bar, select File > Document Wizards.
The Document Wizards dialog box appears.

In the XML Editor tab, click DTD to XML Schema (Trang) and click OK.
The DTD to XML Schema (Trang) dialog box appears.

Figure 283. DTD to XML Schema (Trang) Dialog Box

Stylus Studio User Guide

573

Defining XML Schemas

Enter the absolute path of the DTD from which you want to create an XML Schema.
The DTD must be encoded in UTF-8. You can type the file path, or use the browse
button (which appears when you place the cursor in the Input file (required) field. This
is the only required field.

Optionally, complete any of the remaining fields.

Click OK.
Stylus Studio displays the new XML Schema in the XML Schema Editor.

Creating XML Schema from an XML Document

There are two ways to create XML Schema from an XML document:

The XML to XML Schema document wizard allows you to create XML Schema from
any XML document. The XML document you use to create the XML Schema is not
modified with attribute information about the new XML Schema when you use this
method.

The Create Schema from XML Content feature in the XML Editor. This method
allows you to create an XML Schema (or DTD) based on the current XML document
in the XML Editor. The XML document is always modified with namespace and
schema location attributes when you use this method. If you choose to create DTD,
you have the option of creating internal or external DTD.
Both methods allow you to specify the URI for the generated files (if an XML document
has multiple namespaces defined for it, Stylus Studio creates a separate XML Schema
associated with each namespace).

Using the XML to XML Schema Document Wizard

Use this procedure when you want to create an XML Schema based on the content of an
existing XML document.
To use the XML to XML Schema document wizard:
1.

574

Select File > Document Wizards from the menu.

The Document Wizards dialog box appears.

Stylus Studio User Guide

Creating an XML Schema in Stylus Studio

Double-click XML to XML Schema.

The Convert XML to XML Schema dialog box appears.

Figure 284. Convert XML to XML Schema Dialog Box

Specify the XML document you want to use to create an XML Schema in the XML
Document field.

Specify the URI for the generated file(s) in the Generated XSD field.

Click the OK button.

Stylus Studio creates the XML Schema file and opens it in the XML Schema Editor.

Using the Create Schema from XML Content Feature

Use this procedure when you want to create an XML Schema based on the content of an
existing XML document.
To use the Create Schema XML Content feature:
1.

Open the XML document from which you wish to create an XML Schema.

Stylus Studio User Guide

575

Defining XML Schemas

Select XML > Create Schema from XML Content from the Stylus Studio menu.
The Create Schema or DTD dialog box appears.

Figure 285. Create Schema or DTD Dialog Box

Click Generate XML Schema.

The Output File field becomes active.

Type a name for the XML Schema you want to create, or use the browse button (
to search for an existing file.

Click the Yes button.

The XML Schema is created. If you do not specify a complete URL, the schema is
written to the same location as the XML document from which it was created.

Displaying the New XML Schema

Use this procedure to open the new XML Schema created using the Create Schema from
XML Content feature (or to open the XML Schema associated with any active XML
document).
To display the new XML Schema:

576

Click XML > Open Associated Schema.

Select the XML Schema from the drop-down menu.

The XML Schema appears in the XML Schema Editor.

Stylus Studio User Guide

Creating XML Schema from EDI

The EDI to XSD document wizard is available only in Stylus Studio XML
Enterprise Suite.
The EDI to XSD document wizard allows you to create XML Schema based on supported
EDI dialects like EANCOM, EDIFACT, Edig@s, HIPAA, HL7, IATA, NCPDP,
TRADACOMS, and X12.
This section covers the following topics:

Wizard Options on page 577

Running the EDI to XSD Document Wizard on page 579

Wizard Options
Though specifics vary across EDI dialects (IATA and EANCOM refer to versions, while
X12 refers to Release, for example), the options for most EDI document wizards are
similar, if not the same. Document wizard options are summarized in the following table.
Once specifying the dialect and version, you use the fields of the XML Structure group
box to specify the structure of the XML; you use the fields of the XML Schema Options
group box to specify the settings that are used to generate the XML Schema for the
selected EDI message.
Table 68. EDI Document Wizard Options
Option Name

Description

Dialect

The EDI dialect from which you want to create an XML Schema.

Version

The version of the EDI dialect from which you want to create an
XML Schema.

Mode

Certain EDI messages have alternate batch and interactive forms,

depending upon whether they are used between systems that have
real-time connections. The Interactive setting causes the interactive
form to be used, if available. For example, in EDIFACT, this would
cause the normal envelope of UNB/UNH/UNT/UNZ to be replaced
by UIB/UIH/UIT/UIZ. Valid for EANCOM, EDIFACT, and IATA
only.

Message

The specific message type from which you want to create an XML
Schema.

Stylus Studio User Guide

577

Defining XML Schemas

Table 68. EDI Document Wizard Options

578

Option Name

Description

Use long element names

Whether or not you want to use the long element name as part of the
XML tag UNB01-SyntaxIdentifier versus UNB01, for example

Wrap GROUP
element around message
groups

Whether you want to wrap a <GROUP> element around transaction

messages. This can make message groupings easier to handle with
XPath for EDI document with multiple message groups.

Prefix GROUP_N tags

with the message name

Adds the message name to the GROUP_n prefix in the XML

element tag. For example, <TS_831_GROUP_1>.

Put the data value in

value= attributes

Places code list data values in an value= string in the element tag.
For example, <BGN01 value="00"></BGN01>. By default, the data value is output to
XML as text (<BGN01><!--353: Transaction Set Purpose Code->00</BGN01>).

Put decoded data values

in decode= attributes

Places decoded code list data values in a decode= string in the

element tag. For example, <ISA15 decode=Production Data>. By
default, the decoded value is not output to XML.

Write annotations
describing each element

Whether or not you want the generated XML Schema to include

annotations that are part of the EDI message.

Enumerations for
elements that have
codelists

Whether or not you want the generated XML Schema to include

enumerations for fields that have lists of values.

Use unbounded for

maxOccurs when loop
value is 99 or higher)

Replaces maxOccurs values of 100 or greater with unbounded.

This option ensures that the generated XML Schema can be
successfully validated by most processors

SEF File

The URI of the Standard Exchange Format (SEF) file, if any, you
want to use when generating XML Schema. The SEF file can
augment information that Stylus Studio uses to generate XML
Schema customized EDI definitions are stored in the SEF file, for
example. If the same setting is specified by both the document
wizard and the SEF file, the SEF file value is used.

Stylus Studio User Guide

Creating XML Schema from EDI

Running the EDI to XSD Document Wizard

To run an EDI to XML Schema document wizard:
1.

Select File > Document Wizards from the Stylus Studio menu.
The Document Wizards dialog box appears.

Select the XML Editor tab:

Figure 286. Document Wizards Dialog Box

Stylus Studio User Guide

579

Defining XML Schemas

Double-click the icon for the EDI to XSD document wizard.

A dialog box for the document wizard you selct appears. The Generate XML Schema
from EDI Standards dialog box is shown here.

Figure 287. Generate XML Schema from EDI Standards

580

If necessary, change the version ID or release number. Values are listed

chronologically in ascending order.

Select the message or transaction set on which you wish to base the XML Schema
you are creating.

Change the XML Schema creation options as required. See Wizard Options on
page 577 if you need help with this step.

Click OK.
Stylus Studio converts the EDI you selected in Step 5 to XML Schema and opens a
new, untitled document in the XML Schema Editor.

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

You use the XML Schema Editor to view, define, and validate XML Schema using one or
more of three tabs, or views. This section describes these and other tools for working with
XML Schema in Stylus Studio.
This section covers the following topics:

Views in the XML Schema Editor on page 582

Validating XML Schema on page 585

Updating XML Schema Associated with a Document on page 585

Viewing Sample XML on page 585

Using XML Schema in XQuery and XSLT Mapper on page 587

Printing on page 587

Node Properties on page 589

Searching for Referencing Nodes on page 589

Stylus Studio User Guide

581

Defining XML Schemas

Views in the XML Schema Editor

The XML Schema Editor has Diagram, Tree, and Documentation tabs. The Diagram tab,
which is the default for the XML Schema Editor, is shown in Figure 288.

Figure 288. XML Schema Editor Diagram Tab

Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Schema Diagram Editor
video.
You can see other Stylus Studio video demonstrations here:
http://www.stylusstudio.com/xml_videos.html.

Each tab displays the schema from a unique perspective, as summarized here:

Diagram Displays the XML Schema using graphical elements for the nodes
(elements, attributes, simpleTypes, complexTypes, and so on) defined in the XML
Schema in a diagram pane. Container elements can be expanded to show child
582

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

elements, and values such as element and attribute names and types can be edited in
place by double-clicking the node you want to modify.
In addition to the diagram pane, the Diagram tab includes a text pane. The text pane
displays the raw XML text used to define the XML Schema, and lets you see how the
changes you make in the diagram affect the XML Schema text. You can make
changes in either pane to a node in the diagram, or directly to the text Stylus Studio
keeps both views synchronized.
The Diagram tab has a full complement of editing tools, including checkers for wellformedness and validation, as well as a query functionality that lets you evaluate your
query using either XPath 1.0 or XPath 2.0. XML Schema query is also supported in
the Tree tab. See <hyperlink>Printing on page 587 to learn how to print information
in the Diagram tab.
For more information on the Diagram tab, including a description of the graphical
symbols used to represent XML Schema elements, see Introduction to the XML
Schema Editor Diagram Tab on page 67.
Tree Displays a DOM tree representation of the XML Schema. You can edit the
XML Schema graphically, in the tree itself, or by modifying the properties of the
nodes you select.

Figure 289. XML Schema Editor Tree Tab

Stylus Studio User Guide

583

Defining XML Schemas

Documentation Displays read-only summary and detailed reference information

about the XML Schema, including sections for schema document properties, global
declarations, and global definitions.

Figure 290. XML Schema Editor Documentation Tab (XS3P Format)

In Stylus Studio, the information in all tabs synchronized automatically.

Generally speaking, if you are just getting started with XML Schema you should consider
using the Diagram tab to work with XML Schema in Stylus Studio. Its graphical user
interface makes defining XML Schema easy and error-free, and the built-in text pane,
which lets you see how new nodes are rendered in XML, can be a useful learning tool.
To get started using the Diagram view to define an XML Schema, see Defining an XML
Schema Using the Diagram Tab Getting Started on page 66. Procedures for working
with the Diagram tab are also covered throughout this chapter.

584

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

Validating XML Schema

Stylus Studio can analyze your XML Schema document to determine if it is valid. At any
time, click Validate Document
in the Stylus Studio tool bar to ensure that your schema
is valid. If it is not, Stylus Studio displays a message that indicates the cause and location
of the error.

Choosing a validation engine

When you click the Validate Document
button, Stylus Studio uses the built-in
validation engine. If you want to use a different validation engine, like XML Schema
Validator (XSV), for example:
1.

Click the down arrow next to the Validate Document

A list of supported validation engines appears.

Select the validation engine you want to use.

Click the Validate Document

button.

button again to validate your XML Schema.

Updating XML Schema Associated with a Document

Stylus Studio can associate an XML Schema with an XML document, and it can validate
an XML document against its associated XML Schema. If you update an XML Schema
in Stylus Studio and that schema is associated with an XML document that is open in
Stylus Studio, Stylus Studio refreshes the XML Schema information for the XML
document.

Viewing Sample XML

You can view a sample of the XML represented by a node in the XML Schema Diagram
tab. You can also optionally create an XML document based on that instance. For

Stylus Studio User Guide

585

Defining XML Schemas

example, here is an instance of the XML represented by the purchaseOrder element in

purchaseOrder.xsd.

Figure 291. Sample of XML Based on XML Schema

If you want, you can create a new XML document based on this instance by clicking the
Open as New Document button.
Note If the XML Schema contains an element defined using a built-in type, the instance of that

586

In the Diagram tab, select the node for which you want to see sample XML.

Select Diagram > View XML Sample from the Stylus Studio menu.
Alternative: Select View XML Sample from the nodes shortcut menu (right-click to
display).
The View Sample XML dialog box appears. (See Figure 291.)

If you want to open this instance as a new XML document in Stylus Studio, click the
Open as a New Document button. Otherwise, click Close Preview.

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

Using XML Schema in XQuery and XSLT Mapper

You can use an XML Schema as the source document or target document for Stylus
Studios XQuery and XSLT Mappers. See Building an XQuery Using the Mapper on
page 813 and Creating XSLT Using the XSLT Mapper on page 507 for more
information on these topics.

Printing
You can print XML Schema from the Diagram tab, and you can print XML Schema
documentation from the Documentation tab.

Printing XML Schema

Stylus Studio allows you to print either the graphics in the diagram pane, or the raw XML
in the text pane. If one pane is collapsed, Stylus Studio prints the visible pane. If both
panes are visible, Stylus Studio prints the pane that currently has focus.
Tip Select File > Print Preview to verify the output before you print.

To print XML Schema from the Diagram tab:

Select the pane of the Diagram tab you want to print.

Click Print
.
Alternative: Select File > Print from the Stylus Studio menu.

Printing XML Schema Documentation

To print XML Schema documentation, click the Print tool (or Ctrl + P) on the
Documentation tab. Stylus Studio prints the XML Schema documentation using the
XS3P format. See Generating Documentation for XML Schema on page 643 for more
information.

Saving theXML Schema Diagram as an Image

You can save a graphical image of your XML Schema diagram as a JPEG (.jpg) file or as
an Extended Meta File (.emf). When you save an XML Schema as an image, Stylus Studio
includes the entire XML Schema diagram, not just what is currently visible.
Stylus Studio uses a standard zoom level when saving the image; application zoom level
settings are ignored.
Stylus Studio User Guide

587

Defining XML Schemas

To save an XML Schema diagram as an image:

Select Diagram > Export Image from the menu, or select Export Image from the
shortcut menu on the diagram pane (right-click).
Stylus Studio displays the Save As dialog box.

588

Select the file format (.jpg or .emf) from the Files of type drop-down list.

Specify a name and location for the file and click the Save button. The default name
is the name of the XML Schema document; the default location is the folder in which
the XML Schema document has been saved.

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

Node Properties
The Properties window is available when you are using the Diagram or Tree tab of the
XML Schema Editor. When the Properties window is open, it displays the properties of
the node you click. If you have selected a restricted node from a redefined XML Schema,
Stylus Studio displays a separate section in the lower half of the Properties window for
you to specify the facets, as shown in Figure 292.

Figure 292. Properties Window with Restricted Type Facets

If the Properties window is not visible, select View > Properties from the Stylus Studio
menu.
Tip The Properties window is a dockable window you can drag it out of Stylus Studio and

place it anywhere on your desktop, as shown in Figure 292.

To change the value of a property, click the property field and enter the new value. If only
certain values are allowed, Stylus Studio displays a drop-down list of the valid choices.
Each type of node has its own set of properties. For a description of each property, see
About XML Schema Properties on page 648.

Working with Properties in the Diagram

You can also display and edit properties within the nodes in the diagram. See Displaying
Properties on page 70 for more information on this feature.

Searching for Referencing Nodes

You can use the Find References feature to find all the constructs that reference a
definition you select in the XML Schema diagram. You can search for references to

Global elements

Stylus Studio User Guide

589

Defining XML Schemas

Simple global types

Complex global types

In addition to the current XML Schema, Stylus Studio searches any included or imported
XML Schemas for references.

Search Results
Search results are displayed in the Output window, as shown in Figure 293. Information
in the result includes

The name of the node whose references you are looking for

Searched files (that is, the current XML Schema and any included or imported XML
Schemas)

The location (file URL, and line:column) of the reference

Figure 293. Results of a Search for Referencing Nodes

Pressing F4:

Highlights the first search result

Scrolls the text pane to the referencing node (note the blue marker in the text pane
margin)

Scrolls the diagram pane and highlights the referencing node

Pressing F4 again repeats this action for the next search result.
590

Stylus Studio User Guide

Working with XML Schema in Stylus Studio

To search for referencing nodes in an XML Schema:
1.

Select the XML Schema node for which you want to find referencing nodes.

Right-click, and select Find References from the shortcut menu.

Alternative: Select Diagram > Find References from the Stylus Studio menu.

Stylus Studio User Guide

591

Defining XML Schemas

Getting Started with XML Schema in the Tree View

This section provides a quick tour of the main features of the Tree view in the XML
Schema Editor. It provides instructions that you can follow to define a simple XML
Schema.
This section provides step-by-step instructions for defining the bookstoreTree.xsd XML
Schema document. You should perform the steps in each topic in the order of the topics.
This section covers the following topics:

Description of Sample XML Schema on page 592

Defining a complexType in a Sample XML Schema in the Tree View on page 593

Defining Elements of the Sample complexType in the Tree View on page 598
For instructions for using the Diagram view to define the same XML Schema, see
Defining an XML Schema Using the Diagram Tab Getting Started on page 66.

Description of Sample XML Schema

The genre attribute specifies the style of the publication.

There is always exactly one title element.

The subtitle element is optional.

There must be at least one author element and there can be more. Each author
element contains one first-name element and one last-name element.

Of the following three elements, exactly one must always be present:

592

ISBNnumber

PUBnumber

LOCnumber

The elements must be in the order specified in this list.

Stylus Studio User Guide

Getting Started with XML Schema in the Tree View

Tips for Adding Nodes

To add a node to an XML Schema in the Tree view, click a node that is already in the
schema. Stylus Studio activates the buttons for only those nodes that can be children of
the node you selected. If you hold down the Shift key, Stylus Studio activates only those
buttons that allow you to add nodes that can be siblings of the selected node.

Defining a complexType in a Sample XML Schema in the Tree

View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
The steps for defining the PublicationType complexType are described in the following
sections:

Defining the Name of the Sample complexType in the Tree View on page 593

Adding an Attribute to a Sample complexType in the Tree View on page 594

Adding Elements to a Sample complexType in the Tree View on page 594

Adding Optional Elements to a Sample complexType in the Tree View on page 596

Adding an Element That Contains Subelements to a complexType in the Tree View

on page 596

Choosing the Element to Include in the Sample complexType in the Tree View on
page 597

Defining the Name of the Sample complexType in the Tree View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
To define a complexType in the sample XML Schema:
1.

From the Stylus Studio menu bar, select File > New > XML Schema.
Stylus Studio displays the XML Schema Editor.

At the bottom of the XML Schema Editor, click the Tree tab.
Stylus Studio displays the Tree view of the schema, and the Properties window,
which lists the properties for the selected node in the tree.

Click the Schema node

In the left tool bar, click New complexType

Stylus Studio User Guide

.
.
593

Defining XML Schemas

Stylus Studio displays a field for the new complexType.

Type PublicationType as the name for this new complexType and press Enter.

Click Save

In the Save dialog box that appears, in the URL field, type bookstoreTree.xsd, and
click Save.

Adding an Attribute to a Sample complexType in the Tree View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
To add the genre attribute to the PublicationType complexType:
1.

In the Tree view, click the PublicationType node.

In the left tool bar, click New Attribute Definition

.
In the Tree view, Stylus Studio displays a field for the new attribute.

Type genre as the name of the new attribute and press Enter.
Stylus Studio displays a drop-down list of built-in simpleTypes.

Double-click xsd:string.

Adding Elements to a Sample complexType in the Tree View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
To add the title element, which must appear exactly once, to the PublicationType
complexType:

594

In the Tree view, click the PublicationType node.

In the left tool bar, click New Model Group

.
Stylus Studio displays a drop-down list of group modifiers.

Double-click the sequence modifier.

The sequence modifier indicates that an instance document contains zero, one, or
more of each child element in the order in which they are defined.

In the left tool bar, click New Element Definition

.
In the Tree view, Stylus Studio displays a field for the new element definition.
Stylus Studio User Guide

Getting Started with XML Schema in the Tree View

Type title as the name of the new element and press Enter.
Stylus Studio displays a drop-down list of built-in simpleTypes.

Double-click xsd:string.

Stylus Studio User Guide

595

Defining XML Schemas

Adding Optional Elements to a Sample complexType in the Tree View

This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
To add the optional subtitle element to the PublicationType complexType:
1.

In the Tree view, click the sequence node.

In the left tool bar, click New Element Definition

.
In the Tree view, Stylus Studio displays a field for the new element definition.

Type subtitle as the name of the new element and press Enter.
Stylus Studio displays a drop-down list of built-in simpleTypes.

Double-click xsd:string.

In the Properties window, double-click the Min Occur. field.

Type 0 and press Enter

In the Properties window, double-click the Max Occur. field.

Type 1 and press Enter.

Adding an Element That Contains Subelements to a complexType in the

Tree View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
The PublicationType complexType must include at least one author element. An author
element must include a first-name element and a last-name element.
Each element that can contain subelements is a complexType. Consequently, to add the
author element to the PublicationType complexType, you must first define the authorType
complexType. You can then add an element that is of authorType to the PublicationType
complexType.
To define the authorType complexType:

596

In the XML Schema Editor, click the Schema node.

In the left tool bar, click New complexType

.
Stylus Studio displays a field for the new complexType.

Type authorType as the name for this new complexType and press Enter.
Stylus Studio User Guide

Getting Started with XML Schema in the Tree View

In the left tool bar, click New Model Group

In the drop-down list that appears, double-click the sequence modifier.

In the left tool bar, click New Element Definition

In the field that Stylus Studio displays, type first-name as the name of the new
element and press Enter.

In the drop-down list that appears, double-click xsd:string.

In the Tree view, click the sequence modifier for authorType.

10.

Repeat Step 6 through Step 8, but type last-name as the name of the new element.

Now you can add the author element to the PublicationType complexType:
1.

In the Tree view, click the sequence node under the PublicationType node.

In the left tool bar, click New Element Definition

In the field that Stylus Studio displays, type author as the name of the new element
and press Enter.

In the drop-down list that appears, double-click authorType.

In the Properties window, double-click in the Min Occur. field.

Type 1 and press Enter.

In the Properties window, double-click in the Max Occur. field.

Type unbounded in the Max Occur. field and press Enter.

Choosing the Element to Include in the Sample complexType in the Tree

View
This topic is part of a sequence that begins with Description of Sample XML Schema
on page 592.
In the sample XML Schema, you want PublicationType elements to contain an
ISBNnumber, PUBnumber, or LOCnumber element.
To specify this:
1.

In the Tree view, under the PublicationType node, click the sequence node.

In the left tool bar, click New Model Group

In the drop-down list that appears, double-click the choice modifier.

Stylus Studio User Guide

597

Defining XML Schemas

In the left tool bar, click New Element Definition

In the field that Stylus Studio displays, type ISBNnumber as the name of the new
element and press Enter.

In the drop-down list that appears, scroll until you can double-click xsd:integer, or
type xsd:integer and press Enter.

In the Tree view, click the choice modifier for PublicationType.

Repeat Step 4 through Step 7 two more times. Once for the PUBnumber element and
once for the LOCnumber element.

Click Save
.
Stylus Studio displays a message that indicates that the schema is not valid. Click OK
in the error box. In the Output Window, you can see the following message:
Validating bookstoreTree.xsd...
file://c:\yourDirectory\bookstoreTree.xsd:6,45:
Invalid child 'sequence' in the complexType
The XML document bookstoreTree.xsd is NOT valid (1 errors)

The problem is that there is a sequence element after an attribute element. The
must come first.

sequence element

10.

Right-click the genre node.

11.

In the pop-up menu that appears, click Move Down.

12.

Click Validate Document

and Save

The definition of the PublicationType complexType is now complete and the schema is
now valid.

Defining Elements of the Sample complexType in the Tree View

To define the book, magazine, and newsletter elements in the sample XML Schema:

598

In the Tree tab, click the Schema node.

In the left tool bar, click New Element Definition

In the field that Stylus Studio displays, type book as the name of the new element and
press Enter.

In the drop-down list that appears, double-click PublicationType.

Stylus Studio User Guide

Defining simpleTypes in XML Schemas

Repeat Step 1 through Step 4 two more times. Once for the magazine element and
once for the newsletter element.

Click Save

This is the end of the section that provides instructions for getting started with defining
XML Schemas in the Tree view. The topics that follow this topic provide complete
information for defining the elements that can be in an XML Schema and for working in
the Diagram, Tree, and Text views.

Defining simpleTypes in XML Schemas

Many simpleTypes, such as string and integer, are built in to an XML Schema. You can
define your own simpleType by restricting the range of values provided by a built-in
simpleType. You can also define simpleTypes that are derived from the simpleTypes you
define.
This section covers the following topics:

About simpleTypes in XML Schemas on page 599

Examples of simpleTypes in an XML Schema on page 600

Defining a simpleType in the Diagram View on page 601

Defining a simpleType in the Tree View on page 605

About Facet Types for simpleTypes on page 607

Defining List and Union simpleTypes in the Tree View on page 608

About simpleTypes in XML Schemas

XML Schema defines several kinds of simpleTypes:

Atomic is the term for most of the simpleTypes built in to XML Schema, such as
integer, string, and decimal. They are called atomic because in the context of
XML Schema, no part of an element or attribute of an atomic type has meaning on its
own. It is only the whole instance that has meaning.
Descriptions of the XML Schema built-in types are in the W3C XML Schema Part 2:
Datatypes at http://www.w3.org/TR/xmlschema-2/.

List simpleTypes are sequences of atomic types. All elements of a particular list
simpleType are instances of the same atomic type.

Union simpleTypes are sequences of atomic and list types. However, the elements of
a particular union simpleType can be instances of more than one atomic or list type.
Stylus Studio User Guide

599

Defining XML Schemas

Anonymous simpleTypes are simpleType definitions that are not explicitly named. An
anonymous simpleType can be an atomic, list, or union simpleType. You define an
anonymous simpleType in the element or attribute definition that uses it.
Anonymous simpleTypes are useful when you want to define a type that is used in
only one element or attribute. By specifying an anonymous simpleType, you save the
overhead of explicitly defining the type and specifying a reference to it.

Examples of simpleTypes in an XML Schema

The W3C XML Schema Part 0: Primer specifies the following simpleType in its sample
purchase order schema:

<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{3}-[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>

This specifies that SKU is a simpleType. It is restricted to the values of the base type, which
is xsd:string. This means that for a node that is of type SKU, the possible values are a
subset of the values allowed for the xsd:string type.
The xsd:pattern element specifies that the pattern facet is being applied to the set of
values allowed by the xsd:string type. The value of the xsd:pattern element is an XML
Schema regular expression that specifies the allowable values for nodes of type SKU. In this
example, the regular expression specifies that the value must be three digits, followed by
a hyphen, followed by two uppercase ASCII letters <xsd:pattern value="\d{3}-[AZ]{2}"/>. For information about XML Schema expressions, see the W3C XML Schema
Part 0: Primer at http://www.w3.org/TR/xmlschema-0/.
Elsewhere in the purchase order schema, an attribute definition specifies that SKU is the
type of its value:
<xsd:attribute name="partNum" type="SKU" use="required"/>

An XML document that uses a schema that contains this simpleType definition can
specify the partNum attribute. The parser ensures that the value of the partNum attribute is
in the range specified by the xsd:pattern element. The SKU type itself is not mentioned in
the instance document.

600

Stylus Studio User Guide

Defining simpleTypes in XML Schemas

Following is another example of a simpleType definition from the W3C XML Schema Part
0: Primer. This simpleType, myInteger, is based on the xsd:integer type. It specifies two
facets (minInclusive and maxInclusive), which specify the lower and upper inclusive
bounds of the range of valid values.
<xsd:simpleType name="myInteger">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="10000"/>
<xsd:maxInclusive value="99999"/>
</xsd:restriction>
</xsd:simpleType>

Defining a simpleType in the Diagram View

This section describes the procedures for defining simpleTypes in the Diagram view. It
covers the following topics:

Before You Begin on page 601

Defining an Atomic simpleType on page 601

Specifying a Restriction for a simpleType QuickEdit on page 602

Specifying a Restriction for a simpleType Manually on page 603

Defining List and Union simpleTypes on page 604

Before You Begin

Many of the editing features used in this section are described in Defining an XML
Schema Using the Diagram Tab Getting Started on page 66. You should familiarize
yourself with that material if you have not done so already.

Defining an Atomic simpleType

This topic provides the steps for defining an atomic simpleType in the Diagram view.
In the Diagram view, to define an atomic simpleType:
1.

Right-click the schema node

Select Add > simpleType.

The new simpleType appears in the diagram; its properties are displayed in the
Properties window.

Change the default name to the name of the new simpleType and press Enter.

Stylus Studio User Guide

to display the shortcut menu.

601

Defining XML Schemas

Specifying a Restriction for a simpleType QuickEdit

QuickEdit is a feature that combines commonly-performed editing operations, such as
specifying a restriction for a simpleType. You can also perform this operation in a
different way. See Specifying a Restriction for a simpleType Manually on page 603.
To specify a restriction for a simpleType using QuickEdit:
1.

Right-click the simpleType node

to display the shortcut menu.

Select QuickEdit > Derive by restriction from the shortcut menu.

The Type Derivation dialog box appears.

Figure 294. Type Derivation Dialog Box

The Type Derivation dialog box displays the W3C XML Schema, as well as any
referenced XML Schemas.
3.

Expand the schema (click the plus sign) to display the base types associated with that
XML Schema.

Select the type on which you wish to base the simpleType you are defining and click
OK.
The simpleType is updated with an element that identifies the restricted type:

Figure 295. Restricted Type

In the lower half of the Properties window, Stylus Studio displays a section that
allows you to specify facets values that define the constraint on the range of values
allowed by the base type.

602

Stylus Studio User Guide

Defining simpleTypes in XML Schemas

Click the Name field and select a facet type.

Figure 296. Specifying Facets for a Restricted Type

Stylus Studio displays only those facets that are allowed for the base type you
selected. For a description of each facet, see About Facet Types for simpleTypes on
page 607.
6.

Click the Value field for a facet you want to specify.

Enter a value for the new facet.

To specify another facet, repeat Step 5 through Step 7.

Specifying a Restriction for a simpleType Manually

This procedure describes how to specify a restriction for a simpleType manually. It is an
alternative to the procedure described in Specifying a Restriction for a simpleType
QuickEdit on page 602.
To specify a restriction for a simpleType manually:
1.

Right-click the simpleType node to display the shortcut menu.

Select Add > Restriction from the shortcut menu.

The simpleType is updated with a restriction icon:

Figure 297. Restriction Icon

Stylus Studio User Guide

603

Defining XML Schemas

Select the restriction icon if it is not already selected.

In the Properties window, select the type on which you want to base the simpleType
you are defining from the Base Type field.
At the bottom of the Properties window, Stylus Studio displays a section that allows
you to specify facets values that define the constraint on the range of values
provided by the base type.

Click the Name field and select a facet type.

Figure 298. Specifying Facets for a Restricted Type

Stylus Studio displays only those facets that are allowed for the base type you
selected. For a description of each facet, see About Facet Types for simpleTypes on
page 607.
6.

Click the Value field for a facet you want to specify.

Enter a value for the new facet.

To specify another facet, repeat Step 5 through Step 7.

Defining List and Union simpleTypes

The procedure for defining list and union simple types is similar:
1.

604

Create the simpleType as described in Defining a simpleType in the Diagram View

on page 601.

Stylus Studio User Guide

Defining simpleTypes in XML Schemas

Select the type (list or union) from the shortcut menu (right-click the new simpleType
and select Add > List or Add > Union).

Specify the nodes that comprise the simpleTypes list or union. These types are
restricted to annotations and other simpleTypes.

How you perform this last step depends on whether you are adding new or existing
annotation or simpleType nodes to the list or union.

To add a new, undefined annotation or simpleType to the list or union, right click the
list or union and select Add > Annotation or Add > SimpleType from the shortcut
menu.

To add an existing annotation or simpleType to the list or union, drag the annotation
or simpleType to the list or union, and drop it there, as shown in Figure 299, which
shows SimpleType-6 being added to the union SimpleType-3.

Figure 299. Dragging Nodes to Define Other Nodes

Notice that the pointer changes shape when you place it over an appropriate target
node.

Defining a simpleType in the Tree View

This topic provides the steps for defining an atomic simpleType in the Tree view. When
you are familiar with this procedure, you can adapt it to define list, union, and anonymous
simpleTypes.
In the Tree view, to define an atomic simpleType:
1.

Click the node you want to define a simpleType for. This can be one of the following
types of nodes:

schema

element

attribute

list

union

Stylus Studio User Guide

605

Defining XML Schemas

To define a simpleType as the sibling of another node, click the node and hold down
the Shift key when you click the button in Step 2. You cannot, of course, define a
simpleType as a sibling of the Schema node.

606

In the left tool bar, click New simpleType

. Stylus Studio displays an empty
simpleType field as the last child of the node you selected. If you held down the Shift
key, the field is the last sibling of the selected node.

Type a name for the new simpleType and press Enter.

In the left tool bar, click New Restriction

. A restriction specifies the type that the
new simpleType is derived from. This is the base type.
Stylus Studio displays a scrollable list of XML Schema built-in types, and any
simpleTypes you already defined in this schema. Descriptions of the XML Schema
built-in types are in the W3C XML Schema Part 0: Primer at
http://www.w3.org/TR/xmlschema-0/.

Double-click the simpleType that you want to base your new simpleType on.

In the left tool bar, click New Facet

. A facet specifies a constraint on the range
of values provided by the base type. Stylus Studio displays a scrollable list of XML
Schema facet types. For a description of each facet, see About Facet Types for
simpleTypes on page 607.
You must ensure that you specify a facet that is valid for the specified base type.
Stylus Studio does not prevent you from specifying an invalid facet. The W3C XML
Schema Part: 0 Primer includes a table at http://www.w3.org/TR/xmlschema-0/ that
provides this information.

Double-click the type of facet you want to specify.

In the Properties window, double-click the Value field.

Enter a value for the new facet.

10.

To add another facet, click the restriction node for your simpleType, and repeat Step 6
through Step 9.

Stylus Studio User Guide

Defining simpleTypes in XML Schemas

About Facet Types for simpleTypes

Table 69 provides a brief description of what you should specify as the value of a facet for
a new simpleType. You should consult the XML Schema Recommendation for a complete
definition of each facet and its allowable values.
Table 69. Facet Values for simpleTypes
Facet

Value

enumeration

One allowable value. Add an enumeration facet for each

allowable value. For example:
<xsd:simpleType name="USState">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="AK"/>
<xsd:enumeration value="AL"/>
<xsd:enumeration value="AR"/>

</xsd:restriction>
</xsd:simpleType>

fractionDigits

The maximum number of digits that are allowed in the fractional

portion of values of simpleTypes that are derived from
xsd:decimal.

length

The number of units of length. Units vary according to the base

type. The simpleType must be this number of units of length. For
example, if xsd:string is the base type, you might specify 5 as
the length if you know that each value will be a code that always
has five characters.

maxExclusive

The exclusive upper bound of the range of values allowed for this
simpleType. The value of the simpleType must be less than the
value of maxExclusive.

maxInclusive

The inclusive upper bound of the range of values allowed for this
simpleType. The value of the simpleType must be less than or
equal to the value of maxInclusive.

maxLength

The maximum number of units of length. Units vary according

to the base type. The length of the instances of this simpleType
must be less than or equal to this number of lengths.

Stylus Studio User Guide

607

Defining XML Schemas

Table 69. Facet Values for simpleTypes
Facet

Value

minExclusive

The exclusive lower bound of the range of values allowed for this
simpleType. The value of the simpleType must be more than the
value of minExclusive.

minInclusive

The inclusive lower bound of the range of values allowed for this
simpleType. The value of the simpleType must be equal to or
more than the value of minInclusive.

minLength

The minimum number of units of length. Units vary according to

the base type. The length of the instances of this simpleType
must be equal to or more than this number of lengths.

pattern

A regular expression. The values of the simpleType must be

literals that match this regular expression.

totalDigits

The maximum number of digits that are allowed in values of

simpleTypes that are derived from xsd:decimal.

whiteSpace

Specify one of the following values:

preserve indicates

that no normalization is done. The

value is not changed.
replace indicates that each tab, line feed, and return is
replaced with a space.
collapse indicates that the processing specified by
replace is done, and then contiguous sequences of
spaces are collapsed into one space.

Defining List and Union simpleTypes in the Tree View

Sometimes you need to define a simpleType for a sequence of atomic types. In a list
simpleType, all instances in the sequence must be of the same type. In a union
simpleType, the instances in the sequence can be of different types. The procedure for
defining list and union simpleTypes is the same.

608

Stylus Studio User Guide

Defining complexTypes in XML Schemas

In the Tree view, to define a list or union simpleType:
1.

Click the node you want to define the list or union type for.

In the left tool bar, click New simpleType

. Stylus Studio displays an empty
simpleType field as the last child of the node you selected.

Type a name for the new simpleType and press Enter.

In the left tool bar, click New Aggregator

with two choices.

Double-click list or union.

Define the atomic simpleType of the elements or attributes that are instances of the
list or union type. See Defining simpleTypes in XML Schemas on page 599.

If you are defining a list type you are done. If you are defining a union type, click
the union node and define another atomic simpleType that can be in the union.
Perform this step for each type in the union.

. Stylus Studio displays a pop-up menu

Defining complexTypes in XML Schemas

In an XML Schema, an element that contains only data is a simpleType. Elements with
any other contents are complexTypes. (Attributes are always simpleTypes.) The XML
Schema Recommendation does not include any built-in complexTypes. You must define
each complexType you need.
In the Diagram view, when you define a complexType as a top-level definition, it is a
global declaration. You can specify that any element in the schema is of this
complexType. Similarly, in the Tree view, it is a global declaration when you define a
complexType as a child of the Schema node.
Tip Define the complexType first. Then when you define an element, Stylus Studio includes

your complexTypes name in the menu that lists the available types for your new element.
You can select the name of the complexType from the menu.
You can also define a complexType in the definition of an element. See Defining
Elements That Contain Subelements in XML Schemas on page 623.
Stylus Studio takes care of most of the details for you. But as you define a complexType,
it is helpful to keep in mind that a complexType node can have only one child node that is
a model group modifier. However, this modifier node can have any number of child nodes
that are modifiers. In this way, you can specify any number of modifiers in a
Stylus Studio User Guide

609

Defining XML Schemas

complexType. Each modifier controls the occurrence of its child nodes. You can specify
the same modifier more than once. For example, you might want to specify the sequence
modifier, with some child nodes, then the choice modifier with some child nodes, and
then the sequence modifier again with other child nodes.
This section discusses the following topics:

Defining complexTypes That Contain Elements and Attributes Diagram View on

page 610

Defining complexTypes That Contain Elements and Attributes Tree View on

page 614

Defining complexTypes That Mix Data and Elements on page 616

Defining complexTypes That Contain Only Attributes on page 618

Defining complexTypes That Contain Elements and Attributes

Diagram View
To define a complexType in the Diagram view:
1.

Right-click the schema node

In the shortcut menu, select Add > ComplexType.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> ComplexType menu and from the Add button
.
The new complexType is added to the XML Schema. It is displayed in the diagram
and in the text pane (if you have it open). The properties for the new complexType are
displayed in the Properties window.

Adding Nodes to a complexType

Once you have created a complexType, you can further define it by adding sequences,
elements, and other nodes. The basic procedure for adding nodes to a complexType is to:

610

Select the node.

Use the menus or tool bar to add the node.

Fully describe the complexType and its nodes by editing values in the Properties
window.

Stylus Studio User Guide

Defining complexTypes in XML Schemas

You can use this procedure to add the following nodes to a complexType:

all

annotation

anyAttribute

attribute

attributeGroup

choice

group

sequence

Next steps vary according to the constraints on the elements in the complexType. The
following instructions show how to achieve some typical constraints.

Choosing an Element
Suppose you want to define a complexType that contains exactly one element, and that
element can be one of several different elements. In XML Schema, you do this by defining
xsd:choice.
To define xsd:choice in the Diagram tab:
1.

Right-click the icon that represents your new complexType.

In the shortcut menu that appears, select Add > Choice.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> Choice menu and from the Add button
.
Stylus Studio displays the choice icon
alongside the complexType icon.

Right-click the choice icon and select Add > Element, or use the Add button
A element is added to the choice icon.

Figure 300. Defining Choice for a complexType

Make sure the new element is selected. In the Properties window, click the Type field.

Enter or select the type of the element.

Repeat Step 3 through Step 5 for each element that might be in the complexType.

Stylus Studio User Guide

611

Defining XML Schemas

Including All Elements

Suppose you want to define a complexType that contains a number of elements, the
elements can be in any order, and there must be zero or one of each element. In XML
Schema, you do this by defining xsd:all.
To define xsd:all in the Diagram tab:
1.

Right-click the icon that represents your new complexType.

In the shortcut menu that appears, select Add > All.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> All menu and from the Add button
.
Stylus Studio displays the all icon
alongside the complexType icon.

Right-click the choice icon and select Add > Element, or use the Add button
A element is added to the all icon.

Make sure the new element is selected. In the Properties window, click the Type field.

Enter or select the type of the element.

If the element is required, go to Step 7. If the element is optional, click the Min Occur.
field in the Properties window, and type a zero (0).

If there must always be exactly one of this element, go to Step 8. If there can be more
than one of this element, click the Max Occur. field in the Properties window, and
enter the maximum number allowed or click unbounded in the drop-down list.

Repeat Step 3 through Step 7 for each element that can be in the complexType.

Specifying the Sequence of Elements

Suppose you want to define a complexType that contains a number of elements in a
particular order. The default is that each element must appear exactly once. However,
some elements are optional, and some elements can appear more than once. In XML
Schema, you do this by defining xsd:sequence.
To define xsd:sequence in the Diagram tab:

612

Right-click the icon that represents your new complexType.

In the shortcut menu that appears, select Add > Sequence.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
.
> Sequence menu and from the Add button
Stylus Studio User Guide

Defining complexTypes in XML Schemas

Stylus Studio displays the sequence icon

alongside the complexType icon.

Right-click the sequence icon and select Add > Element, or use the Add button
A element is added to the sequence icon.

Make sure the new element is selected. In the Properties window, click the Type field.

Enter or select the type of the element.

If the element is required, go to Step 7. If the element is optional, click the Min Occur.
field in the Properties window, and type a zero (0).

Repeat Step 3 through Step 7 for each element that can be in the complexType.

Reordering Nodes
If you make a mistake in the order in which you specify nodes in your XML Schema
(when specifying elements in a sequence, for example), you can rearrange them.
To reorder nodes in the diagram view:
1.

Click the node you want to move.

Click the Move Up

or Move Down
from the Stylus Studio tool bar until the
node is positioned where you want it.
Alternative: This operation is also available from the XMLSchema menu and from the
nodes shortcut menu.

Combining the Sequence and Choice Modifiers

Suppose you want to define a complexType that contains a number of elements in a
particular order, but some of them are optional, and you want to ensure that only one
element from a particular group of elements is present. In other words, you need to
combine the use of the sequence and choice modifiers. To define this, you must define a
sequence modifier first. You can then define sequence and choice modifiers that are
children of the initial sequence modifier.

Stylus Studio User Guide

613

Defining XML Schemas

Defining complexTypes That Contain Elements and Attributes

Tree View
The purchaseOrder.xsd sample document contains the following complexType definition.
This complexType defines three elements, refers to a fourth element, and defines an
attribute.
<xsd:complexType name="PurchaseOrderType">
<xsd:sequence>
<xsd:element name="shipTo" type="USAddress"/>
<xsd:element name="billTo" type="USAddress"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="items" type="Items"/>
</xsd:sequence>
<xsd:attribute name="orderDate" type="xsd:date"/>
</xsd:complexType>

In the Tree view, to define a complexType with a similar structure:

614

Click the Schema node.

In the left tool bar, click New complexType

displays a field for the new complexType.

Type a name for this new complexType and press Enter.

In the left tool bar, click New Model Group

menu that lists the group modifiers.

Double-click the modifier you want. For a description of each modifier, see Model
Group Properties in XML Schemas on page 655.
You can specify any number of modifiers in a complexType. Each modifier controls
the occurrence of its child nodes. You can specify the same modifier more than once.
For example, you might want to specify the sequence modifier, with some child nodes,
then the choice modifier with some child nodes, and then the sequence modifier again
with other child nodes.

For each element that you want to define in this complexType with the selected
modifier, perform the following steps:

. In the Tree view, Stylus Studio

. Stylus Studio displays a pop-up

Click the modifier name in the Tree view.

In the left tool bar, click New Element Definition

. In the Tree view, Stylus
Studio displays a field for the new element definition.

Stylus Studio User Guide

Defining complexTypes in XML Schemas

Type a name for the new element and press Enter. Stylus Studio displays a popup menu that lists the built-in simpleTypes and simpleTypes you defined.

Double-click the type for the new element.

In the Properties window, you can double-click the field for any property to set
the value for that property.
For example, you can specify 0 for the Min Occur. property and 1 for the Max
property. The effect is that the element is optional.

For each element or group that you want to refer to in this complexType with the
selected modifier, perform the following steps:
a.
b.

Click the modifier name in the Tree view.

In the left tool bar, click New Reference to Element
or New Reference to
. Stylus Studio displays a pop-up menu that lists the elements or
groups defined in the schema.

Group
c.
8.

Double-click the element or group you want to reference.

To define an attribute in this complexType:

Click the name of the complexType in the Tree view.

In the left tool bar, click New Attribute

displays a field for the new attribute.

Type a name for the new attribute and press Enter. Stylus Studio displays a popup menu that lists the built-in simpleTypes and the simpleTypes you defined in
this schema.

Double-click the type of the new attribute.

. In the Tree view, Stylus Studio

To reference an attribute or attributeGroup in this complexType:

Click the name of the complexType in the Tree view.

In the left tool bar, click New Reference to Attribute

or New Reference to
. Stylus Studio displays a pop-up menu that lists the attributes
Attribute Group
or attributeGroups defined in the schema.

Double-click the attribute or attributeGroup you want to reference.

Stylus Studio User Guide

615

Defining XML Schemas

Defining complexTypes That Mix Data and Elements

Suppose you want to define a complexType that mixes elements and data. For example,
you have an XML document with contents such as the following:
<letter>
<salutation>
Dear Mr.
<name>Robert Smith</name>
,
</salutation>
Your order of
<quantity>1 </quantity>
<productName>Baby Monitor </productName>
shipped from our warehouse on
<shipDate>2001-04-21</shipDate>
.
</letter>

The letter element and salutation element have element and data children. You must
define complexTypes for both the letter and the salutation elements. Their Mixed
property value must be set to true. The Mixed property is the one that allows an element
to contain both elements (<shipDate>, for example) and raw data (Dear Mr. for example)
as children.
This section describes how to achieve this using both the Diagram and Tree views.

Diagram View
To define a complexType that mixes data and elements:

616

Create a complexType as described in Defining complexTypes That Contain

Elements and Attributes Diagram View on page 610.

In the Properties window, click the Mixed field.

In the drop-down menu that appears, click true.

Stylus Studio User Guide

Defining complexTypes in XML Schemas

Tree View
In the Tree view, to define a complexType that mixes data and elements:
1.

Click the Schema node.

In the left tool bar, click New complexType

displays a field for the new complexType.

Type a name for this new complexType and press Enter.

In the Properties window, double-click the Mixed field.

Double-click true.

In the left tool bar, click New Model Group

menu that lists the group modifiers.

Double-click the modifier you want. For a description of the modifiers, see Model
Group Properties in XML Schemas on page 655. For the rest of this procedure,
assume that you double-click the sequence modifier. By default, the elements that are
children of this node each appear exactly once. If you want an element to be optional,
or if you want an element to appear more than once, specify appropriate values for the
properties for minimum occurrence and maximum occurrence.

For each element that you want this complexType to contain:

. In the Tree view, Stylus Studio

. Stylus Studio displays a pop-up

In the left tool bar, click New Element Definition

. In the Tree view, Stylus
Studio displays a field for the new element definition.

Type a name for the new element and press Enter. Stylus Studio displays a popup menu that lists the built-in simpleTypes and any types already defined in the
schema.

Double-click the type for the new element.

Stylus Studio User Guide

617

Defining XML Schemas

Defining complexTypes That Contain Only Attributes

An XML Schema allows you to create groups of attributes. This makes it easy to create a
complexType that contains only attributes. The first step is to create an attributeGroup.
You can then create a complexType and add a reference to the attributeGroup to the
complexType.

Diagram View
To define a complexType that contains only attributes:
1.

Right-click the schema node

In the shortcut menu, select Add > AttributeGroup.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> AttributeGroup menu and from the Add button
.
The new attributeGroup is added to the XML Schema. It is displayed in the diagram
and in the text pane (if you have it open). The properties for the new attributeGroup
are displayed in the Properties window.

Right-click the new attributeGroup.

In the shortcut menu that appears, select Add > Attribute.

The new attribute is added to the attributeGroup.

Figure 301. attributeGroup with New Attribute

618

Make sure the new attribute is selected. In the Properties window, click the Data Type
field.

Enter or select the type of the attribute.

Repeat Step 3 through Step 6 for each attribute that you want to be in the group.

Create a complexType as described in Defining complexTypes That Contain

Elements and Attributes Diagram View on page 610.

Drag the attributeGroup to the complexType.

Stylus Studio User Guide

Defining Elements and Attributes in XML Schemas

Tree View
To define a complexType that contains only attributes:
1.

Click the Schema node.

In the left tool bar, click New Attribute Group

displays a field for new attributeGroup.

Enter a name for the attributeGroup.

In the left tool bar, click New Attribute Definition

displays a field for the new attribute definition.

Enter a name for the new attribute. Stylus Studio displays a scrollable, pop-up menu
that lists the built-in simpleTypes and any previously defined simpleTypes.

Double-click the type of the new attribute.

For each additional attribute you want to add to the group, click the name of the
attributeGroup in the Tree view, and repeat Step 4 through Step 6.

Click the Schema node.

In the left tool bar, click New complexType

displays a field for the new complexType.

10.

Type a name for the new complexType and press Enter.

11.

In the left tool bar, click New Reference to Attribute Group

. Stylus Studio
displays a pop-up menu that contains a list of attributeGroups.

12.

Double-click the attributeGroup that you want this complexType to contain.

. In the Tree view, Stylus Studio

Defining Elements and Attributes in XML Schemas

You can define an element or attribute as part of a complexType. You can also define an
element or an attribute as a top-level item. In other words, in the XML document that
defines the XML Schema, the element or attribute is a child of the xsd:schema element.
An element or attribute that is an immediate child of the xsd:schema element is a global
element or attribute.
A global element or attribute cannot

Contain a reference to another element or attribute

Specify values for the minOccurs, maxOccurs, or use properties

Stylus Studio User Guide

619

Defining XML Schemas

This section covers the following topics:

Defining Elements That Carry Attributes and Contain Data in XML Schemas on
page 620

Defining Elements That Contain Subelements in XML Schemas on page 623

Adding an Identity Constraint to an Element on page 624

Defining Elements That Carry Attributes and Contain Data in XML

Schemas
You might want to define an element that carries attributes and contains data, but does not
contain subelements. In the purchaseOrder.xsd document, an example of this is the
internationalPrice element, shown here in the Diagram tab.

Figure 302. internationalPrice Element in purchaseOrder.xsd

This element has a currency attribute, and it contains data based on the xsd:decimal
simpleType.

Diagram View
To define a complexType that contains only attributes:

620

Right-click the schema node

In the shortcut menu, select Add > Element.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> Element menu and from the Add button
.

Stylus Studio User Guide

Defining Elements and Attributes in XML Schemas

The new element is added to the XML Schema. It is displayed in the diagram and in
the text pane (if you have it open). The properties for the new element are displayed
in the Properties window.
3.

Create a complexType of the element right-click the element and select Add >
ComplexType.

Make sure the new complexType is selected.

Click the QuickEdit button and select Derive by extension. This choice lets you
extend a base simpleType.
The Type Derivation dialog box appears.

Figure 303. Type Derivation Dialog Box

Expand the W3C XML Schema and select the simpleType on which you want to base
the data allowed by the complexType.

Click OK.
The XML Schema is updated with the elements new definition. Figure 304 shows an
extension of the decimal simpleType.

Figure 304. complexType with simpleContent Defined

The simpleContent node ( ) specifies that the complexType can contain only data
and attributes. It cannot contain subelements.
8.

To add an attribute, right-click the element and select Add > Attribute.

Stylus Studio User Guide

621

Defining XML Schemas

Tree View
To define an element that contains raw data and carries attributes:
1.

Click the Schema node.

In the left tool bar, click New Element Definition

displays a field for the new element definition.

Type the name of the element and press Enter twice. If you press Enter once, Stylus
Studio displays a pop-up menu that lists the possible types for the new element. You
need to define a new type, so you cannot select from this list. If the pop-up menu does
appear, press Enter or click outside the menu. You should now have a named element
with no type specified.

In the left tool bar, click New complexType

displays a field for the new complexType.

In the left tool bar, click New Content

In the drop-down list that appears, double-click simpleContent. This is the Content
Type property. When the content type is simpleContent, the complexType you are
defining can contain data and attributes. It cannot contain subelements.

If you want the contained data to be one of the simpleTypes already defined with no
restrictions, click New Extension
in the left tool bar.
Stylus Studio displays a scrollable, drop-down list of the simpleTypes built in to XML
Schema and previously defined in the current schema.

If you clicked New Extension, double-click the type of the data you want this element
to contain. Go to Step 9.
If you clicked New Restriction, follow these steps:

622

. In the Tree view, Stylus Studio

. Stylus Studio displays a drop-down list.

Double-click the simpleType whose values you want to restrict.

In the left tool bar, click New Facet

Double-click the type of facet you want to specify.

In the Properties window, double-click the Value field.

Enter a value for the new facet.

To add another facet, click the restriction node for the simpleType, and repeat
Step b.

. Stylus Studio displays a pop-up menu.

In the left tool bar, click the complexType node that you created in Step 4.
Stylus Studio User Guide

Defining Elements and Attributes in XML Schemas

10.

In the left tool bar, click New Attribute Definition

displays a field for the new attribute definition.

. In the Tree view, Stylus Studio

11.

Type a name for the new attribute and press Enter. Stylus Studio displays a scrollable,
drop-down list of the possible types for the new attribute.

12.

Double-click the attribute type. If you want to, specify a value for the attributes
Default or Fixed Value property in the Properties window.

13.

To add additional attributes, repeat Step 9 through Step 12.

Defining Elements That Contain Subelements in XML Schemas

An element that contains subelements is a complexType. Consequently, you can define an
element that contains subelements in either of the following ways:

Define a top-level complexType. That is, it is a child of the xsd:schema node. In the
complexType definition, define the subelements. Elsewhere in the schema, define an
element that uses the complexType you defined.

Define an element that is a child of the xsd:schema node or a Model Group node. In
the element definition, define a complexType that contains your subelements.
To define a complexType that contains elements, see Defining complexTypes That
Contain Elements and Attributes Diagram View on page 610 or Defining
complexTypes That Contain Elements and Attributes Tree View on page 614.

Diagram View
To define an element and define subelements in the element definition:
1.

Right-click the schema node

In the shortcut menu, select Add > Element.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
> Element menu and from the Add button
.
The new element is added to the XML Schema. It is displayed in the diagram and in
the text pane (if you have it open). The properties for the new element are displayed
in the Properties window.

Right-click the new element and click QuickEdit. Select one of the following from the
QuickEdit menu:

Add Elements Sequence

Stylus Studio User Guide

623

Defining XML Schemas

Add Elements Choice

Add Elements All

Add Elements Any

Stylus Studio updates the element definition to include a complexType with the
sequence, choice, all, or any element you selected in the previous step.
4.

Add subelements to the element you created in Step 3.

Tree View
In the Tree view, to define an element and define subelements in the element
definition:
1.

Click the Schema node or a Model Group (all, any, choice, sequence) node.

In the left tool bar, click New Element Definition

Enter the name for your new element. Stylus Studio displays a pop-up menu that lists
the built-in simpleTypes and any simple or complexTypes already defined in your
schema.

Press Enter again. Rather that using a type that is already defined, you want to define
a new complexType in the definition of your element. You do not want to assign a type
to your new element.

In the left tool bar, click New complexType

Enter a name for the new type.

At this point, the procedure for defining a complexType in the definition of an element is
the same as defining a complexType as a child of the Schema node. See Defining
complexTypes That Contain Elements and Attributes Tree View on page 614.

Adding an Identity Constraint to an Element

XML Schemas provide a feature that is similar to the DTD ID identity constraint. In a
DTD, the value of an ID attribute must be unique within an XML document. In XML
Schemas, the type of an identity constraint can be unique, key, or keyref. You use XPath
expressions to define the scope of the constraint.
You associate an identity constraint with an element.

A unique identity constraint forces the result of evaluation of an XPath expression to

be unique. Stylus Studio evaluates the XPath expression against the element for which
624

Stylus Studio User Guide

Defining Elements and Attributes in XML Schemas

you define the identity constraint. If the element is present, the result must be unique
among the children of that element.
A key identity constraint specifies that the fields that form the expression must be
present in all instance documents. For example, if a key is based on date and number
attributes, the date and number attributes must always be specified.
A keyref identity constraint is equivalent to the IDREF attribute in DTDs. It specifies
that the contents of a field in the instance document is the value of a key that is defined
in another document. For example, a Quote document would have a reference to the
RFQ that originated it.

This section covers the following topics:

Example of an Identity Constraint on page 625

Diagram View on page 626

Tree View on page 627

Example of an Identity Constraint

This topic provides an example of an element with an identity constraint. Introductory
information about identity constraints is in Adding an Identity Constraint to an Element
on page 624. See also Tree View on page 627.
Suppose you define the following element in an XML Schema:
<element name="purchaseReport">
<complexType>
<sequence>

Stylus Studio User Guide

625

Defining XML Schemas

In an XML document that uses this schema, you could define the following elements:
<purchaseReport>
<parts>
<part number="00-01-02" vendor="IBM" quantity="10"/>
<part number="01-01-02" vendor="BEAS" quantity="1"/>
...
</parts>
</purchaseReport>

If you want to enforce that there is just one part element for each product that has been
purchased, you add the following to the previous XML Schema example:
... [previous definition]
</sequence>
</complexType>
<unique name="pNumKey">
<selector xpath="parts/part"/>
<field xpath="@number"/>
<field xpath="@vendor"/>
</unique>
</element>

The schema validator starts with an initial context set that contains purchaseReport
elements. It runs the XPath expression parts/part to obtain the data set to be checked. In
this example, this is the two part elements. The schema validator then gathers the values
from the number and vendor attributes, and builds a key from these values. It then uses the
key to check that there are no part elements that have the same tuple.

Diagram View
To specify an identity constraint:

626

Right-click the element for which you want to specify the identity constraint.

Select Add > and then Key, KeyRef, or Unique from the menu.

Right-click the new identity constraint, and select Selector.

In the Properties window, specify the XPath expression that identifies the set of
elements to which the identity constraint applies.

Return to Step 3 and select Field.

Stylus Studio User Guide

Defining Elements and Attributes in XML Schemas

In the Properties window, specify the XPath expression that identifies the element or
attribute for each element identified by the selector element that has to be unique.

Tree View
This topic provides the procedure for specifying an element with an identity constraint.
Introductory information about identity constraints is in Adding an Identity Constraint to
an Element on page 624. See also Example of an Identity Constraint on page 625.
To specify an identity constraint:
1.

Click the element for which you want to specify the identity constraint.

In the XML Schema left-side tool bar, click

In the drop-down list that Stylus Studio displays, double-click unique, key, or keyref.

In the Properties window, double-click the Name field and enter a name for the
identity constraint.

If you selected keyref, then in the Properties window, double-click the Refer field and
enter the name of the key definition.

In the tree representation, click the identity constraint you just defined.

In the left tool bar, click New Selector/Key

In the drop-down list that Stylus Studio displays, double-click selector. You must
define exactly one selector for each identity constraint.

In the Properties window, double-click the XPath Expression field and enter an
XPath expression that returns the element for which you are specifying a constraint.

10.

Click the unique, key, or keyref identity constraint you defined in Step 3.

11.

In the left tool bar, click New Selector/Key

12.

In the drop-down list that Stylus Studio displays, double-click field. You must define
one or more fields for each identity constraint. A field can be whatever the XPath
expression (defined in the next step) retrieves.

13.

In the Properties window, double-click the XPath Expression field and enter an
XPath expression that returns the element or attribute that is the key or one of the keys
for the constraint. XPath expressions associated with fields return the data that define
the key for each element returned by the selector XPath expression.

14.

Repeat Step 10 through Step 13 for each additional key field.

Stylus Studio User Guide

627

Defining XML Schemas

Defining Groups of Elements and Attributes in XML

Schemas
The XML Schema Recommendation allows you to specify groups of elements and groups of
attributes. Here is an example of an element group, purchaseType:
<xsd:group name="purchaseType">
<xsd:choice>
<xsd:element name="retail"/>
<xsd:element name="internet"/>
<xsd:element name="mailOrder"/>
</xsd:choice>
</xsd:group>

Specification of a group makes it easier to update the schema. You only need to update
the group definition. There is no need to change the references to the group.
Here is an example of an attributeGroup, deliveryDetail.
<xsd:attributeGroup name="deliveryDetail">
<xsd:attribute name="method"/>
<xsd:attribute name="vendor"/>
<xsd:attribute name="dateShipped"/>
<xsd:attribute name="dateArrived"/>
</xsd:attributeGroup>

This section discusses the following topics:

Defining Groups of Elements in XML Schemas Diagram View on page 628

Defining Groups of Elements in XML Schemas Tree View on page 629

Defining attributeGroups in XML Schemas Diagram View on page 630

Defining attributeGroups in XML Schemas Tree View on page 631

Defining Groups of Elements in XML Schemas Diagram View

To define a group of elements:

628

Define the elements that you want to be in the group. See Defining Elements and
Attributes in XML Schemas on page 619.

Right-click the schema node

In the shortcut menu, select Add > Group.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
.
> Group menu and from the Add button

Stylus Studio User Guide

Defining Groups of Elements and Attributes in XML Schemas

The new group is added to the XML Schema. It is displayed in the diagram and in the
text pane (if you have it open). The properties for the new group are displayed in the
Properties window.
4.

Specify the group name in the Name property in the Properties window.

Right-click the new group.

In the shortcut menu, select Add > and then select the modifier for the group of
elements All, Choice, or Sequence. In the Properties window, click the fields for
the Min Occur. and Max Occur. properties to specify their values. These properties
determine how often the group of the elements with the selected modifier can appear.

Drag the elements defined in Step 1 and drop them on the all, choice, or sequence
modifier created in Step 6.

Alternative
If you prefer, you can create the element group first, define the modifier for the group
elements, and then add new elements to the group by right-clicking on the modifier and
selecting Add > Element. If you do this, you must then define each of the elements you
added to the group.

Defining Groups of Elements in XML Schemas Tree View

To define a group of elements:
1.

Define the elements that you want to be in the group. See Defining Elements and
Attributes in XML Schemas on page 619.

Click the Schema node.

In the left tool bar, click New Group

field for the new group.

Type a name for the group of elements and press Enter.

In the left tool bar, click New Model Group

. Stylus Studio displays a pop-up
menu that lists the model group modifiers. See Model Group Properties in XML
Schemas on page 655.

Double-click a modifier that applies to at least one element that will be in the group.

Stylus Studio User Guide

. In the Tree view, Stylus Studio displays a

629

Defining XML Schemas

In the Properties window, double-click the fields for the Min Occur. and Max Occur.
properties to specify their values. These properties determine how often the subgroup
of the elements with the selected modifier can appear.

For each element that you want to apply the selected modifier to, perform these steps:

Click New Reference to Element

. Stylus Studio displays a pop-up menu that
lists the elements defined in the schema.

Double-click the element you want to add to the group.

Click the modifier to add another element reference.

To add more elements to the group and specify a different modifier for them, click the
name of the group in the Tree view, and repeat Step 5 through Step 8.

In any location where you can add a model group, you can also add a reference to a model
group definition.

Defining attributeGroups in XML Schemas Diagram View

You define attributeGroups in much the same way that you define element groups by
creating the attributes you want to add to the attributeGroup, creating the attributeGroup,
and then dragging-and-dropping the attributes in the attributeGroup. As with element
groups, you can define the attributeGroup first and then add new attributes to it, if you
prefer. The following procedure describes how to create an attributeGroup by creating the
attributes at the same time you create the attributeGroup.
To define an attributeGroup:

630

Right-click the schema node

In the shortcut menu, select Add > AttributeGroup.

Right-click the new attributeGroup.

Stylus Studio User Guide

Defining Groups of Elements and Attributes in XML Schemas

In the shortcut menu that appears, select Add > Attribute.

The new attribute is added to the attributeGroup.

Figure 305. attributeGroup with New Attribute

Make sure the new attribute is selected. In the Properties window, click the Data Type
field.

Enter or select the type of the attribute.

Repeat Step 3 through Step 6 for each attribute that you want to be in the group.

Defining attributeGroups in XML Schemas Tree View

To define an attributeGroup:
1.

Click the Schema node.

In the left tool bar, click New Attribute Group

displays a field for the new attributeGroup.

Type a name for the attributeGroup and press Enter.

In the left tool bar, click New Attribute Definition

displays a field for the new attribute definition.

Type a name for the new attribute and press Enter. Stylus Studio displays a scrollable,
pop-up menu that lists the built-in simpleTypes and any previously defined
simpleTypes.

Double-click the type of the new attribute.

For each additional attribute you want to add to the group, click the name of the
attributeGroup in the Tree view, and repeat Step 4 through Step 6.

Stylus Studio User Guide

. In the Tree view, Stylus Studio

631

Defining XML Schemas

Adding Comments, Annotation, and Documentation

Nodes to XML Schemas
The XML Schema Recommendation provides comment and annotation nodes for you to
provide information that documents an XML Schema. You can add these nodes to any
node in an XML Schema.
The difference between comments and annotations is that a human being must read a
comment node for it to have meaning. An annotation element allows you to specify nodes
that a stylesheet can operate on.

Comments
You cannot add comments in the Diagram tab.
To add comments in the Tree tab:
1.

Click any node in your schema.

In the left tool bar, click New Comment

a field for the comment.

Type your comment and press Enter.

. In the Tree view, Stylus Studio displays

Annotations
You use an annotation element to provide information about the XML Schema. You can
annotate any node in your XML Schema. The annotation element always contains at least
one appInfo or documentation node. Any text you want to enter must be entered in one of
these nodes.

Diagram View
When you create an annotation in the Diagram tab, you create the element and specify its
subelement (appInfo or documentation) in the Diagram tab. You can further describe the
node

In the Diagram tab, by editing the node properties directly

In the Properties window

In the Text pane

632

Stylus Studio User Guide

Adding Comments, Annotation, and Documentation Nodes to XML Schemas

To add an annotation:
1.

Right-click the node you want to annotate.

Select Add > Annotation from the shortcut menu.

.
The annotation icon appears in the Diagram tab

Right-click the annotation icon and select the type of annotation you want to define
appInfo ( )or documentation (
).

In the text pane, type the text for the appInfo or documentation node.
Stylus Studios backmapper identifies the line representing the element you created
in Step 3 in the text pane on the Diagram.

Tip

Tree View
To add an annotation:
1.

Click the node you want to annotate.

In the left tool bar, click New Annotation

Annotation node.

In the left tool bar, click New Documentation

If you added documentation, in the Properties window, double-click the Source field
and type the URL or file path for the documentation you want to include in the
schema, and press Enter.
Double-click the Language field and enter the language of the contents of the source
file.

In the left tool bar, click New Text

for the new text.

. Stylus Studio creates and selects an

or New Application Info

. In the Tree view, Stylus Studio displays a field

Moving a Comment or Annotation

If the parent of the new comment or annotation node has more than one child, you can
move the comment or annotation with the up or down arrow. However, you cannot move
the comment or annotation out of the scope of its parent.

Stylus Studio User Guide

633

Defining XML Schemas

Example
In an XML Schema, you might have a comment node such as the following:
<xsd:schema ...>

<xsd:element name="..."/>

The contents of a comment node have meaning only when a person reads them. However,
the contents of annotation nodes can be operated on. For example:
<xsd:schema ... >
<xsd:element name="foo">
<xsd:annotation>

<xsd:documentation language="en">
This is a <b>foo</b> element. Use it for ...
</xsd:documentation>
<xsd:documentation language="jp">
xksnjgfyre fvhfdbvhjds
</xsd:documentation>
</xsd:annotation>
</xsd:element>
...

You can apply an XSLT stylesheet to this XML Schema document. The stylesheet could
generate an HTML manual by extracting the Documentation nodes in the desired
language:
<xsl:stylesheet ... >
<xsl:template match="xsd:element">
<xsl:apply-templates select=

"xsd:annotation/xsd:documentation[@language='en']"/>
</xsl:template>
...

634

Stylus Studio User Guide

Defining Notations

Defining Notations
A notation is an unparsed entity. It is a name for something that you cannot express in
terms of XML. For example, suppose you have an XML file that represents a press
release. You can define a notation named logo that points to a JPEG image. You can place
the notation in the XML file in the location where you want the logo. See
http://www.w3.org/TR/REC-xml#Notations for more information on the notation element.
Note A notation element is always described as a child of the schema element.

Diagram View
To define a notation:
1.

Right-click the schema node

In the shortcut menu, select Add > Notation.

Alternatives: This operation is also available from the XMLSchema > Diagram > Add
.
> AttributeGroup menu and from the Add button
The new notation is added to the XML Schema. It is displayed in the diagram and in
the text pane (if you have it open). The properties for the new notation are displayed
in the Properties window.

Specify the details of the notation node in the Properties window.

Tree View
To define a notation:
1.

Click the schema node.

In the left tool bar, click New Notation

In the field that Stylus Studio displays, enter the name of the notation.

In the Properties window, double-click the Public ID field and enter the public ID.
The public ID is a unique string that refers to the location of the external data, but it
leaves the resolution of the location to some interpretations, for example,
MyCompany//LOGO//JPEG.

In the Properties window, double-click the System ID field and enter the system ID.
The system ID is the URL that Stylus Studio uses to physically locate the external
data, for example, http://www.mycompany.com/mylogo.jpg.

Stylus Studio User Guide

635

Defining XML Schemas

Referencing External XML Schemas

Support for referencing external XML Schemas is available only in Stylus Studio
XML Enterprise Suite and Stylus Studio XML Professional Suite.
If you want, you can reference definitions from other XML Schemas in your XML
Schema document. You might want to do this if you want to simply reuse existing
definitions as-is, or if you wan to use an existing definition as the base for a type that you
want to modify in your XML Schema.
This section covers the following topics:

Ways to Reference XML Schemas on page 636

Where You Can Reference XML Schemas on page 637

Referencing XML Schemas in the Tree View on page 640

Redefining Nodes on page 641

Ways to Reference XML Schemas

There are three ways to reference XML Schema:

Including

Importing

Redefining
This section describes each of these techniques and how they can be used. In these
descriptions, we use the term referenced XML Schema to indicate the XML Schema that
is being included, imported, or redefined; and base XML Schema to indicate the XML
Schema in which the referenced schema is being included, imported, or redefined.

Including an XML Schema

When reference an XML Schema by including it, the included XML Schema augments
the base XML Schema. Both documents are effectively combined, and they both define
the same XML Schema. complexTypes defined in the included XML Schema can be used
as the base for new types you might use a periodicals complexType from the included
XML Schema to define weekly and quarterly types for example. Both the included XML
Schema and the base XML Schema must have the same target namespace. You can
include multiple XML Schemas in a base XML Schema.

636

Stylus Studio User Guide

Referencing External XML Schemas

Importing an XML Schema

When you reference an XML Schema by importing it, the base XML Schema and the
imported XML Schema must have difference namespaces. The base XML Schema can
the reference parts of the imported XML schema using a prefix whose namespace is
defined in the imported XML Schema, for example. You can import multiple XML
Schemas in a base XML Schema.

Redefining an XML Schema

Referencing an XML Schema by redefining it is similar to including it, with one important
difference: when you redefine an XML Schema in the base XML Schema, you can
redefine the definitions of the referenced XML Schemas complexTypes, simpleTypes,
groups, and attributeGroups. For example, suppose you release version 1 of an XML
Schema. When you need to release version 2 of the XML Schema, you can reference
version 1 by redefining it in version 2, which allows you to change the definition of a
given node to include a new attribute.
The original complexTypes, simpleTypes, groups, and attributeGroups in the redefined
XML Schema are completely masked. They are redefined using extensions and
restrictions. An extension extends the base type declaring a new element, for example.
A restriction constrains the base type.

Where You Can Reference XML Schemas

You can reference external XML Schemas in the Tree or Diagram tabs. In the text pane of
the Diagram tab and the Tree tab, Stylus Studio displays the referenced XML Schema, but
they do not display its contents. For example, in the Tree view, you cannot expand the
node for an included XML Schema.

Stylus Studio User Guide

637

Defining XML Schemas

In the Diagram tab, Stylus Studio displays complete information for any definitions in
referenced XML Schema. You can toggle between diagram views of the base and
referenced XML Schemas using the definition browser.

Figure 306. You Can View Referenced Schemas

If you select a referenced schema from the definition browser, as shown in Figure 306,
Stylus Studio changes the diagram view to display the referenced schemas structure. If
you selected a redefined XML Schema, for example, you could modify its complexType
definitions there.

What to Do Next
If you redefine an XML Schema (as opposed to including or importing one), you can
redefine nodes after referencing the XML Schema. See Redefining Nodes on page 641
for more information.

Referencing XML Schemas in the Diagram View

To reference an XML Schema in the Diagram view:

638

Right-click the schema node

Click Referenced Schemas on the shortcut menu.

Stylus Studio User Guide

Referencing External XML Schemas

The Referenced Schemas dialog box appears.

Figure 307. Referenced Schemas Dialog Box

Click the Add button.

The Add References to Schema dialog box appears.

Figure 308. Add References to Schema Dialog Box

Specify the type of reference you want to make. If you are redefining an XML
Schema, specify the namespace in the Namespace field.

Stylus Studio User Guide

639

Defining XML Schemas

Specify the URL of the XML Schema you want to reference. For example:

myfile.xsd

http://www.mycompany.com/schemas/myfile.xsd

\\fileserver\schemas\myfile.xsd

Click OK.
You are returned to the Referenced Schemas dialog box.

Click OK to add the referenced XML Schema to your XML Schema.

Referencing XML Schemas in the Tree View

To reference an XML Schema in the Tree view:
1.

Click the Schema node.

In the XML Schema left-side tool bar, click one of the following:

New Include

New Import

New Redefine

In the field that Stylus Studio displays, enter the location. This is a URL that identifies
the location of the file that contains the XML Schema. For example, it can be like any
one of the following:

myfile.xsd

http://www.mycompany.com/schemas/myfile.xsd

\\fileserver\schemas\myfile.xsd

If you defined an Import node, in the Properties window, double-click the Target
Namespace field and enter the target namespace. The target namespace must be
different from the target namespace of the importing file.

640

Stylus Studio User Guide

Referencing External XML Schemas

Redefining Nodes
Once you reference an XML Schema by redefining it, you are able to redefine that XML
Schemas complexTypes, simpleTypes, groups, and attributeGroups. This section
describes how to redefine nodes using the Diagram tab.

Extensions and Restrictions

There are two ways to redefine a node: by extension and restriction. An extension extends
the base type adding an element or an attribute definition, for example. A restriction
constrains the base type limiting a type to a certain range of values, for example.

Specifying Restriction Facets

If you define a restriction using a simpleType, the Properties window displays a section
that allows you to define the facets that restrict that type, as shown in Figure 309.

Figure 309. Facets for Describing Restrictions

Restriction facets include length, minLength, maxLength, and totalDigits. For each facet
you specify, you provide the facet name, a value, and, for some facets, whether or not the
value is fixed. Note that not all facets apply to all types.
See About Facet Types for simpleTypes on page 607 for more information on facets.

Stylus Studio User Guide

641

Defining XML Schemas

How to Redefine a Node

To redefine a node in the Diagram view:
1.

Right-click the schema node

Select Redefine from the shortcut menu.

The Redefine Schema Symbols dialog box appears.

Figure 310. Redefine Schema Symbols Dialog Box

Select the node from the redefined XML Schema you want to redefine and click OK.
The redefined node is added to the diagram, and the text for the redefined node
appears in the text pane. For example, <xsd:complexType name="PublicationType"/>.

Right-click the redefined node.

From the shortcut menu, select Quick Edit > and then either Derive by extension or
Derive by restriction.
The Type Derivation dialog box appears.

Figure 311. Type Derivation Dialog Box

642

Stylus Studio User Guide

Generating Documentation for XML Schema

Select the base type from which you want to derive the definition of the node you are
redefining. and click OK.
The node you added in Figure 3 is modified in the diagram to display the restriction
or extension you are using to redefine it, as shown in Figure 312.

Figure 312. Redefined Node as a Restricted simpleType

The code displayed in the text pane is also modified. For example:
<xsd:complexType name="PublicationType">
<xsd:simpleContent>
<xsd:restriction base="SKU"/>
</xsd:simpleContent>
</xsd:complexType>

If you specified a restriction of a simpleType, specify the restriction facets in the

Properties window. See Specifying Restriction Facets on page 641 if you need help
with this step.

Generating Documentation for XML Schema

The Documentation tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
The Documentation tab of the XML Schema Editor displays HTML documentation that
describes the currently active XML Schema. The HTML is presented using the XS3P
stylesheet.
To display XML Schema documentation, open an XML Schema document and click
the Documentation tab.

This section covers the following topics:

XS3P Stylesheet Overview on page 644

Saving XML Schema Documentation on page 647

Stylus Studio User Guide

643

Defining XML Schemas

Printing XML Schema Documentation on page 647

XS3P Stylesheet Overview

By default, Stylus Studio displays XML Schema on the Documentation tab using the
XS3P stylesheet from the DSTC Project Titanium (http://titanium.dstc.edu.au/).
Figure 313 shows how the purchaseOrder.xsd looks when displayed using this stylesheet.

Figure 313. XML Schema Documentation Displayed Using XS3P Stylesheet

The XS3P stylesheet contains

A customizable title (the default title is XML Schema Documentation)

A table of contents with hypertext links to sections in the documentation

644

Stylus Studio User Guide

Generating Documentation for XML Schema

Information about the XML Schemas properties, such as its target namespace and
any declared namespaces
Global declarations and global definitions, if any
A legend that describes the graphical conventions used in the XML Schema
documentation. The legend uses a fictitious type declaration for example purposes.
A glossary that defines terminology used in the XML Schema documentation.

Tip You can hide the legend and the glossary by clicking the Printer-friendly Version check

box at the top of the page.

This section covers the following topics:

XS3P Stylesheet Features on page 645

XS3P Stylesheet Settings on page 646

Modifying the XS3P Stylesheet on page 647

XS3P Stylesheet Features

The XS3P stylesheet has several features that affect content and layout of XML Schema
displayed on the Documentation tab. You can

Create a printer-friendly version of the documentation by clicking the Printer-friendly

Version check box.

Figure 314. Features of XML Schema Documentation

When you click this check box, Stylus Studio

Hides the Legend and Glossary sections

Automatically expands all XML instance and schema component representations

Removes the expand/collapse controls from the page

Expand and collapse XML instance and schema component representations. You can
do this for every XML instance or schema component by clicking the Expand All and

Stylus Studio User Guide

645

Defining XML Schemas

Collapse All buttons associated with these representations. You can also set this
option for individual instances by clicking the +/- button, as shown in Figure 315.

Figure 315. Representations Can be Collapsed/Expanded Individually

Customize and modify the XML Schema documentation. For example, you can
choose to include all super-types, you can change the default name, and you can
specify the sort order. Settings for these and other properties that affect the content
and appearance of the XML Schema documentation are displayed in the Options
dialog box. See XS3P Stylesheet Settings on page 646 for more information.

XS3P Stylesheet Settings

The XS3P stylesheet allows you to modify the following:

Title The default title is XML Schema Documentation, but you can change it to
whatever you want by editing the Title field.

Sort order By default, Stylus Studio sorts information in the XML Schema in
alphabetical order by type name. If you want to display information in document
order, set the Sort by Component field to False.

Whether or not you want Stylus Studio to search included and imported XML
Schemas.

If you want to incorporate instructions in the HTML, the Use JavaScript option
makes it easy for you to add instructions such to display pop-up windows and hide
information in the generated HTML document.

Inclusion in the XML Schema documentation of

Supertypes

Subtypes

Glossary

Legend

xsd namespace prefix

Schema diagrams

646

Stylus Studio User Guide

Generating Documentation for XML Schema

You control these settings on the Documentation page of the Options dialog box.
Tip You can also modify the stylesheet directly. See Modifying the XS3P Stylesheet on

page 647.

Modifying the XS3P Stylesheet

You can customize the XS3P stylesheet that Stylus Studio uses to display XML Schema
documentation. The XS3P stylesheet is in the \schema-documentation directory where
you installed Stylus Studio: bin\Plugins\schema-documentation. The name of the
stylesheet file is xs3p.xsl.
Should you choose to modify the default XS3P stylesheet, the new stylesheet must have
the same name as the original. After you modify and save this file, click the refresh button
on the Stylus Studio tool bar to see your changes.
Tip Make a copy of the xs3p.xsl file before you modify it.

Saving XML Schema Documentation

To save the XML Schema documentation, click the Save Documentation button (
) in
the XML Schema window. The XML Schema documentation is saved as an HTML file
that you can edit and add to as you would any other HTML file.

Printing XML Schema Documentation

To print XML Schema documentation:
1.

If you are using the XS3P stylesheet, optionally click the Printer-friendly Version
check box at the top of the XML Schema documentation.

Review the settings on the Documentation page of the Options dialog box (Tools >
Options > Module Settings > XML Schema Editor > Documentation).

Optionally, preview the XML Schema documentation (File > Print Preview).

Click the Print button (

Stylus Studio User Guide

), or type Ctrl + P.

647

Defining XML Schemas

About XML Schema Properties

The Documentation tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
When the Diagram or Tree tab of an XML Schema is active, you can see the properties for
the selected node. Click the node whose properties you want to view, and the properties
appear in the Properties window. If the Properties window is not visible, select View >
Properties from the menu bar.
To change the value of a property, click the property field and enter the new value. If only
certain values are allowed, Stylus Studio displays a drop-down list of the valid choices. In
the Diagram view, some properties are read-only. To modify these properties, switch to
the Tree view and change the property there. When you switch back to the Diagram view,
your change is visible.
Each type of node has its own set of properties. The following topics describe the
properties for various node types:

About xsd:schema Properties on page 649

Element and Element Reference Properties in XML Schemas on page 651

Attribute and Attribute Reference Properties in XML Schemas on page 653

Group Properties in XML Schemas on page 655

Model Group Properties in XML Schemas on page 655

Complex and simpleType Properties in XML Schemas on page 657

Restriction and Extension Type Properties in XML Schemas on page 658

Content Type Properties in XML Schemas on page 658

Aggregator Type Properties in XML Schemas on page 659

Facet Type Properties in XML Schemas on page 660

Notation Type Properties in XML Schemas on page 661

Include Type Properties in XML Schemas on page 661

Import Type Properties in XML Schemas on page 662

Redefine Type Properties in XML Schemas on page 662

Identity Constraint Type Properties in XML Schemas on page 662

Constraint Element Type Properties in XML Schemas on page 663

Documentation Type Properties in XML Schemas on page 663

648

Stylus Studio User Guide

About XML Schema Properties

About xsd:schema Properties

The root element of every XML Schema document is the xsd:schema element. The
xsd:schema element has the properties described in Table 70. Click the Tree tab, and then
click the Schema node to view the properties for the xsd:schema element.
Table 70. xsd:schema Properties
Property

Description

Type

The type is always Schema.

Namespace

The namespace for the Schema node is usually xsd, but you can
change it.

Target Namespace

This is the namespace that elements and attributes defined in an

instance document belong to. For example, suppose you define the
following:
<xsd:schema ... targetNamespace="http://myNS">
<xsd:element name="myelement"/>

In an instance document, the following declarations conform

with the target namespace:
<myelement xmlns="http://myNS/>
<myns:myelement xmlns:myns="http://myNS"/>

However, the following declaration does not conform:

<myns:myelement xmlns:myns="http://anotherNS"/>
Version

Stylus Studio User Guide

Use this property as a convenient way to track the revisions of your

XML Schema document.

649

Defining XML Schemas

Table 70. xsd:schema Properties
Property

Description

Default Element Form

An element or attributes form is either qualified or unqualified.

A form of qualified means that each time an element or attribute
is referenced in the schema document, you must specify the prefix
of its namespace. Every element and attribute has a form attribute. If
it is not explicitly defined, the schema processor checks the default
attribute form specified for the Schema node. For example:

Default Attribute
Form

<xs:schema elementFormDefault="qualified"
targetNamespace="http://myNs"
xmlns:myns="http://myNS">
<xs:element name="topElem">

....
</xs:element>
<xs:element name="anElem">
<xs:complexType>

<xs:sequence>
<xs:element ref="myns:topElem">
...

If the form for the element topElem (or, the default form for
elements) was defined to be unqualified, the reference could
have used ref="topElem".
Default Blocked
Definitions
Default Final

If an element does not have its own blocked or final definition, the
schema processor uses the default blocked or final definition you
specify here.

Definitions

650

Stylus Studio User Guide

About XML Schema Properties

Element and Element Reference Properties in XML Schemas

Both global and local elements have the properties described in Table 71. References to
elements have the same properties except where noted.
Table 71. Element and Element Reference Properties
Property

Description

Type

For elements, the type is always Element. For references to

elements, the type is always Ref. to Element.

Name

The tag name you use in an instance document. Specify the name
you want the element to have.

Min Occur.

Specifies the minimum number of instances of this element that can

be present. If an element is not required to be present, specify 0. You
cannot specify this property for a global element. If you do, Stylus
Studio ignores it.

Max Occur.

Specifies the maximum number of instances of this element that can

be present. If there is no limit to the number of instances, specify
unbounded. You cannot specify this property for a global element. If
you do, Stylus Studio ignores it.

Data Type

The type of the data that the element contains. Select from all
simpleTypes defined in an XML Schema, and all types (simple or
complex) that you define in the same schema. Nodes that are
references to elements do not have this property.

Default

Specifies the default value for this element. Specification of this

property makes sense only for optional elements. If you specified 0
for the Min Occur. property, you can specify a default value.
When this element is in an instance document, the element has
whatever value you specify. If you do not specify this element, the
schema processor behaves as though you had specified it with the
default value. When you specify a default value for an element, that
element must be optional in an instance document. An element can
have a value for the Default property or a value for the Fixed
Value property. The two properties are mutually exclusive.

Stylus Studio User Guide

651

Defining XML Schemas

Table 71. Element and Element Reference Properties
Property

Description

Fixed Value

When you specify a value for Fixed Value, it is optional for the
element to appear in an instance document. However, if the element
does appear, it must have the value specified by Fixed Value.
Whether or not you specify this element in an instance document,
the schema processor behaves as though you had specified this
element with the fixed value. An element can have a value for the
Fixed Value property or a value for the Default property. The two
properties are mutually exclusive.

Abstract

A Boolean value that indicates whether substitution for this element

is required. When Abstract is true, the element cannot be used in
an instance document. Instead, a member of the elements
substitution group must appear in the instance document.

Nillable

A Boolean value that indicates whether the contents of the element

can be set to nil. A value of true indicates that the element can be
empty; that is, it is permissible for the element to not contain any
subelements, attributes, or data.

Form

An elements form is either qualified or unqualified. A form of

qualified means that each time the element is referenced in the
schema document, you must specify the prefix of its namespace.
Every element has a form attribute. If it is not explicitly defined, the
schema processor checks the default attribute form specified for the
Schema node.

Blocked

Defines that this element cannot be derived in some forms. That is,
it specifies that one or more extensions, restrictions or substitutions
cannot be permitted. For example, an enumeration for all the states
in the United States can block extensions and substitutions, thus
allowing derived data types only so as to restrict the number of valid
states.

Substitutions

652

Stylus Studio User Guide

About XML Schema Properties

Table 71. Element and Element Reference Properties
Property

Description

Final Substitutions

Specifies that this element is not allowed to be substituted in a

substitution group if these are extensions or restrictions of the same
base type. For example, suppose an Invoice contains a reference to
a PO document. The PO document is derived from
AccountingDocument. If PO document has the
final="extensions" attribute, and PartialPO is defined as an
extension from AccountingDocument, the Invoice cannot
substitute PO with PartialPO.

Substitution Groups

If an element defines an element name definition in a substitution

group, it means that it can be used in all the places where there is a
reference to that element. For example, suppose the PO document
definition indicates that it can refer to an RFQ element. You can
specify that a foo element is in the substitution group for an RFQ
element. If you do, a PO document is valid if it refers to a foo
element.

Attribute and Attribute Reference Properties in XML Schemas

Both global and local attributes have the properties described in the Table 72. References
to attributes have the same properties, except where noted.
Table 72. Attribute and Attribute Reference Properties
Property

Description

Type

For attributes, the type is always Attribute. For attribute references,

the type is always Ref. to Attribute.

Name

The attribute name you use in an instance document. Specify the

name you want the attribute to have.

Data Type

The type of the data that is the value of the attribute. Select from all
simpleTypes defined in an XML Schema, and all simpleTypes that
you already defined in the same schema. References to attributes do
not have this property.

Stylus Studio User Guide

653

Defining XML Schemas

Table 72. Attribute and Attribute Reference Properties
Property

Description

Default

Specifies the default value for this attribute. Specification of this

property makes sense only for optional attributes. If you specified
optional for the Restrictions property, you can specify a default
value.
If this attribute is in an instance document, the attribute has whatever
value you specify. If you do not specify this attribute, the schema
processor behaves as though you had specified it with the default
value. When you specify a default value for an attribute, that
attribute must be optional in an instance document. An attribute can
have a value for the Default property or a value for the Fixed Value
property. The two properties are mutually exclusive.

654

Fixed Value

When you specify a value for Fixed Value, it is optional for the
attribute to appear in an instance document. However, if the attribute
does appear, it must have the value specified by Fixed Value.
Whether or not you specify this attribute in an instance document,
the schema processor behaves as though you had specified this
attribute with the fixed value. An attribute can have a value for the
Fixed Value property or a value for the Default property. The two
properties are mutually exclusive.

Restrictions

Specify prohibited, optional, or required.

Form

An attributes form is either qualified or unqualified. A form of

qualified means that each time the attribute is referenced in a
schema document, you must specify the prefix of its namespace.
Every attribute has a form attribute. If it is not explicitly defined, the
schema processor checks the default attribute form specified for the
Schema node.

Stylus Studio User Guide

About XML Schema Properties

Group Properties in XML Schemas

A group contains references to elements. Groups have the properties described in
Table 73:
Table 73. Group Properties
Property

Description

Type

The type is always Group.

Name

The name you specified for the group.

Min Occur.

Specifies the minimum number of instances of this group that can

appear in a complexType that references this group. If a group is not
required to be present, specify 0.

Max Occur.

Specifies the maximum number of instances of this group that can

appear in a complexType that references this group. If there is no
limit to the number of instances, specify unbounded.

Model Group Properties in XML Schemas

After you create a group node or a complexType node, you can add a model group node
as a child. A model group specifies rules for the occurrence of elements. These are the
elements that are the children of the group or complexType in an instance document. A

Stylus Studio User Guide

655

Defining XML Schemas

model group references and defines elements. Model groups have the properties described
in Table 74:
Table 74. Model Group Properties
Property

Description

Type

The type is always Model Group.

Modifier

Specifies the occurrence rules for the elements that you add as
children of the model group node. Specify one of the following
values:

all specifies that each element must appear exactly zero or one
time. The elements can appear in any order. In an instance
document, the children of the group or complexType can
include 0 or 1 instance of each element.

choice specifies that exactly one element can be present, and

there must be only one instance of that element. In an instance

document, exactly one element can be a child of the group or
complexType.

sequence specifies that the elements must appear in the order in

which they are specified in the schema. For each element, you
can specify whether it is optional and whether it can appear
more than once. The default is that exactly one must be present
in an instance document. In an instance document, each element
that appears must be in the same order as in the schema.
Another value you can specify is any. When you specify any,
you do not add any element definitions or references to
elements. As the name implies, any element can appear any
number of times.

656

Min Occur.

Specifies the minimum number of instances of this model group that

can appear in this group or complexType. If a model group is not
required to be present, specify 0.

Max Occur.

Specifies the maximum number of instances of this model group that

can appear in this group or complexType. If there is no limit to the
number of instances, specify unbounded.

Stylus Studio User Guide

About XML Schema Properties

Complex and simpleType Properties in XML Schemas

complexTypes have the properties described in Table 75. simpleTypes have only the Type
and Name properties.
Table 75. Complex and simpleType Properties
Property

Description

Type

The type is always complexType or simpleType.

Name

The type name you use elsewhere in the XML Schema. Specify the
name you want the type to have.

Abstract

A Boolean value that indicates whether substitution for this

complexType is required. When Abstract is true, the complexType
cannot be used in an instance document. Instead, a member of the
complexTypes substitution group must appear in the instance
document. simpleTypes do not have this property.

Mixed

A Boolean value that indicates whether or not this complexType can

contain raw data as well as elements and attributes. A value of true
indicates that it can contain raw data. simpleTypes do not have this
property.

Blocked

Defines that this type cannot be derived in some forms. That is, it
specifies that one or more extensions, restrictions or substitutions
cannot be permitted. For example, an enumeration for all the states
in the United States can block extensions and substitutions, thus
allowing derived data types only so as to restrict the number of valid
states.

Substitutions

Final Substitutions

Stylus Studio User Guide

Specifies that the type is not allowed to be substituted in a

substitution group if these are extensions or restrictions of the same
base type. For example, suppose an Invoice contains a reference to
a PO document. The PO document is derived from
AccountingDocument. If PO document has the final="extensions"
attribute, and PartialPO is defined as an extension from
AccountingDocument, the Invoice cannot substitute PO with
PartialPO.

657

Defining XML Schemas

Restriction and Extension Type Properties in XML Schemas

When you define a simpleType, you always derive it from a built-in XML Schema
simpleType, or a simpleType you previously defined. To specify the simpleType that your
simpleType is based on, add a restriction node or an extension node to your simpleType
node.
A restriction node indicates that your simpleType is a subset of some other simpleType.
An extension node indicates that your simpleType extends the range of values provided
by an existing simpleType.
Restriction type nodes and extension type nodes have the properties described in
Table 76:
Table 76. Restriction and Extension Type Properties
Property

Description

Type

The type is always Restriction or Extension.

Base Type

Indicates the data type that this simpleType is based on.

Content Type Properties in XML Schemas

Content types have the properties described in Table 77:
Table 77. Content Type Properties

658

Property

Description

Type

The type is always Content.

Mixed

A Boolean value that indicates whether this node can contain text as
well as elements.

Content Type

When the value is simpleContent, the node can contain only

character data and no elements or attributes. When the value is
complexContent, the node can contain character data, elements, and
attributes.

Stylus Studio User Guide

About XML Schema Properties

Aggregator Type Properties in XML Schemas

After you create a simpleType node, you can add an aggregator node as its child. An
aggregator node indicates that a single instance of an element of your new simpleType
contains a sequence of atomic types. Aggregator types have the properties described in
Table 78:
Table 78. Aggregator Type Properties
Property

Description

Type

Must be list or union.

Aggregator Type

Stylus Studio User Guide

list indicates that all instances in the sequence must be of

the same type.
union indicates that the instances in the sequence can be
of different types.

The type of the instances included in your new simpleType. If the

value of Type is union, you can specify a space-separated list.

659

Defining XML Schemas

Facet Type Properties in XML Schemas

Facet types have the properties described in Table 79:
Table 79. Facet Type Properties
Property

Description

Facet Type

Must be one of the following: enumeration, fractionDigits,

length, maxExclusive, maxInclusive, maxLength, minExclusive,
minInclusive, minLength, pattern, totalDigits, or whiteSpace.

Fixed

A Boolean value that indicates whether you can further restrict the
simpleType with this same facet and a different value. The default is
false. That is, the default is that you can apply the same facet more
than once. For example, suppose you specify the following
definition:
<xsd:simpleType name="zip">
<xsd:restriction base="xsd:string">
<xsd:length value="5" fixed="true"/>
</xsd:restriction>
</xsd:simpleType>

This defines a postal code whose length is 5 characters. You can

further restrict this simpleType with, for example, the pattern facet
so that the first three characters must always be "100", but you
cannot further restrict the length facet when the Fixed property is
set to true.
Facet types of pattern and enumeration do not have the Fixed
property.
Value

660

Varies according to the facet type. See About Facet Types for
simpleTypes on page 607.

Stylus Studio User Guide

About XML Schema Properties

Notation Type Properties in XML Schemas

Notation types have the properties described in Table 80. See Defining Notations on
page 635 for more information.
Table 80. Notation Type Properties
Property

Description

Type

The type is always Notation.

Name

The name you specify for the notation.

Public ID

Unique string that refers to the physical location of the external data,
for example, MyCompany//LOGO//JPEG.

System ID

URL used to physically locate the external data, for example,

http://www.mycompany.com/mylogo.jpg.

Include Type Properties in XML Schemas

Include types have the properties described in Table

81. See Referencing External XML

Schemas on page 636 for more information.

Table 81. Include Type Properties
Property

Description

Type

The type is always Include.

Location

URL that identifies the location of the file that contains the XML
Schema.

Stylus Studio User Guide

661

Defining XML Schemas

Import Type Properties in XML Schemas

Import types

have the properties described in Table 82. See Referencing External XML
Schemas on page 636 for more information.

Table 82. Import Type Properties

Property

Description

Type

The type is always Import.

Location

URL that identifies the location of the file that contains the XML
Schema.

Target Namespace

This is the namespace that elements and attributes defined in an

instance document belong to.

Redefine Type Properties in XML Schemas

Redefine types have the properties described in Table 83. See Referencing External
XML Schemas on page 636 for more information.

Table 83. Redefine Type Properties

Property

Description

Type

The type is always Redefine.

Location

URL that identifies the location of the file that contains the XML
Schema.

Identity Constraint Type Properties in XML Schemas

Identity Constraint types

have the properties described in Table 84. See Adding an

Identity Constraint to an Element on page 624 for more information.

Table 84. Identity Constraint Type Properties

662

Property

Description

Type

The type is always Identity Constraint.

Name

The name you specify for the identity constraint.

Stylus Studio User Guide

About XML Schema Properties

Constraint Element Type Properties in XML Schemas

Constraint Element types

have the properties described in Table 85. See Adding an

Identity Constraint to an Element on page 624 for more information.

Table 85. Constraint Element Type Properties

Property

Description

Type

The type is always Constraint Element.

XPath Expression

An XPath expression that returns the element for which you are
defining a constraint.

Documentation Type Properties in XML Schemas

Documentation types have the properties described in the following table:
Table 86. Documentation Type Properties
Property

Description

Type

The type is always Documentation.

Source

A path or URL for an external file that contains the documentation.

Language

The language of the contents of the documentation.

Stylus Studio User Guide

663

Defining XML Schemas

664

Stylus Studio User Guide

Chapter 9

Defining Document Type Definitions

This section provides information about how to use the Stylus Studio Document Type
Definition (DTD) editor to define a DTD. Familiarity with DTDs is assumed.
This section discusses the following topics:

What Is a DTD? on page 666

Creating DTDs on page 666

About Editing DTDs on page 667

About Modifiers in Element Definitions in DTDs on page 668

Defining Elements in DTDs on page 671

Defining General Entities and Parameter Entities in DTDs on page 680

Inserting White Space in DTDs on page 683

Adding Comments to DTDs on page 683

About Node Properties in DTDs on page 684

Associating an XML Document with an External DTD on page 688

Moving an Internal DTD to an External File on page 688

Stylus Studio User Guide

665

Defining Document Type Definitions

What Is a DTD?
A document type definition (DTD) describes the structure of a document. It specifies
which elements can contain which other elements, which elements are optional and which
are required, and which elements contain data. For example, a DTD might specify that a
book element

Must contain exactly one title element

Can contain any number of author elements

Might contain a subtitle element

To use a DTD, you must associate it with an XML document. A DTD can be internal or
external. An internal DTD is inside the XML document that uses it. It appears in the
DOCTYPE element, which immediately follows the XML declaration at the beginning of the
document. An external DTD is in a separate file. An XML document that uses an external
DTD specifies the path for the DTD in its DOCTYPE element. For example, the following
DOCTYPE element specifies that bookstore is the root element in this XML document, and
that the DTD that this document uses is stored in the file system at
C:\mydir\bookstore.dtd:
<!DOCTYPE bookstore SYSTEM "file://C:\mydir\bookstore.dtd">

A document instance is an XML document that uses a particular DTD. In other words, the
contents of a document instance have been tagged according to the structure defined in
the DTD it is associated with. For example, if the contents of the bookstore.xml file follow
the structure defined in the bookstore.dtd file, bookstore.xml is a document instance of
the bookstore DTD.

Creating DTDs
To create a DTD, select File > New > DTD Schema from the Stylus Studio menu bar.
Stylus Studio displays the DTD schema editor.
The Stylus Studio DTD editor provides two views of a DTD. In the Tree view, Stylus
Studio uses branches and leaves to represent the DTD. When you define a DTD in the Tree
view, you do not need to know the details about DTD syntax. In the Text view, Stylus
Studio displays the lines of text that make up the DTD. To define a DTD in the Text view,
you must be familiar with DTD syntax.
If you are editing an XML document and you want to create a DTD for that document,
click the Schema tab. Stylus Studio displays the Schema Not Found dialog box. Indicate
666

Stylus Studio User Guide

About Editing DTDs

that you want Stylus Studio to generate a DTD and indicate whether you want the new
DTD to be internal or external. After you respond to the prompts and click Yes, Stylus
Studio automatically creates the DTD for you and displays it in the Schema tab.
If you instruct Stylus Studio to create an internal DTD, you can update the DTD in the
XML editor. If you instruct Stylus Studio to create an external DTD, you must explicitly
open it to update it. An external DTD that Stylus Studio displays in the Schema tab is
read-only.
To use Stylus Studio to validate an XML document against a DTD, see Validating XML
Documents on page 208. If you update a DTD in Stylus Studio and that DTD is
associated with an XML document that is open in Stylus Studio, Stylus Studio refreshes
the schema information for the XML document.

About Editing DTDs

Stylus Studio displays a DTD with two views. Click the Text tab or the Tree tab to display
the view you want. The Tree tab displays a DOM-like tree that represents the DTD.
You can specify and edit the DTD in either view. However, the recommended method is
to edit the DTD in the Tree view. The Tree view provides tools tailored for creating a
DTD. The tool bar on the left provides a button for defining each node in a DTD. After
you select a node in the tree, the DTD editor allows you to add only those nodes that are
valid at that point.
Also, in the Tree view of the DTD, you can see the properties for each node. When you
click the node whose properties you want to view, the properties appear in the Properties
window. If the Properties window is not visible, select View > Properties from the menu
bar.
After you add a node, you can make changes in the Properties window, the Tree tab, or
the Text tab. Any changes you make in one place are immediately reflected in the other
places.
See Defining Elements in DTDs on page 671.

Restrictions
A DTD can include other, external DTDs. In a future release, it is expected that you will
be able to click Open Schema
to display an included DTD. However, in this release,
this is not supported.

Stylus Studio User Guide

667

Defining Document Type Definitions

DTDs are not XML documents. Consequently, as you would expect, Indent XML Tags
does not work on DTDs.

About Modifiers in Element Definitions in DTDs

When you define an element, you specify one or more modifiers. A modifier specifies a
rule about the structure or occurrence of the element being defined. An element can have
only one top-level modifier. However, you can add one or more modifiers to the top-level
modifier. A modifier can aggregate elements or other modifiers.
This section discusses the following topics:

Description of Element Modifiers in DTDs on page 668

Simple Example of Aggregating Modifiers in DTDs on page 669

More Complex Example of Aggregating Modifiers in DTDs on page 670

Aggregating Modifiers to Allow Any Order and Any Number in DTDs on page 670

Description of Element Modifiers in DTDs

Table 87 describes the available modifiers:
Table 87. Element Modifiers

668

Modifier

Description

Indicator in DTD

Optional

This element can appear once or not at all. (0 or

Question mark (?)

Zero or more

This element is optional and repeatable. (0, 1,

or more)

Asterisk (*)

One or more

This element is required and repeatable. (1 or

more)

Plus sign (+)

Stylus Studio User Guide

About Modifiers in Element Definitions in DTDs

Table 87. Element Modifiers
Modifier

Description

Indicator in DTD

Choice

Exactly one of the specified subelements must

appear.

Vertical bar (|)

Sequence

If no other modifiers are defined on the

Sequence modifier, each subelement in this
element must appear exactly once. In other
words, it is required. Also, the subelements
must appear in the order in which they are
specified in the referencing element. You can
define other modifiers on the Sequence
modifier. In this way, you can specify that some
subelements are optional, some appear zero or
more times, and some appear one or more
times.

Comma (,)

Simple Example of Aggregating Modifiers in DTDs

Suppose you want a book element to always contain exactly one title element and any
number of author elements. The title and author elements contain only raw data. To
accomplish this, you would perform steps that generate the following tree representation:
book
Sequence
title
One or More

author
title
Zero or More
#PCDATA
author
Zero or More
#PCDATA

In the book element definition, Sequence modifies book and One or More modifies Sequence.
Because the title element immediately follows the Sequence modifier, the default
occurrence rule is assumed. That is, the title element must appear exactly once. In the
Text view of the DTD, the definition for the book element is as follows:
<!ELEMENT book (title, (author)+)>

Stylus Studio User Guide

669

Defining Document Type Definitions

More Complex Example of Aggregating Modifiers in DTDs

Following is a more complicated example. Suppose you want book elements to include

Exactly one title

Either an author or an editor, but it is okay if neither appear

Zero or more paragraphs

To accomplish this, you would perform steps that generate the following tree
representation:
book
Sequence
title
Optional
Choice
author
editor
Zero or More
paragraph

In the Text view of the DTD, the definition for the book element is as follows:
<!ELEMENT book (title, (author|editor)?, paragraph*)>

Aggregating Modifiers to Allow Any Order and Any Number in

DTDs
The Choice modifier specifies that only one of the specified elements can appear in an
instance document. However, if you specify the Zero or More modifier and then the
Choice modifier, the result is that the specified elements can appear in any order and each
element can appear any number of times.
The text for such an element definition is as follows:
<!ELEMENT A (B|C|D)*>

670

Stylus Studio User Guide

Defining Elements in DTDs

The tree representation is as follows:

A
Zero or More
Choice
B
C
D

This allows an A element to contain

Zero, one, or more B elements

Zero, one, or more C elements

Zero, one, or more D elements

Furthermore, the contained elements can be in any order.

Defining Elements in DTDs

You can define an element in the Text or Tree tab.
In the Text tab, you enter the text that defines your element and describes its structure. For
example, to define a Catalog element that can contain one or more Publisher elements,
followed by zero or more Thread elements, followed by one or more Book elements, you
would enter the following:
<!ELEMENT Catalog ((Publisher)+,((Thread)*,(Book)+))>

When you define elements in the Text tab, you must know the syntax and keywords for
what you want to define. This information is publicly available on the World Wide Web.
Stylus Studio documentation does not include instructions for defining a DTD in the Text
tab. For DTD information, see, http://www.w3.org/TR/REC-xml.
When you use Stylus Studio, it is easier to define an element in the Tree tab. In the Tree
, and Stylus Studio takes care of the syntax and
tab, you click New Element Definition
keywords. In the Tree tab, definition of an element requires that you
1.

Create the element by specifying its name. To do this, see Defining Elements in the
DTD Tree Tab on page 672, which is the first topic in this section.

Define the structure of the element by specifying modifiers, defining where raw data
is allowed, and adding references to other elements. To help you do this, this section
discusses the following topics:

Stylus Studio User Guide

671

Defining Document Type Definitions

Specifying That an Element Can Have an Attribute in DTDs on page 673

Specifying That an Element is Required in DTDs on page 673
Specifying That an Element is Optional in DTDs on page 674
Specifying That Multiple Instances of An Element Are Allowed in DTDs on
page 675
Specifying That An Element Can Contain One of a Group of Elements in DTDs
on page 677
Specifying That an Element Can Contain One or More Elements in DTDs on
page 678
Specifying That an Element Can Contain Data in DTDs on page 680
Moving, Renaming, and Deleting Elements in DTDs on page 680

Defining Elements in the DTD Tree Tab

In the DTD editor, if the Tree view is not visible, click the Tree tab at the bottom of the
window.
To create an element in the Tree tab:
1.

Click the DTD node at the top of the tree.

In the tool bar on the left, click New Element Definition

. Stylus Studio displays
a field for the new element at the end of the current contents of the DTD.

Type the name of the new element and press Enter. Stylus Studio displays the
properties for the new element in the Properties window. If the Properties window is
not visible, select View > Properties from the Stylus Studio menu bar. For example,
suppose you specified title as the name of the new element. Your new element has
the following properties:
Table 88. Element Properties

672

Property

Value

Type

Element

Name

title

Content Model

Empty

Stylus Studio User Guide

Defining Elements in DTDs

To change the value of a property, double-click the current value. For information
about the properties that each element can have, see About Node Properties in
DTDs on page 684.

After you create an element, you must define the structure of the contents of the element.
The rest of the topics in this section provide information on how to define structure.

Specifying That an Element Can Have an Attribute in DTDs

In the DTD Tree tab, to specify that an element can have an attribute:
1.

Click the name of the element that you want to have an attribute.

In the menu bar on the left, click New Attribute

Type the name of the attribute and press Enter.

Specifying That an Element is Required in DTDs

You specify that an element is required when you add a reference to that element in
another element.
In the Tree tab, to specify that an element is required:
1.

Define the element that you want to be required. See Defining Elements in the DTD
Tree Tab on page 672.

Create the element that contains the element that you want to be required. This is the
container element.

Click the container element name.

In the tool bar on the left, click New Modifier

menu.

Double-click Sequence.

If the required element can appear only once, skip this step. If the required element
can appear more than once, click New Modifier and double-click One or More in the
pop-up menu.

With the modifier highlighted, click New Reference to Element

on the left.

Stylus Studio User Guide

. Stylus Studio displays a drop-down

in the tool bar

673

Defining Document Type Definitions

Enter the name of the element that you want this element to reference.
After you add a reference to an element, you might want to check the definition of the
referenced element. To do this, right-click the reference. In the shortcut menu, click
Go To Definition. Stylus Studio moves the focus to the definition of the referenced
element.

For example, suppose the title element is required, and that it is relevant only in the
context of a book element. When you define the book element, you specify that it contains
the title element. If you specify only the Sequence modifier, the occurrence default is
assumed. The occurrence default is that there must be exactly one of the contained
element. In other words, the title element is required and there can be only one. In this
case, the definition of the book element is as follows:
<!ELEMENT book (title)>

The tree representation looks like this:

book
Sequence
title

It is also possible for an element to be required and for more than one to be allowed.
Suppose the book element must also contain at least one author element, but it can contain
more than one author element. The definition of the book element is as follows:
<!ELEMENT book (title, author+)>

The tree representation looks like this:

book
Sequence
title
One or More
author

Specifying That an Element is Optional in DTDs

You specify that an element is optional when you add a reference to that element in
another element. When an element is optional, it means that there can be one or none. If
you want to specify that there can be none, one, or more, use the Zero or More modifier.
See Specifying That Multiple Instances of An Element Are Allowed in DTDs on
page 675.
674

Stylus Studio User Guide

Defining Elements in DTDs

In the Tree tab, to specify that an element is optional:
1.

Define the element that you want to be optional. See Defining Elements in the DTD
Tree Tab on page 672.

Create the element that contains the element that you want to be optional. This is the
container element.

Click the container element name.

In the tool bar on the left, click New Modifier

menu.

If the container element can contain only the optional element, skip this step. If the
container element can contain more than one element, click Sequence.

Click New Modifier.

In the pop-up menu that appears, double-click Optional.

In the tool bar on the left, click New Reference to Element

and enter the name of
the optional element. If the container element can contain additional optional
elements, repeat this step for each one.
After you add a reference to an element, you might want to check the definition of the
referenced element. To do this, right-click the reference. In the shortcut menu, click
Go To Definition. Stylus Studio moves the focus to the definition of the referenced
element.

. Stylus Studio displays a drop-down

Specifying That Multiple Instances of An Element Are Allowed in

DTDs
You specify that multiple instances of an element are allowed when you add a reference
to that element in another element. When multiple instances of an element are allowed,
you specify that there can be either

None, one, or more

One or more
In the Tree tab, to specify that there can be multiple instances of an element:
1.

Define the element that can appear multiple times. See Defining Elements in the
DTD Tree Tab on page 672.

Define the element that contains the element that can appear multiple times. This is
the container element.

Stylus Studio User Guide

675

Defining Document Type Definitions

Click the container element name.

In the left tool bar, click New Modifier

If the container element can contain only one type of element, skip this step. If the
container element can contain more than one type of element, double-click
Sequence, and then click New Modifier.

Double-click Zero or More to allow the container element to contain zero, one, or
more instances of an element. Or, double-click One or More to allow the container
element to contain one or more instances of an element.

In the left tool bar, click New Reference to Element

and enter the name of the
element that can appear multiple times. If the container element can contain
additional types of elements, repeat this step for each one that can appear multiple
times.
After you add a reference to an element, you might want to check the definition of the
referenced element. To do this, right-click the reference. In the shortcut menu, click
Go To Definition. Stylus Studio moves the focus to the definition of the referenced
element.

. Stylus Studio displays a drop-down menu.

Suppose there are some elements that can appear zero, one, or more times, and there are
other elements that can appear one or more times. The tree representation for this might
look like the following:
book
Sequence
One or More
Author
Format
Zero or More
Award
Review

In this example, an instance document must contain these elements in the following order:
author
format
award
review

676

Stylus Studio User Guide

Defining Elements in DTDs

Suppose you want them in the following order:

review
format
award
author

In this case, the tree representation would look like this:

book
Sequence
Zero or More
Award
One or More
Format
Zero or More
Review
One or More
Author

Specifying That An Element Can Contain One of a Group of

Elements in DTDs
You might want to define an element that contains one element out of a group of elements.
For example, you might want an InventoryNumber element to contain a book, magazine, or
newsletter element.
In the Tree tab, to define an element that contains one of a group of elements:
1.

Define the elements that your new element can contain. See Defining Elements in
DTDs on page 671.

Define the element that you want to contain another element. This is the container
element.

Click the container element name.

In the left tool bar, click New Modifier

Double-click Choice.

Stylus Studio User Guide

. Stylus Studio displays a drop-down menu.

677

Defining Document Type Definitions

For each element in the group of elements from which one element can appear:
a.

Click New Reference to Element

in the left tool bar.

Type the name of the element and press Enter.

After you add a reference to an element, you might want to check the definition of the
referenced element. To do this, right-click the reference. In the shortcut menu, click
Go To Definition. Stylus Studio moves the focus to the definition of the referenced
element.
b.

When the XSLT processor validates an instance document against this DTD, it ensures
that each instance of the new element you just defined contains exactly one of the
referenced elements.
The tree representation for an InventoryNumber element that can contain a book, magazine,
or newsletter element would look like the following:
InventoryNumber
Choice
book
magazine
newsletter

Specifying That an Element Can Contain One or More Elements

in DTDs
Often, you want an element to contain a sequence of elements. Some of these elements
might be required, some might be optional, and some might be able to occur more than
once. There might even be a group of elements in which only one can appear.
In the Tree tab, to define an element that contains a sequence of elements:

678

Define the elements that you want your new element to contain. See Defining
Elements in DTDs on page 671.

Define the element that contains the sequence of elements. This is the container
element.

Click the container element name.

In the left tool bar, click New Modifier

Double-click Sequence.

. Stylus Studio displays a drop-down menu.

Stylus Studio User Guide

Defining Elements in DTDs

To add required elements to the container element, click New Reference to Element
in the left tool bar and enter the name of the required element. Do this for each
required element. You can change the order later.

At this point, you can add

Optional elements

Elements that can appear one or more times

Elements that can appear zero, one, or more times

Elements that belong to a group in which only one element in the group can be present
The procedure is the same for these modifiers. The only difference is the modifier you
select. For example, following are the instructions for adding optional elements:
1.

In the DTD editor, click the Sequence modifier.

In the left tool bar, click New Modifier.

Double-click Optional.

For each optional element, click New Reference to Element and enter the name of the
optional element. This works only if you want all optional elements to be consecutive.
If you want optional elements to be interspersed with required elements or elements
that can appear one or more times, you must perform steps 1 through 4 for each
element.

In an instance document, the contained elements must appear in the order in which they
are specified in the DTD.
To modify the order:
1.

Click the modifier for the element you want to move.

Click the up or down arrow repeatedly until the element is where you want it to be.

To move a required element that can appear only once, click its name and then use the up
and down arrows.
Alternative: Right-click the item you want to move. Select Move Up or Move Down from
the shortcut menu.

Stylus Studio User Guide

679

Defining Document Type Definitions

Specifying That an Element Can Contain Data in DTDs

To specify that an element can contain raw data, you must first define the element. See
Defining Elements in the DTD Tree Tab on page 672.
In the Tree tab, to specify that an element can contain data:
1.

Click the element you want to contain data.

In the left tool bar, click New Modifier

Double-click Zero or More.

In the left tool bar, click Add $PCDATA

. Stylus Studio displays a drop-down menu.

Moving, Renaming, and Deleting Elements in DTDs

To move an element definition or a reference to an element, in the Tree tab, click the name
of the element or the modifier for the reference. Then click Move Up
or Move Down
repeatedly until the element or reference is where you want it to be.
Alternative: Right-click the item you want to move. Select Move Up or Move Down from
the shortcut menu that appears.
To rename an element or attribute, right-click it and select Rename from the shortcut
menu that appears. Type the new name and press Enter.
.

Alternative: Click Change Name

To delete a node in the DTD, right-click the node you want to delete. In the shortcut menu
that appears, click Delete.
Alternative: Click Delete Node

Defining General Entities and Parameter Entities in

DTDs
In DTDs, an entity allows you to define a symbol for a value. In the Tree view, you can
define general entities and parameter entities. The value of a general entity can be just
about anything. It can be

A short string that represents a longer string

A way to include another marked-up file

680

Stylus Studio User Guide

Defining General Entities and Parameter Entities in DTDs

A reference to a graphical image

A placeholder for some non-XML data or an expression that needs special formatting

General entities are useful for things that change often, such as the name of a product in
development. An entity allows you to change the value in one place and have the corrected
value appear everywhere it is needed.
See also Description of Entity and Parameter Entity Properties in DTDs on page 687.
When you define a general entity, you specify a symbol that you can use in instance
documents. When the XML parser finds a reference to a general entity, it replaces the
symbol with the value you specified when you defined the general entity.
When you define a parameter entity, you specify a symbol that you can use elsewhere in
the DTD. Again, when the XML parser finds a reference to a parameter entity, it replaces
the reference with the value you specified when you defined the parameter entity.
In a DTD, the definition of an entity must appear before a reference to that entity.
Therefore, it is good practice to put all entity declarations at the beginning of a DTD.
This section discusses the following topics:

Steps for Defining Entities in DTDs on page 681

General Entity Example in a DTD on page 682

Parameter Entity Example in a DTD on page 683

Steps for Defining Entities in DTDs

The procedures for defining general entities and parameter entities are almost the same.
To define an entity in the Tree tab:
1.

Click the DTD node.

In the left tool bar, click New Entity

Type the name of the new entity and press Enter. Stylus Studio displays the properties
for the new entity in the Properties window. If the Properties window is not visible,
select View > Properties from the Stylus Studio menu bar to display it.

In the Properties window, check the value of the Location property.

If you want to define the value for this entity in this DTD, the value should be Internal.
Otherwise, the value should be External. If you need to change the value of the

Stylus Studio User Guide

or New Parameter Entity

681

Defining Document Type Definitions

Location property, double-click its current value. In the drop-down menu that

appears, double-click the new value.

If the value of the Location property is External, skip this step. If the value of the
Location property is Internal, double-click the Value field and enter the value of the
entity. Definition of your entity is complete. You do not perform the remaining steps
in this procedure.

If the value of the Location property is External, specify a value for System ID.
Double-click the field to enter a value. The value of System ID is a path to a file. It
can be a URL or a file system path.
Although you can also specify a value for the Public ID property, Stylus Studio
ignores any value you specify. A Public ID is a string that some parsers can resolve to
an address, which they then use to locate a file. Stylus Studio does not have this
capability.

If you are defining a parameter entity, you are done. If you are defining a general
entity, check the value of the Parsed property. If necessary, double-click the value of
the Parsed property to change it. The value of the Parsed property indicates whether
the value of the entity is parsed XML. For example, if the entity refers to an image
file, you do not want Stylus Studio to try to parse it.

General Entity Example in a DTD

Suppose you define the shopname general entity as an internal entity with the value Most
Excellent Book Store of Tokyo. In the Text view of the DTD, this appears as follows:
<!ENTITY shopname "Most Excellent Book Store of Tokyo">

In an instance document, when the XML parser finds &shopname;, it replaces it with Most
Excellent Book Store of Tokyo.

682

Stylus Studio User Guide

Inserting White Space in DTDs

Parameter Entity Example in a DTD

Suppose you define the invoice parameter entity as an internal entity as follows:
<!ENTITY % customer "name, street, city, state, zipcode">

The percent sign (%) after the ENTITY keyword indicates that this is a parameter entity.
Later in the DTD, you can reference this parameter entity as follows:
<!ELEMENT invoice (%customer;, item, price, date)>

When this DTD is processed, it is as if you had specified the following:

<!ELEMENT invoice (name, street, city, state, zipcode, item, price, date)>

Inserting White Space in DTDs

Suppose you define some elements in the Tree tab. If you click the Text tab, you see that
your DTD is on one long line. To make your DTD more readable, you can insert white
space between elements. You cannot insert white space between the nodes that define an
element.
In the Tree tab, to insert white space:
1.

Click the DTD node at the top of the schema.

In the tool bar on the left, click New Text

Type a space and press Enter.

Click the up arrow to move the space to the desired location.

Adding Comments to DTDs

In a DTD, comments are useful for organizing the contents and clarifying the various parts
of a DTD. A comment can appear between element, entity, or white space nodes. You can
insert a comment in the middle of an element definition.
In the Tree tab, to insert a comment:
1.

Click the DTD node at the top of the schema.

In the tool bar on the left, click New Comment

Stylus Studio User Guide

683

Defining Document Type Definitions

Type your comment and press Enter.

Click the up arrow to move the comment to the desired location.

About Node Properties in DTDs

Each node in a DTD is associated with one or more properties. Every node has a Type
property. The properties associated with a node vary according to the value of the Type
property. Stylus Studio supports the following values for the Type property of a node in a
DTD:

Element

Attribute

DTD Modifier

PCDATA

Entity

Parameter Entity

Text

Comment

To determine the properties for a particular node in a DTD, click the node. Stylus Studio
displays the properties in the Properties window. If the Properties window is not visible,
select View > Properties from the Stylus Studio menu bar.
To change a property, double-click the property value in the Properties window. Enter the
new value or, if a drop-down menu appears, double-click the value you want. Any changes
you make in the Properties window are immediately reflected in the Tree and Text views.
You cannot change the type property of a node.
The remainder of this section discusses the following topics:

Description of Element Properties in DTDs on page 685

Description of Attribute Properties in DTDs on page 685

Description of Entity and Parameter Entity Properties in DTDs on page 687

684

Stylus Studio User Guide

About Node Properties in DTDs

Description of Element Properties in DTDs

An element has three properties: Type, Name, and Content Model. The Name property is a
string that identifies the element. The Content Model property describes the allowed
contents for the element. Table 89 describes the possible values of the Content Model
property for Element nodes:
Table 89. Element Property Descriptions
Value of Content
Model Property

Description

Empty

This element can contain only attributes.

Element Only

This element can contain attributes and specified elements. It cannot

directly contain raw data.

Mixed

This element can contain attributes, specified elements, and raw

data.

Any

This element can contain attributes, any elements defined in this

DTD, and raw data.

Description of Attribute Properties in DTDs

Table 90 shows the properties that an attribute can have. It also provides the possible
values, and a description for each property.
Table 90. Attribute Property Descriptions
Property

Allowable Values

Description

Type

Attribute

All attribute nodes have this type.

Name

String

Identifier for the particular attribute.

Restrictions

Fixed

The attribute is required and it must always have

the value specified by the Default property. You
must always explicitly specify this attribute.

Implied

The attribute is optional. There is no default value.

Optional

The attribute is optional. If you do not specify it,

the XML parser uses the value of the Default
property.

Stylus Studio User Guide

685

Defining Document Type Definitions

Table 90. Attribute Property Descriptions
Property

Content Type

686

Allowable Values

Description

Required

The element must always explicitly specify this

attribute and assign a value to it.

CDATA

The attribute value can contain any valid character

data. It is a text string.

Entity

The attribute value is the name of an entity defined

in the DTD.

Entities

The attribute value is a space-separated list of

entities that are defined in the DTD.

Enumerated

The attribute value is one of a set of specified

values. When the value of the Content Type
property is Enumerated, the attribute has an
additional property: Allowed Values. Specify the
allowed values in a space-separated list.

The attribute value is a unique name within the

DTD.

IDREF

The attribute value is an ID that is defined in the

DTD.

IDREFs

The attribute value is a space-separated list of IDs

that are defined in the DTD.

NMToken

The attribute value is a valid XML name that is

composed of letters, numbers, hyphens,
underscores, and colons.

Stylus Studio User Guide

About Node Properties in DTDs

Table 90. Attribute Property Descriptions
Property

Allowable Values

Description

NMTokens

The attribute value is a space-separated list of

name tokens.

Notation

The name of a notation specified in the DTD. The

notation describes a non-XML data format, such
as those used for image files. When the value of
the Content Type property is Notation, the
attribute has an additional property: Allowed
Values. Specify the allowed values in a spaceseparated list.

Description of Entity and Parameter Entity Properties in DTDs

Table 91 shows the properties that an entity or parameter entity can have. It also provides
the possible values, and a description for each property.
Table 91. Entity and Parameter Entity Property Descriptions
Property

Allowable Values

Description

Type

Entity

All entity nodes have this type.

Parameter Entity
Name

String

Identifier for this entity.

Location

External or

An external location indicates that the value of the

entity is in a file that is outside the DTD file.

Internal

An internal location indicates that the value of the

entity is defined in the Value property of this
entity node.
Value

Stylus Studio User Guide

String

If the value of the Location property is Internal,

this property specifies the value of the entity. If the
value of the Location property is External, you
cannot specify this property.

687

Defining Document Type Definitions

Table 91. Entity and Parameter Entity Property Descriptions
Property

Allowable Values

Description

Public ID

String

String that some parsers can resolve to a file

location. Stylus Studio ignores any value you
specify.

System ID

String

Path or URI for a file that contains the value of the

entity.

Parsed

True or False

Indicates whether the entity value is parsed XML.

A parameter entity does not have this property.

Associating an XML Document with an External DTD

To associate an XML document with an external DTD, add a DOCTYPE element to the
beginning of your XML document. The DOCTYPE element should be immediately after the
XML declaration element. The format of the DOCTYPE element is
<!DOCTYPE root_element_name SYSTEM "path_to_dtd">

Replace root_element_name with the name of the root element in your XML document.
Replace path_to_dtd with the path for the DTD you want your document to use.

Moving an Internal DTD to an External File

To move an internal DTD to an external file:

688

In the Text tab of the DTD editor, in the DOCTYPE element, select only the text inside
the brackets [ ].

Cut the text.

Select File > New > DTD Schema from the menu bar.

Paste the text in the new DTD schema file that Stylus Studio displays.

Save the file. You might want to save the DTD in the same directory as the XML
document that uses it.

Stylus Studio User Guide

Moving an Internal DTD to an External File

In your XML document in the Text tab of the DTD editor, remove the brackets and
insert the following in their place:
SYSTEM "schema_file_path"

The path you specify can be the relative or absolute path of the DTD file you just
saved. This path must be in quotation marks.

Stylus Studio User Guide

689

Defining Document Type Definitions

690

Stylus Studio User Guide

Chapter 10

Writing XPath Expressions

The XML Path Language (XPath) allows you to query an XML document using XPath
expressions. An XPath expressions returns a well-formed XML node-list or an XPath
value object. Stylus Studio supports the November 2005 W3C XPath 2.0 Candidate
Recommendation. XPath 2.0 is a superset of XPath 1.0.
This section discusses the following topics:

About the XPath Processor on page 692

Using the XPath Query Editor on page 694

Sample Data for Examples and Practice on page 701

Getting Started with Queries on page 707

Specifying the Nodes to Evaluate on page 720

Handling Strings and Text on page 734

Specifying Boolean Expressions and Functions on page 741

Specifying Number Operations and Functions on page 744

Comparing Values on page 747

Finding a Particular Node on page 752

Obtaining a Union on page 760

Obtaining Information About a Node or a Node Set on page 761

Using XPath Expressions in Stylesheets on page 765

Accessing Other Documents During Query Execution on page 769

XPath Quick Reference on page 771

Stylus Studio User Guide

691

Writing XPath Expressions

About the XPath Processor

Stylus Studio supports the November 2005 W3C XPath 2.0 Candidate Recommendation.
XPath 2.0 is a superset of XPath 1.0.
As an overview of the XPath processor, this section provides the following information:

Where You Can Use XPath Expressions on page 692

About XPath on page 692

Benefits of XPath on page 693

Internationalization on page 694

Restrictions on Queries on page 694

For additional information about XPath see http://www.w3.org/TR/xpath20.

Where You Can Use XPath Expressions

You use XPath expressions in XQuery documents and XSLT stylesheets to select the
nodes you want to transform and query. For example, you can specify queries as values
of match and select attributes in stylesheets. You can use XPath 1.0 expressions in
XQuery and XSLT 1.0, and XPath 2.0 expressions in XSLT 2.0.
You can also query XML documents using the XPath Query Editor. Stylus Studio displays
the results in the Query Output window, Stylus Studio displays the result of the query.

About XPath
XPath is a notation for retrieving information from a document. The information could be
a set of nodes or derived values.
XPath allows you to identify parts of an XML document. In addition, a subset of XPath
allows you to test whether or not a node matches a particular pattern. XPath provides
Boolean logic, filters, indexing into collections of nodes, and more.
XPath is declarative rather than procedural. You use a pattern modeled on directory
notation to describe the types of nodes to look for. For example, book/author means find
all author elements that are contained in book elements.
XPath provides a common syntax for features shared by Extensible Stylesheet Language
Transformations (XSLT) and XQuery. XSLT is a language for transforming XML
documents into XML, HTML, or text. XQuery builds on XPath and is a language for
extracting information from XML documents.
692

Stylus Studio User Guide

About the XPath Processor

The basic syntax for XPath mimics the Uniform Resource Identifier (URI) directory
navigation syntax. However, the syntax does not specify navigation through a physical file
structure. The navigation is through elements in the XML tree.

Benefits of XPath
XPath is designed for XML documents. It provides a single syntax that you can use for
queries, addressing, and patterns. XPath is concise, simple, and powerful. XPath has
many benefits, as follows:

Queries are compact.

Queries are easy to type and read.

Syntax is simple for the simple and common cases.

Query strings are easily embedded in programs, scripts, and XML or HTML
attributes.

Queries are easily parsed.

You can specify any path that can occur in an XML document and any set of
conditions for the nodes in the path.

You can uniquely identify any node in an XML document.

Queries return any number of results, including zero.

Query conditions can be evaluated at any level of a document and are not expected to
navigate from the top node of a document.

Queries do not return repeated nodes.

For programmers, queries are declarative, not procedural. They say what should be
found, not how it should be found. This is important because a query optimizer must
be free to use indexes or other structures to find results efficiently.

XPath is designed to be used in many contexts. It is applicable to providing links to

nodes, for searching repositories, and for many other applications.
When you define a query, keep in mind that XML data can be represented as a tree. A tree
is a hierarchical representation of XML data. The root node is the top of the tree. Each
element, attribute, text string, comment, and processing instruction corresponds to one
node in the tree. A tree also shows the relationships among the nodes. For more
information on tree structure, see Tree Representation of a Sample XML Document on
page 704.

Stylus Studio User Guide

693

Writing XPath Expressions

Internationalization
Queries can contain non-Latin characters.

Restrictions on Queries
XPath is a language for selecting existing XML data; it does not perform manipulation
(like sorting) or construction of different XML structures. To perform such operations,
you need to use the language that is hosting XPath XSLT or XQuery, for example.
You cannot query non-XML data. If you query a document that does not contain XMLformatted data, Stylus Studio displays an error message that informs you that the queried
text is not XML.

Using the XPath Query Editor

The XPath Query Editor is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio Professional Suite.

694

Stylus Studio User Guide

Using the XPath Query Editor

The XPath Query Editor is a dockable window that you can use to query XML documents
in Stylus Studio. An example, showing an XPath expression being evaluated against
bookstore.xml from the Example project installed with Stylus Studio, is shown here:

Figure 316. XPath Query Editor

Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XPath Query
Editor video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.

Parts of the XPath Query Editor

The XPath Query Editor consists of

A query pane, in which you enter the XPath expression you want to execute against
the current document. The query pane allows you to enter queries with multiple lines.

Stylus Studio User Guide

695

Writing XPath Expressions

The query pane supports Stylus Studios Sense:X feature, which provides tool-tips for
XPath expressions and auto-completion for XML documents associated with an
XML Schema, as shown here:

Figure 317. Sense:X Auto-completion in XPath Query Editor

A results pane, which shows the results from the query after you execute it. Results
are shown as a number of hits and include the type of XML tag and value of each hit.
When you click on a returned node, Stylus Studio moves the cursor in the XML
document to the source node for the returned node.
A namespace pane, which allows you to redefine the namespace prefix to be used in
the query. The namespace pane is not displayed by default, and is not shown in
Figure 316.

Displaying the XPath Query Editor

The XPath Query Editor is not displayed by default. In addition, it is closed when you exit
the XML document with which it is associated.
To display the XPath Query Editor:

696

Click the Show XPath Query Editor button on the XML Editor tool bar ( ).
The XPath Query Editor appears. Any previously created queries are displayed on
individual tabs. If no queries have been created, a new tab, labeled Query1, is
displayed.

Stylus Studio User Guide

Using the XPath Query Editor

Alternative:

Select View > XPath Query Editor from the Stylus Studio menu.

Customizing Syntax Coloring

The XPath Query Editor uses Stylus Studios syntax coloring, and you can change the
default settings for several XPath Query Editor properties on the Editor Format page of
the Options dialog box. These settings affect tokens in XPath expressions, such as errors,
strings, keywords, operators, and attributes.
To change syntax coloring in the XPath Query Editor:
1.

Click Tools > Options > General > Editor Format to display the Editor Format page
of the Options dialog box.
The Options dialog box appears.

Scroll the Colors list; fields related to the XPath Query Editor are prefixed with
XPath.

Use the palette to change the color of the tokens as desired.

Click OK.

Working with XPath Queries

When you display the XPath Query Editor, an empty query is created for you. The query
name, Query1, is displayed on a tab in the XPath Query Editor window.You can start
typing the XPath expression on the first line in the editing pane; use the Enter key to move
the cursor to a new line.
Tip Line numbers are displayed in the editing pane if you have enabled them for XML
documents. Click Tools > Options > General > Editor General to change this setting.

You can create up to sixty-four queries for a single document; each is given the name
Queryn, where n is a unique number incremented by one. You cannot name queries.
Queries are saved with the project. Changes you make either to query expressions, or
creating and deleting queries are saved when you save the project, and not the document.

Executing the Query

Stylus Studio executes XPath query expressions based on the cursors current position in
the document, regardless of which editor is currently active.
Stylus Studio User Guide

697

Writing XPath Expressions

To execute the query:

Click the Execute button on the XPath Query Editor tool bar (
).
Stylus Studio processes the query and displays the result in the results pane.

Alternatives:

Press F5.
or

Right-click the query panel in the XPath Query Editor and select Execute Query from
the short cut menu.

Creating a New Query

To create a new query:

Click the New XPath Query button on the XPath Query Editor tool bar (
A new tab appears in the XPath Query Editor.

Alternative:

Right-click the query panel in the XPath Query Editor and select New XPath Query
from the short cut menu.

Deleting a Query
To delete a query:

Click the Delete button on the XPath Query Editor tool bar (
).
The tab associated with the query is removed from the XPath Query Editor. The query
itself is deleted when you save the project.

Alternative:

Right-click the query panel in the XPath Query Editor and select New XPath Query
from the short cut menu.

698

Stylus Studio User Guide

Using the XPath Query Editor

Working with Query Results

Query results are shown in the XPath Query Editor in the results pane as a number of hits
and include the type of XML tag and value of each hit, as shown here.

Figure 318. XPath Result Pane

When you click on a result node, Stylus Studios back-mapping feature highlights the line
in the XML document that supplied the value for the result node you selected.

Opening Query Results as a New Document

After you have executed a query, you can optionally choose to display the query result in
a new XML document. If the result contains only elements, Stylus Studio creates a root
element (named <xqr:xpath-query-result>) to ensure that the document is wellformed.
To open a query result as an XML document:

Execute the query, and then

Click the Open result in a new XML document button on the XPath Query Editor tool
bar (
).

Stylus Studio User Guide

699

Writing XPath Expressions

Alternative:

Right-click the query pane in the XPath Query Editor and select Open result in a new
XML document from the shortcut menu.

Working with Namespaces

When the XML document declares one or more namespaces, those namespaces are
displayed in the namespace pane, as shown here:

Figure 319. Namespaces Pane

In addition to the namespace URI, Stylus Studio displays the namespace prefix declared
in the XML document, if any, and a prefix that is used when creating XPath query
expressions.
If one namespace prefix clashes with another in the XML document, Stylus Studio
renames the second prefix by adding a number to the end of the original prefix name to
make it unique for example, if two namespaces have the prefix bks, the second is
renamed bks1. Similarly, if no namespace prefix has been declared, Stylus Studio creates
a default namespace prefix, ns1. Namespace declarations in the XML document are not
changed.
Namespace prefixes defined for the query

Allow you to execute the query with the root node of the document as the current
context node

Simplify the process of entering XPath expressions in the query pane

Changes saved to the XML document are reflected in the namespace pane when you click
on the namespace pane or query pane.

Viewing/Changing Namespace Prefixes

You must use the value in the Query for Prefix field when writing XPath query
expressions; you can specify your own prefix if want to use one other than the one
provided by Stylus Studio.
700

Stylus Studio User Guide

Sample Data for Examples and Practice

To change a namespace prefix:
1.

Click the Show Namespaces button (

) if the namespace pane is not already
displayed.
The namespace pane shows any namespaces that have been defined for the current
XML document, as well their associated namespace prefixes, if any.

Optionally, change the value in the Prefix for Query field.

Sample Data for Examples and Practice

The best way to learn how to query data is to practice using XPath. To prepare you for
practicing with XPath queries, this section provides a review of the basic structure of an
XML document. An understanding of this structure is crucial to defining queries that
return the data you want. Following the review, this section includes the XML data on
which the query examples operate. The last part of this section provides instructions for
running queries on sample data.
The topics in this section include

About XML Document Structure on page 701

A Sample XML Document on page 703

Tree Representation of a Sample XML Document on page 704

Steps for Trying the Sample Queries on page 707

About XML Document Structure

The XPath processor operates on a tree representation of XML data that looks like the
following figure:
Root Node

Comment...

Element...

Stylus Studio User Guide

Processing
Instruction...

Comment...

Document
Element

Processing
Instruction...

Text...

701

Writing XPath Expressions

The root node has no actual text associated with it. You can think of the file name as the
root node. A document can include zero or more comments and zero or more processing
instructions.
A document element is required, and there can be only one. The document element
contains all elements in the document. For example:
bookstore.xml

specialty
="novel"

<book>

<book>

<my:book>

xmlns:my="http://www.placeholder-name-here.com/schema/"

In the preceding figure, bookstore.xml is the name of a file that contains XML data. There
is a comment near the beginning of the document that starts with "This file represents
a ..." The document element is bookstore. The immediate children of bookstore include
an attribute, a namespace declaration (not supported by Stylus Studio), three book
elements (one is in the my namespace), and a magazine element. The book and magazine
elements contain elements and attributes, which are shown in the figure that appears in
Tree Representation of a Sample XML Document on page 704.

702

Stylus Studio User Guide

Sample Data for Examples and Practice

A Sample XML Document

The examples in this section are based on the following XML data. This data is in the
bookstore.xml file, which is in the examples directory of your installation directory.
<?xml version="1.0"?>

<bookstore specialty="novel"
xmlns:my="http://www.placeholder-name-here.com/schema/">
<book style="autobiography">
<title>Seven Years in Trenton</title>
<author>
<first-name>Joe</first-name>
<last-name>Bob</last-name>
<award>Trenton Literary Review Honorable Mention</award>
</author>
<pub_date>1997-11-30</pub_date>
<price>12</price>
</book>
<book style="textbook">
<title>History of Trenton</title>
<author>

<first-name>Mary</first-name>
<last-name>Bob</last-name>
<publication>
Selected Short Stories of
<first-name>Mary</first-name>
<last-name>Bob</last-name>
<price>14</price>
</publication>
</author>
<pub_date>1994-07-21</pub_date>
<price>55</price>
</book>
<magazine style="glossy" frequency="monthly">
<title>Tracking Trenton</title>
<price>2.50</price>
<subscription price="24" per="year"/>
</magazine>

Stylus Studio User Guide

703

Writing XPath Expressions

<book style="novel" id="myfave">
<title>Trenton Today, Trenton Tomorrow</title>
<author>

<first-name>Toni</first-name>
<last-name>Bob</last-name>
<degree from="Trenton U">B.A.</degree>
<degree from="Harvard">Ph.D.</degree>
<award>Pulitzer</award>
<publication>Still in Trenton</publication>
<publication>Trenton Forever</publication>
</author>
<price intl="canada" exchange="0.7">6.50</price>
<excerpt>

<p>It was a dark and stormy night.</p>

<p>But then all nights in Trenton seem dark and
stormy to someone who has gone through what
<emph>I</emph> have.</p>
<definition-list>
<term>Trenton</term>
<definition>misery</definition>
</definition-list>
</excerpt>
</book>
<my:book style="leather" price="29.50">
<my:title>Whos Who in Trenton</my:title>
<my:author>Robert Bob</my:author>
</my:book>
<book style="tour">
<title>Tar Pits in Trenton</title>
<price>1.99</price>
</book>
</bookstore>

Tree Representation of a Sample XML Document

When you query a document, it can be helpful to think of a tree representation of your
data. A tree that represents the bookstore.xml document appears in Figure 320 (and is

704

Stylus Studio User Guide

Sample Data for Examples and Practice

continued in Figure 321). To use Stylus Studio to view a similar tree for any XML
document, open the XML document in Stylus Studio and select the Tree tab.

Figure 320. Tree Display of an XML Document

Stylus Studio User Guide

705

Writing XPath Expressions

Figure 321. Tree Display of an XML Document (continued)

706

Stylus Studio User Guide

Getting Started with Queries

Steps for Trying the Sample Queries

To try the queries in this section, or any other queries you want to run on the
bookstore.xml document, follow these instructions:
1.

In Stylus Studio, open bookstore.xml. You can find it in the examples directory of your
installation directory.

Open the XPath Query Editor if it is not already displayed. See Displaying the XPath
Query Editor on page 696 if you need help with this step.

Type a query. For example: /bookstore/book/author.

Press F5, or click Execute Query (

Stylus Studio displays the results in the Query Output window.

Getting Started with Queries

This section provides information to get you started using queries. It does not provide
complete information about how to define a query. Instead, it provides instructions for
defining typical queries you might want to run. There are numerous cross-references to
later sections that provide complete information about a particular query construct.
The topics discussed in this section include

Obtaining All Marked-Up Text on page 708

Obtaining a Portion of an XML Document on page 708

Obtaining All Elements of a Particular Name on page 709

Obtaining All Elements of a Particular Name from a Particular Branch on page 710

Different Results from Similar Queries on page 711

Queries That Return More Than You Want on page 711

Specifying Attributes in Queries on page 712

Filtering Results of Queries on page 713

Wildcards in Queries on page 716

Calling Functions in Queries on page 717

Case Sensitivity and Blank Spaces in Queries on page 718

Precedence of Query Operators on page 719

Stylus Studio User Guide

707

Writing XPath Expressions

Obtaining All Marked-Up Text

When you query a document, you do not usually want to obtain all marked-up text.
However, an understanding of queries that return all marked-up text makes it easier to
define a query that retrieves just what you want.
The following figure shows a complete query (/bookstore) and the way the XPath
processor interprets it:
/bookstore

Start at the
root node.

Search immediate children

and return the bookstore
element.

This query returns the bookstore element. Because the bookstore element is the document
element, which contains all elements and attributes in the document, this query returns all
marked-up text.
In the query, the initial forward slash (/) instructs the XPath processor to start its search at
the root node.
Suppose you run the following query on bookstore.xml:
/book

This query returns an empty set. It searches the immediate children of the root node for
an element named book. Because there is no such element, this query does not return any
marked-up text. Note that this query does not return an error. The query runs successfully,
but the XPath processor does not find any elements that match the query. All book
elements are grandchildren of the root node, and the XPath processor only checks the
children of the root node.

Obtaining a Portion of an XML Document

Usually, you use a query to obtain a portion of an XML document. To obtain the particular
elements that you want, you must understand how to obtain an element that is a child of
the document element. With this information, you can obtain any elements in the
document.

708

Stylus Studio User Guide

Getting Started with Queries

The following figure shows how the XPath processor interprets the /bookstore/book
query:
/ bookstore / book

Start at the root

node.

Search immediate
children for the
bookstore element.

This is a
separator
between

Search immediate children

of bookstore and return all
book elements.

When the XPath processor starts its search at the root node, there is only one element
among the immediate children of the root node. This is the document element. In this
example, bookstore is the document element.
The query in this figure returns the book elements that are children of bookstore. This
query does not return the my:book element, which is also a child of bookstore.
Now you can define queries that obtain any elements you want. For example:
/bookstore/book/title

This query returns title elements contained in book elements that are contained in
bookstore.

Obtaining All Elements of a Particular Name

Sometimes you want all like-named elements regardless of where they are in a document.
In this case, you do not need to start at the root node and navigate to the elements you
want.
For example, the following query returns all last-name elements in any XML document:
//last-name

The double forward slash (//) at the beginning of a query instructs the XPath processor to
start at the root node and search the entire document. In other words, the XPath processor
searches all descendants of the root node.
If you perform this query on bookstore.xml, it returns the last-name elements that are
children of author elements, and it also returns the last-name element that is a child of a
publication element.

Stylus Studio User Guide

709

Writing XPath Expressions

Obtaining All Elements of a Particular Name from a

Particular Branch
Although sometimes you might want all like-named elements wherever they are in a
document, other times you might want only those like-named elements from a particular
part of the document (branch of the tree).
For example, you might want all price elements contained in book elements, but not price
elements contained in magazine elements. The query is to return such a result is:
/bookstore/book//price

This query returns all price elements that are contained in book elements. Some of these
price elements are immediate children of book elements. One returned price element is a

great-grandchild of the second book element. The following figure shows how the XPath
processor interprets this query:
/ bookstore / book // price

Start at the
root node.

710

Search
immediate
children for the
bookstore

This is a
step
separator.

Search
immediate
children of
bookstore
for book

Search all book

elements and all
descendants of all
book elements.

For each node that

is searched,
search its children
for price elements.
Return any price

Stylus Studio User Guide

Getting Started with Queries

Different Results from Similar Queries

Some queries can look very similar but return very different results. The following figure
shows this.
This query returns the empty
set. No author elements are
immediate children of

/ bookstore / author

Start at
the
root
node.

Search
immediate
children
for the
bookstore
element.

This is a step
separator.
Search all
descendants of
bookstore.

Search
immediate
children of
bookstore.

Return all
author
elements.

/ bookstore // author

This query returns all author elements

that are anywhere in the bookstore
element. Since bookstore is the
document element, this is all author

Queries That Return More Than You Want

Suppose you want the titles of all the books. You might decide to define your query like
this:
//title

This query does return all titles of books, but it also returns the title of a magazine. This
query instructs the XPath processor to start at the root node, search all descendants, and
return all title elements. In bookstore.xml, this means that the query returns the title of
the magazine in addition to the titles of books. In some other document, if all titles are
contained in book elements, this query returns exactly what you want.
To query and obtain only the titles of books, you can use either of the following queries.
They obtain identical results. However, the first query runs faster.
/bookstore/book/title
//book/title

The first query runs faster because it uses the child axis, while the second query uses the
descendent-or-self axis. In general, the simpler axes, such as child, self, parent, and
Stylus Studio User Guide

711

Writing XPath Expressions

ancestor,

are faster than the more complicated axes, such as descendent, preceding,
following, preceding-sibling, and following-sibling. This is especially true for large
documents. Whenever possible, use a simpler axis.

Specifying Attributes in Queries

To specify an attribute name in a query, precede the attribute name with an at sign (@).
The XPath processor treats elements and attributes in the same way wherever possible.
For example:
//@style

This query returns the style attributes associated with the magazine, the three books, and
the my:book element. That is, it returns all the style attributes in the document. It does not
return the elements that contain the attributes.
Following is another query that includes an attribute:
/bookstore/book/@style

This query returns the three style attributes for the three book elements.
The following query returns the style attribute of the context node:
@style

If the context node does not have a style attribute, the result set is empty.
The next query returns the exchange attribute on price elements in the current context:
price/@exchange

Following is an example that is not valid because attributes cannot have subelements:
price/@exchange/total

Following is a query that finds the style attribute for all book elements in the document:
//book/@style

712

Stylus Studio User Guide

Getting Started with Queries

Restrictions
Attributes cannot contain subelements. Consequently, you cannot apply a path operator to
an attribute. If you try to, you receive a syntax error.
Attributes are inherently unordered. Consequently, you cannot apply a position number to
an attribute. If you try to, you receive a syntax error.

Attributes and Wildcards

You can use an at sign (@) and asterisk (*) together to retrieve a collection of attributes.
For example, the following query finds all attributes in the current context:
@*

Filtering Results of Queries

Sometimes you want to retrieve only those elements that meet a certain condition. For
example, you might want information about a particular book. In this case, you can
include a filter in your query. You enclose filters in brackets ( [ ] ).
The following figure shows how the XPath processor interprets a query with a filter:
/ bookstore / book [ title = "History of Trenton" ]

Start at the
root node.

Search
immediate
children for
the
bookstore

Step
separator.

Search
immediate
children of
bookstore for
book

Check book
elements
against the
subquery in

Return only
those book
elements that
contain title
child elements
that contain

End
filter.

This query checks each book element to determine whether it has a title child element
whose value is "History of Trenton". If it does, the query returns the book element. Using
the sample data, this query returns the second book element.
The following topics provide details about filters:

Quotation Marks in Filters on page 714

More Filter Examples on page 714

How the XPath Processor Evaluates a Filter on page 715

Stylus Studio User Guide

713

Writing XPath Expressions

Multiple Filters on page 715

Filters and Attributes on page 716

Quotation Marks in Filters

Suppose you define the following filter:
[title="History of Trenton"]

If you need to specify this filter as part of an attribute value, use single quotation marks
instead of double quotation marks. This is because the attribute value itself is (usually)
inside double quotation marks. For example:
<xsl:value-of select="/bookstore/book[title='History of Trenton']">

Strings within an expression may contain special characters such as [, {, &, , /, and others,
as long as the entire string is enclosed in double quotes ("). When the string itself contains
double quotes, you may enclose it in single quotes ('). When a string contains both single
and double quotes, you must handle these segments of the string as if they were individual
phrases, and concatenate them.

More Filter Examples

Following is another example of a query with a filter clause. This query returns book
elements if the price of the book is greater than 25 dollars:
/bookstore/book[price > 25]

The next query returns author elements if the author has a degree:
//author[degree]

The next query returns the date attributes that match "3/1/00":
//@date[.="3/1/00"]

The next query returns manufacturer elements in the current context for which the rwdrive
attribute of the model is the same as the vendor attribute of the manufacturer:
manufacturer[model/@rwdrive = @vendor]

714

Stylus Studio User Guide

Getting Started with Queries

How the XPath Processor Evaluates a Filter

You can apply constraints and branching to a query by specifying a filter clause. The filter
contains a query, which is called the subquery. The subquery evaluates to a Boolean value,
or to a numeric value. The XPath processor tests each element in the current context to
see if it satisfies the subquery. The result includes only those elements that test true for the
subquery.
The XPath processor always evaluates filters with respect to a context. For example, the
expression book[author] means for every book element that is found in the current context,
determine whether the book element contains an author element. For example, the
following query returns all books in the current context that contain at least one excerpt:
book[excerpt]

The next query returns all titles of books in the current context that have at least one
excerpt:
book[excerpt]/title

Multiple Filters
You can specify any number of filters in any level of a query expression. Empty filters
( [ ] ) are not allowed.
A query that contains one or more filters returns the rightmost element that is not in a filter
clause. For example:
book[excerpt]/author[degree]

The previous query returns author elements. It does not return degree elements. To be
exact, this query returns all authors who have at least one degree if the author is of a book
for which the document contains at least one excerpt. In other words, for all books in the
current context that have excerpts, this query finds all authors with degrees.
The following query finds each book child of the current context that has an author with
at least one degree:
book[author/degree]

The next query returns all books in the current context that have an excerpt and a title:
book[excerpt][title]

Stylus Studio User Guide

715

Writing XPath Expressions

Filters and Attributes

Following is a query that finds all child elements of the current context with specialty
attributes:
*[@specialty]

The following query returns all book children in the current context with style attributes:
book[@style]

The next query finds all book child elements in the current context in which the value of
the style attribute of the book is equal to the value of the specialty attribute of the
bookstore element:
book[/bookstore/@specialty = @style]

Wildcards in Queries
In a query, you can include an asterisk (*) to represent all elements. For example:
/bookstore/book/*

This query searches for all book elements in bookstore. For each book element, this query
returns all child elements that the book element contains.
The * collection returns all elements that are children of the context node, regardless of
their tag names.
The next query finds all last-name elements that are grandchildren of book elements in the
current context:
book/*/last-name

The following query returns the grandchild elements of the current context.
*/*

716

Stylus Studio User Guide

Getting Started with Queries

Restrictions
Usually, the asterisk (*) returns only elements. It does not return processing instructions,
attributes, or comments, nor does it include attributes or comments when it maintains a
count of nodes. For example, the following query returns title elements. It does not
return style attributes.
/bookstore/book/*[1]

Wildcards in strings are not allowed. For example, you cannot define a query such as the
following:
/bookstore/book[author=" A* "]

Attributes
To use a wildcard for attributes, you can specify @*. For example:
/bookstore/book/@*

For each book element, this query returns all attributes. It does not return any elements.

Calling Functions in Queries

The XPath processor provides many functions that you can call in a query. This section
provides some examples to give you a sense of how functions in queries work. Many
subsequent sections provide information about invoking functions in queries. For a
complete list of the functions you can call in a query, see XPath Functions Quick
Reference on page 772.
Following is a query that returns a number that indicates how many book elements are in
the document:
count(//book)

In format descriptions, a question mark that follows an argument indicates that the
argument is optional. For example:
string substring(string, number, number?)

This function returns a string. The name of the function is substring. This function takes
two required arguments (a string followed by a number) and one optional argument (a
number).
Stylus Studio User Guide

717

Writing XPath Expressions

Case Sensitivity and Blank Spaces in Queries

Queries are case sensitive. This applies to every part of the query, including operators,
strings, element and attribute names, and function names.
For example, suppose you try this query:
/Bookstore

This query returns an empty set because the name of the document element is bookstore
and not Bookstore.
Blank spaces in queries are not significant unless they appear within quotation marks.

718

Stylus Studio User Guide

Getting Started with Queries

Precedence of Query Operators

The precedence of query operators varies for XPath 1.0 and XPath 2.0, as shown in the
following tables. In these tables, operators are listed in order of precedence, with highest
precedence being first; operators in a given row have the same precedence.
Table 92. Query Operator Precedence XPath 1.0
Operation Type

XPath Operators

Grouping

( )

Filter

[ ]

Unary minus

Multiplication

*, div, mod

Addition

+, -

Relational
(Comparison)

= != < <= > >=

Union

Negation

not

Conjunction

and

Disjunction

Table 93. Query Operator Precedence XPath 2.0

Operation Type

XPath Operators

Sequence separator

Conjunction

and

Type matching

instance of

Assertion

treat

Conversion test

castable

Conversion

cast

Stylus Studio User Guide

719

Writing XPath Expressions

Table 93. Query Operator Precedence XPath 2.0
Operation Type

XPath Operators

Relational
(Comparison)

eg, ne, lt, le, gt, ge, =, !=, <, <=, >, >=,
is, <<, >>

Range

Addition

+, -

Multiplication

*, div, idiv, mod

Unary

unary -, unary +

Union

union, |

Select set

intersect, except

Navigation

/, //

Filter

[ ]

Specifying the Nodes to Evaluate

Consider the bookstore tree in the sample data. If you query the entire tree for all author
elements, the result contains a number of author elements. If you query only one branch
of the tree, the result contains only one author element. The result of the query depends
on which nodes the XPath processor evaluates in the execution of the query.
This section discusses the following topics:

Understanding XPath Processor Terms on page 721

Starting at the Context Node on page 723

About Root Nodes and Document Elements on page 723

Starting at the Root Node on page 723

Descending Along Branches on page 724

Explicitly Specifying the Current Context on page 725

Specifying Children or Descendants of Parent Nodes on page 726

Examples of XPath Expression Results on page 726

Syntax for Specifying an Axis in a Query on page 727

720

Stylus Studio User Guide

Specifying the Nodes to Evaluate

Supported Axes on page 728

Axes That Represent the Whole XML Document on page 733

Understanding XPath Processor Terms

To use the context operators, it is important to understand the following terms:

Axis
An axis specifies a list of nodes in relation to the context node. For example, the ancestor
axis contains the ancestor nodes of the context node. The child axis contains the
immediate children of the context node. See Syntax for Specifying an Axis in a Query
on page 727.

Context Node
A context node is the node the XPath processor is currently looking at. The context node
changes as the XPath processor evaluates a query. If you pass a document to the XPath
processor, the root node is the initial context node. If you pass a node to the XPath
processor, the node that you pass is the initial context node. During evaluation of a query,
the initial context node is also the current node.

Context Node Set

A context node set is a set of nodes that the XPath processor evaluates.

Current Node
Current node is the node that the XPath processor is looking at when it begins evaluation
of a query. In other words, the current node is the first context node that the XPath
processor uses when it starts to execute the query. During evaluation of a query, the
current node does not change. If you pass a document to the XPath processor, the root
node is the current node. If you pass a node to the XPath processor, that node is the current
node.

Document Element
The document element is the element in a document that contains all other elements. The
document element is an immediate child of the root node. When you obtain the document
element of a document, you obtain all marked-up text in that document.
Stylus Studio User Guide

721

Writing XPath Expressions

Filter
A filter in a query specifies a restriction on the set of nodes to be returned. For example,
the filter in the following query restricts the result set to book elements that contain at least
one excerpt element:
book[excerpt]

Location Path Expression

A location path expression is an XPath expression. It has the following format:
[/]LocationStep[/LocationStep]...

Location Step
An XPath expression consists of one or more location steps. A location step has the
following format:
[axis::]node_test[[filter] [filter]...]

Node Test
You apply a node test to a list of nodes. A node test returns nodes of a particular type or
nodes with a particular name. For example, a node test might return all comment nodes, or
all book elements.

Root Node
The root node is the root of the tree. It does not occur anywhere else in the tree. The
document element node for a document is a child of the root node. The root node also has
as children processing instructions and comment nodes representing processing
instructions and comments that occur in the prolog and after the end of the document
element.

722

Stylus Studio User Guide

Specifying the Nodes to Evaluate

Starting at the Context Node

Following is a query that looks for all child author elements in the current context:
author

This query is simply the name of the element you want to search for. If the context node
is any one of the book elements, this query returns one author element. If the context node
is any other node, this query returns the empty set.

About Root Nodes and Document Elements

A root node is the topmost node in the tree that represents the contents of an XML
document. The root node can contain comments, a declaration, and processing
instructions, as well as the document element. The document element is the element that
contains all other elements; that is, the document element contains elements that are in the
document but that are not immediate children of the root node.

Starting at the Root Node

To specify that the XPath processor should start at the root node when it evaluates nodes
for a query, insert a forward slash (/) at the beginning of the query.
In an XML document, there is no text that corresponds to the root node. Externally, a root
node is really a concept. Internally, there are data structures that represent this concept,
but there is no text that you can point to and call a root node.
The following query instructs the XPath processor to start at the root node, as indicated
by the forward slash at the beginning of the query.
/bookstore

This query searches the children of the root node for a bookstore element. Because the
name of the document element is bookstore, the query returns it. If the name of the
document element is not bookstore, this query returns an empty set.
The following query returns the entire document, starting with the root node. As you can
see, the entire query is just a forward slash:
/

Stylus Studio User Guide

723

Writing XPath Expressions

This query returns everything comments, declarations, processing instructions, the

document element, and any elements, attributes, comments, and processing instructions
that the document element contains.

Descending Along Branches

Sometimes you want the XPath processor to evaluate all nodes that are descendants of a
node and not just the immediate children of that node. This amounts to operating on a
branch of the tree that forms the document.
To specify the evaluation of descendants that starts at the root node, insert two forward
slashes (//) at the beginning of a query.
To specify the evaluation of descendants that starts at the context node, insert a dot and
two forward slashes (.//) at the beginning of the query.
Following is a query that finds all last-name elements anywhere in the current document:
//last-name

Suppose the context node is the first book element in the document. The following query
returns a single last-name element because it starts its search in the current context:
.//last-name

At the beginning of a query, / or // instructs the XPath processor to begin to evaluate

nodes at the root node. However, between tag names, / is a separator, and // is an
abbreviation for the descendant-or-self axis.
The // selects from all descendants of the context node set. For example:
book//award

This query searches the current context for book child elements that contain award
elements. If the bookstore element is the context node, this query returns the two award
elements that are in the document.
For the sample bookstore data, the following two queries are equivalent. Both return all
last-name elements in the document.
//last-name
//author//last-name

724

Stylus Studio User Guide

Specifying the Nodes to Evaluate

The first query returns all last-name elements in the sample document or in any XML
document. The second query returns all last-name elements that are descendants of
author elements. In the sample data, last-name elements are always descendants of author
elements, so this query returns all last-name elements in the document. But in another
XML document, there might be last-name elements that are not descendants of author
elements. In that case, the query would not return those last-name elements.
Tip: // is useful when the exact structure is unknown. If you know the structure of your
document, avoid the use of //. A query that contains // is slower than a query with an
explicit path.

Explicitly Specifying the Current Context

If you want to explicitly specify the current context node, place a dot and a forward slash
(./) in front of the query. This construct typically appears in queries that contain filters
(see Filtering Results of Queries on page 713) . The following two queries are
equivalent:
./author
author

Remember, if you specify the name of an element as a complete query (for example, foo),
you obtain only the foo elements that are children of the current context node. You do not
necessarily obtain all foo elements in the document.
You can also specify the dot notation (.) to indicate that you want the XPath processor to
manipulate the current context. For example:
//title [. = "History of Trenton"]

In this example, the XPath processor finds all title elements. The dot indicates the
context node. This causes the XPath processor to check each title in turn to determine
whether its string value is History of Trenton.

Stylus Studio User Guide

725

Writing XPath Expressions

Specifying Children or Descendants of Parent Nodes

Sometimes you want a query to return information about a sibling of the context node.
One way to obtain a sibling is to define a query that navigates up to the parent and then
down to the sibling.
For example, suppose the context node is the first author element. You want to find out
the title associated with this author. The following query returns the associated title
element:
../title

The double dot (..) at the beginning of the query instructs the XPath processor to select
the parent of the context node. This query returns the title elements that are children of
the first book element, which is the parent of the first author element. In the bookstore.xml
document, there is only one such title element.
Now suppose that the context node is still the first author element and you want to obtain
the style attribute for the book that contains this author. The following query does this:
../@style

The double dot notation need not appear at the beginning of a query. It can appear
anywhere in a query string, just like the dot notation.

Examples of XPath Expression Results

Table 94 provides examples of XPath expression results:
Table 94. XPath Expression Results

726

Expression

Result

Returns the document element of the document if it is an a element

/a/b

Returns all b elements that are immediate children of the document

element, which is the a element

//a

Returns all a elements in the document

//a/b

Returns all b elements that are immediate children of a elements that

are anywhere in the document

Stylus Studio User Guide

Specifying the Nodes to Evaluate

Table 94. XPath Expression Results
Expression

Result

a or ./a

Returns all a elements that are immediate children of the context

node

a/b

Returns all b elements that are immediate children of a elements that

are immediate children of the context node

a//b

Returns all b elements that descend from a elements that are

immediate children of the context node

.//a

Returns all a elements in the document tree branch that starts with
the context node

../a

Returns all a elements in the document tree branch that are children
of the parent node of the context node.

Syntax for Specifying an Axis in a Query

The previous sections provide examples of XPath expression syntax that uses
abbreviations. This section introduces you to the axis syntax that many of the
abbreviations represent. For a list of XPath abbreviations, see XPath Abbreviations
Quick Reference on page 777.
You can use axis syntax to specify a location path in a query. An axis specifies the tree
relationship between the nodes selected by an expression and the context node. The
syntax for specifying an axis in a query is as follows:
axis_name::node_test

The axis names are defined in Supported Axes on page 728.

A node test is a simple expression that tests for a specified node type or node name. For
example:

node() matches any type of node.

text() matches text or CDATA nodes.

comment() matches comment nodes.

processing-instruction() matches any processing instruction.

processing-instruction(name) matches processing instructions whose target is name.

Stylus Studio User Guide

727

Writing XPath Expressions

name matches

elements or attributes whose name is name.

* matches any elements or any attributes.

XPath 2.0 adds additional tests, such as

element() matches any element node

attribute() matches any attribute node

document-node() matches any document node

In addition, you can follow the node test with any number of filters.

Supported Axes
The XPath processor supports all XPath axes:

child

descendant

parent

ancestor

following-sibling

preceding-sibling

following

preceding

attribute

namespace

self

descendant-or-self

ancestor-or-self

About the child Axis

The child axis contains the children of the context node. The following examples select
the book children of the context node:
child::book
book

If the context node is the bookstore element, each of these queries return the book
elements in bookstore.xml. When you do not specify an axis, the child axis is assumed.

728

Stylus Studio User Guide

Specifying the Nodes to Evaluate

About the descendant Axis

The descendant axis contains the descendants of the context node. A descendant is a child
or a child of a child, and so on. The descendant axis never contains attribute nodes. The
following example selects the first-name element descendants of the context node:
descendant::first-name

If the context node is the bookstore element, this query returns all first-name elements in
the document. If the context node is the first publication element, this query returns the
first-name element that is in the publication element.

About the parent Axis

The parent axis contains the parent of the context node, if there is one. The following
example selects the parent of the context node if it is a title element:
parent::title

If the first title element in bookstore.xml is the context node, this query returns the first
book element.
Note that dot dot (..) is equivalent to parent::node().

About the ancestor Axis

The ancestor axis contains the ancestors of the context node. The ancestors of the context
node consist of the parent of the context node and the parent's parent, and so on. The
ancestor axis always includes the root node, unless the context node is the root node. The
following example selects the book ancestors of the context node:
ancestor::book

If the context node is the first title element in bookstore.xml, this query returns the first
book element.

Stylus Studio User Guide

729

Writing XPath Expressions

About the following-sibling Axis

The following-sibling axis contains all the siblings of the context node that come after
the context node in document order. If the context node is an attribute node or namespace
node, the following-sibling axis is empty. The following example selects the next book
sibling of the context node:
following-sibling::book[position()=1]

If the context node is the first book element in

second book element.

bookstore.xml, this

query returns the

About the preceding-sibling Axis

The preceding-sibling axis contains all the siblings of the context node that precede the
context node in reverse document order. If the context node is an attribute node or
namespace node, the preceding-sibling axis is empty. The following example selects the
closest previous book sibling of the context node:
preceding-sibling::book[position()=1]

If the context node is the third book element in bookstore.xml, this query returns the
second book element. If the context node is the first book element, this query returns the
empty set.

About the following Axis

The following axis contains the nodes that follow the context node in document order.
This can include

Following siblings of the context node

Descendants of following siblings of the context node

Following siblings of ancestor nodes

Descendants of following siblings of ancestor nodes

The following axis never includes

Ancestors or descendants of the context node

Attribute nodes

Namespace nodes

730

Stylus Studio User Guide

Specifying the Nodes to Evaluate

The following example selects the book elements that are following siblings of the context
node and that follow the context node in document order:
following::book

If the context node is the first book element, this query returns the last three book elements.
If the context node is the second book element, this query returns only the third and fourth
book elements.

About the preceding Axis

The preceding axis contains the nodes that precede the context node in reverse document
order. This can include:

Preceding siblings of the context node

Descendants of preceding siblings of the context node

Preceding siblings of ancestor nodes

Descendants of preceding siblings of ancestor nodes

The preceding axis never includes

Ancestors or descendants of the context node

Attribute nodes

Namespace nodes
The following example selects the book elements that are preceding siblings of the context
node and that precede the context node in document order:
preceding::book

If the third book element is the context node, this query returns the first two book elements.
If the first book element is the context node, this query returns the empty set.

About the attribute Axis

The attribute axis contains the attributes of the context node. The attribute axis is
empty unless the context node is an element. The following examples are equivalent. They
both select the style attributes of the context node. The at sign (@) is an abbreviation for
the attribute axis.
attribute::style
@style

Stylus Studio User Guide

731

Writing XPath Expressions

If the context node is the second book element, this query returns a style attribute whose
value is textbook.

About the namespace Axis

The namespace axis contains the namespace nodes that are in scope for the context node.
This includes namespace declaration attributes for the

Context node

Ancestors of the context node

If more than one declaration defines the same prefix, the resulting node set includes only
the definition that is closest to the context node.
If the context node is not an element, the namespace axis is empty.
For example, if an element is in the scope of three namespace declarations, its namespace
axis contains three namespace declaration attributes.

About the self Axis

The self axis contains just the context node itself. The following example selects the
context node if it is a title element:
self::title

Note that dot (.) is equivalent to self::node().

About the descendant-or-self Axis

The descendant-or-self axis contains the context node and the descendants of the context
node. The following example selects the first-name element descendants of the context
node and the context node itself if it is a first-name element:
descendant-or-self::first-name

If the context node is the first-name element that is in the author element in the second
book element, this query returns just the context node. If the context node is the second
book element, this query returns the two first-name elements contained in the second book
element.
Note that // is equivalent to descendant-or-self::node(), while //name is equivalent to
descendant-or-self::node()/child::name.

732

Stylus Studio User Guide

Specifying the Nodes to Evaluate

About the ancestor-or-self Axis

The ancestor-or-self axis contains the context node and the ancestors of the context
node. The ancestor-or-self axis always includes the root node. The following example
selects the author element ancestors of the context node and the context node itself if it is
an author element:
ancestor-or-self::author

If the context node is the award element in the first book element, this query returns the
first author element.

Axes That Represent the Whole XML Document

The following group of axes represent an entire XML document:

ancestor

preceding

self

following

descendant

There is no overlap among these axes, as shown in the following figure:

ancestor Axis

preceding Axis

self Axis

following Axis

descendant Axis

Stylus Studio User Guide

733

Writing XPath Expressions

Handling Strings and Text

This section includes the following topics:

Searching for Strings on page 734

Manipulating Strings on page 737

Obtaining the Text Contained in a Node on page 740

Searching for Strings

This section provides information about searching for strings. This section discusses the
following topics:

Finding Identical Strings on page 734

Finding Strings That Contain Strings You Specify on page 735

Finding Substrings That Appear Before Strings You Specify on page 735

Finding Substrings That Appear After Strings You Specify on page 736

Finding Substrings by Position on page 736

Finding Identical Strings

In a document, you can search for text that is an exact match with what you specify in
your query. For example, consider the following query:
//name [ . ="Lu" ]

This query finds all name elements that contain only the text Lu. It would return elements
like these:
<name>Lu</name>
<name>
<firstname>Lu</firstname>
</name>

The same query does not return elements like these:

734

Stylus Studio User Guide

Handling Strings and Text

The XPath processor does not return the first name element because the comparison is
between "Lu" and "Lu Chen". The query does not return the second name element because
the XPath processor concatenates the two strings "Lu" and "Chen" before it makes the
evaluation. Consequently, the comparison is between "Lu" and "LuChen". Note that the
XPath processor does not insert a space between text nodes that it concatenates.

Case Sensitivity
Searches are case sensitive. A search for "Lu" does not return "lu".

Finding Strings That Contain Strings You Specify

To obtain elements that contain a particular string, call the contains() function. The
format is
boolean contains(string, string)

The contains() function returns true if the first argument string contains the second
argument string, and otherwise returns false. For example, the following query returns all
books that have a title that contains the string "Trenton":
/bookstore/book[contains(title, "Trenton")]

When the first argument is a node list, the XPath processor tests only the string value of
the node in the node list that is first in document order. Any subsequent nodes are ignored.

Finding Substrings That Appear Before Strings You Specify

To obtain a substring that appears before a string you specify, call the substring-before()
function. The format is
string substring-before(string, string)

The substring-before() function returns the substring of the first argument string that
precedes the first occurrence of the second argument string in the first argument string.
This function returns the empty string if the first argument string does not contain the
second argument string. For example, the following call returns "1999":
substring-before("1999/04/01","/")

Stylus Studio User Guide

735

Writing XPath Expressions

Finding Substrings That Appear After Strings You Specify

To obtain a substring that appears after a string you specify, call the substring-after()
function. The format is
string substring-after(string, string)

The substring-after() function returns the substring of the first argument string that
follows the first occurrence of the second argument string in the first argument string. This
function returns the empty string if the first argument string does not contain the second
argument string. For example, the following call returns "04/01":
substring-after("1999/04/01","/")

Finding Substrings by Position

To obtain a substring that is in a particular position within its string, call the substring()
function. The format is
string substring(string, number, number?)

The substring() function returns the substring of the first argument, starting at the
position specified in the second argument, with length specified in the third argument. For
example, the following returns "234":
substring("12345", 2, 3)

If you do not specify the third argument, the substring() function returns the substring
starting at the position specified in the second argument and continuing to the end of the
string. For example, the following call returns "2345":
substring("12345", 2)

More precisely, each character in the string is considered to have a numeric position. The
position of the first character is 1. The position of the second character is 2, and so on. The
returned substring contains those characters for which the position of the character is
greater than or equal to the rounded second argument and, if the third argument is
specified, less than the sum of the value of the second and third arguments. The
comparisons and addition used for the preceding follow the standard IEEE 754 rules. The

736

Stylus Studio User Guide

Handling Strings and Text

XPath processor rounds the second and third arguments as if by a call to the
function. For example:
substring("12345",
substring("12345",
substring("12345",
substring("12345",
substring("12345",
substring("12345",

round()

1.5, 2.6) returns "234"

0, 3) returns "12"
0 div 0, 3) returns ""
1, 0 div 0) returns ""
-42, 1 div 0) returns "12345"
-1 div 0, 1 div 0) returns ""

Manipulating Strings
After you obtain a string, you might want to manipulate it and use the result in the query.
This section describes functions that allow you to do this. It discusses the following
topics:

Concatenating Strings on page 737

Determining the Number of Characters in a String on page 737

Normalizing Strings on page 738

Replacing Characters in Strings with Characters You Specify on page 738

Converting Objects to Strings on page 739

Finding Strings That Start with a Particular String on page 740

Concatenating Strings
To concatenate two or more strings, call the concat() function. The format is
string concat(string, string, {string}...)

The concat() function returns the concatenation of its arguments.

Determining the Number of Characters in a String

To obtain the number of characters in a string, call the string-length() function. The
format is
number string-length(string?)

The string-length() function returns the number of characters in the string. If you omit
the argument, it defaults to the string value of the context node.

Stylus Studio User Guide

737

Writing XPath Expressions

Normalizing Strings
To strip leading and trailing white space from a string, call the normalize-space()
function. The format is
string normalize-space(string?)

The normalize-space() function removes leading and trailing white space. White space
consists of spaces, tabs, new lines, and returns.
If there are consecutive internal spaces, the normalize-space() function collapses the
internal spaces into one space. The normalize-space() function returns the string with the
extraneous white space removed. If you omit the argument, it defaults to the string value
of the context node.

Replacing Characters in Strings with Characters You Specify

To replace characters in a string with other characters, call the translate() function. The
format is
string translate(string, string, string)

The translate() function looks for characters in the first string that are also in the second
string. For each such character, the translate() function replaces the character in the first
string with a character from the third string. The replacement character is the character in
the third string that is in the same position as the character in the second string that
corresponds to the character being replaced. For example:
translate("bar", "abc", "ABC")

Execution of this function returns "BAr". Following is another example:

translate("---aaa---", "abc", "ABC")

Execution of this function returns "AAA". Sometimes there is a character in the second
argument string with no character at a corresponding position in the third argument string.
This happens when the second argument string is longer than the third argument string.
In this case, the XPath processor removes occurrences of that character.
If a character occurs more than once in the second argument string, the first occurrence
determines the replacement character. If the third argument string is longer than the
second argument string, the XPath processor ignores the excess characters.

738

Stylus Studio User Guide

Handling Strings and Text

Converting Objects to Strings

In some situations, you might want to force a string comparison. The XPath processor
performs a string comparison only when the operands are neither Boolean nor numeric
values. If an operand is numeric or Boolean, call the string() function on it to convert it
to a string. The format of the string() function is
string string(object?)

The string() function can convert any object to a string. If you omit the argument, it
defaults to a node set with the context node as the only member. The string value of an
element node is the concatenation of the string values of all text node descendants of the
element node in document order.
Node Sets

When the string() function converts a node set to a string, it returns the string value of
the node in the node set that is first in document order. If the node set is empty, the
string() function returns an empty string.

Numbers

The

Boolean
Values

string() function

converts numbers to strings as follows:

NaN (not a number) becomes "NaN"
Positive zero becomes "0"
Negative zero becomes "0"
Positive infinity becomes "Infinity"
Negative infinity becomes "-Infinity"
An integer becomes a sequence of digits with no leading zeros, for example, "1234".
A negative integer is preceded by a minus sign, for example, "1234".
A noninteger number becomes a sequence of digits with at least one digit before a
decimal point and at least one digit after a decimal point, for example, "12.34". A
negative noninteger number is preceded by a minus sign, for example, "12.34".
Leading zeros are not allowed unless there is only one to satisfy the requirement of a
zero before the decimal point. Beyond the one required digit after the decimal point,
there must be as many, but only as many, more digits as are needed to uniquely
distinguish the number from all other IEEE 754 numeric values.

The string() function converts the Boolean false value to the string "false", and the
Boolean true value to the string "true".

Stylus Studio User Guide

739

Writing XPath Expressions

Finding Strings That Start with a Particular String

To determine if a string starts with a particular string, specify the starts-with() function.
The format is
boolean starts-with(string, string)

This function returns true if the first argument string starts with the second argument
string, and otherwise returns false.

Obtaining the Text Contained in a Node

You can use the string() function to obtain the text in a node. The string value of an
element node is the concatenation of the string values of all text node descendants of the
element node in document order. Use one of the following formats:
string string(pathExpression)
pathExpression

Replace pathExpression with the path of the node or nodes that contain the text you want.
This can be a rooted path or a relative path. It need not be a single node. If you do not
explicitly specify the string() function, you must specify pathExpression in a context
where the XPath processor must treat it as a string, for example:
/bookstore/book[title = "Trenton Revisited"]

The XPath processor obtains the text contained in each title element and compares it
with "Trenton Revisited". The XPath processor returns books with the title Trenton
Revisited.
For additional information about the string() function, see Converting Objects to
Strings on page 739.

740

Stylus Studio User Guide

Specifying Boolean Expressions and Functions

This section provides information on how to specify Boolean expressions and functions
in queries. It includes the following topics:

Using Boolean Expressions on page 741

Calling Boolean Functions on page 742

Using Boolean Expressions

You can specify Boolean expressions in the subqueries in filters. You specify the Boolean
AND, OR, and NOT operators like this:

and

not

You can use parentheses to group collection specifications and operators for clarity or
where the normal precedence is inadequate to express an operation.

Case Sensitivity
Operators are case sensitive. Spaces are not significant. You can omit them or include
them for clarity.

Examples
The following query returns all authors who have at least one degree and one award:
author[degree and award]

The next query finds all authors who have at least one degree or award and at least one
publication:
author[(degree or award) and publication]

Following is a query that finds all authors who have at least one degree and no
publications:
author[degree and not(publication)]

Stylus Studio User Guide

741

Writing XPath Expressions

Calling Boolean Functions

This section describes the Boolean functions that you can call in a query. The operations
you can perform are

Converting an Object to Boolean on page 742

Obtaining Boolean Values on page 743

Determining the Context Node Language on page 743

Converting an Object to Boolean

In some situations, you might want to force a Boolean comparison. The XPath processor
performs a Boolean comparison if either operand is a Boolean value. Consequently, if
neither operand is a Boolean value, call the boolean() function on one operand to convert
it to a Boolean value. The XPath processor automatically converts the other operand to a
Boolean value. The format of the boolean() function is
boolean boolean(object)

The boolean() function converts its argument to Boolean as follows:

A number is false if and only if it is one of the following:

Positive zero

Negative zero

NaN (not a number)

A node set is false if and only if it is empty.

A string is false if and only if its length is 0.

The boolean() function is useful in comparisons. For example, the following query
returns b elements that either contain both c and d elements as children or contain neither
c nor d elements as children:
/a/b[boolean(c) = d]

This query is equivalent to the following query:

/a/b [(c and d) or (not(c) and not(d))]

742

Stylus Studio User Guide

Specifying Boolean Expressions and Functions

Obtaining Boolean Values

To obtain the opposite Boolean value, call the not() function. The format is
boolean not(boolean)

The not() function returns true if its argument is false, and returns false if its argument
is true. For example, the following query finds all authors who have publications but no
degrees or awards:
author[not(degree or award) and publication]

To obtain the value

true,

call the

true() function.

The format is

boolean true()

The true() function returns true.

To obtain the value

false,

call the

false()

function. The format is

boolean false()

The false() function returns false.

Determining the Context Node Language

To determine whether the language of the context node is the language you expect it to
be, call the lang() function. The format is
boolean lang(string)

The lang() function returns true or false depending on whether the language of the
context node as specified by the xml:lang attribute is the same as, or is a sublanguage of,
the language specified by the argument string. The language of the context node is
determined by the value of the xml:lang attribute on the context node or, if the context
node has no xml:lang attribute, by the value of the xml:lang attribute on the nearest
ancestor of the context node that has an xml:lang attribute.
If there is no such attribute, then lang() returns false. If there is such an attribute, lang()
returns true in the following situations:

The attribute value is equal to the argument string.

The attribute value has a suffix starting with a dash (-) such that the attribute value is
equal to the argument string if you ignore the suffix.
Stylus Studio User Guide

743

Writing XPath Expressions

In both situations, case is ignored. For example:

lang("en")

This returns true if the context node is any of these elements:

Specifying Number Operations and Functions

This section includes the following topics:

Performing Arithmetic Operations

Calling Number Functions

Performing Arithmetic Operations

In queries, a number represents a floating-point number. A number can have any doubleprecision 64-bit format IEEE 754 value. This includes

A special not-a-number (NaN) value

Positive and negative infinity

Positive and negative zero

The numeric operators convert their operands to numbers as if by calling the number()
function. See Converting an Object to a Number on page 745.
You can use the following arithmetic operators in queries:

+ performs addition

- performs subtraction
XML allows hyphens (-) in names. Consequently, the subtraction operator ()
typically needs to be preceded by white space. For example, foo-bar evaluates to a
node set that contains the child elements named foo-bar. However, foo - bar evaluates
to the difference between the result of converting the string value of the first foo child
element to a number and the result of converting the string value of the first bar child
to a number.

* performs multiplication

mod returns the remainder from a truncating division. For example:

744

Stylus Studio User Guide

Specifying Number Operations and Functions

5 mod 2 returns 1.

5 mod -2 returns 1.

-5 mod 2 returns -1.

-5 mod -2 returns -1.

The mod operator is the same as the % operator in Java and ECMAScript. But it does
not perform the same operation as the IEEE remainder operation, which returns the
remainder from a rounding division.
div performs floating-point division according to IEEE 754.

Calling Number Functions

This section describes the number functions that you can call in a query. The operations
you can perform are

Converting an Object to a Number on page 745

Obtaining the Sum of the Values in a Node Set on page 746

Obtaining the Largest, Smallest, or Closest Number on page 746

Converting an Object to a Number

In some situations, you might want to force a numeric comparison. The XPath processor
performs a numeric comparison if either operand is numeric and neither is Boolean. (If
one operand is Boolean, the XPath processor converts the other to Boolean and performs
a Boolean comparison.) However, if neither operand is a numeric or Boolean value, you
can call the number() function on one operand to convert it to a numeric value. The XPath
processor automatically converts the other operand to a numeric value.
To perform a numeric comparison, you must call the number() function to convert a
Boolean operand, if there is one, to a numeric value.
The format of the number() function is
number number(object?)

Stylus Studio User Guide

745

Writing XPath Expressions

If you omit the argument, the value of the argument defaults to a node set with the context
node as its only member. Table 95 shows how the number() function converts its argument
to a number:
Table 95. number() Function Arguments and Converted Values
Argument

Converted Value

String that consists of optional

white space followed by an
optional minus sign followed by a
number followed by white space

IEEE 754 number that is nearest to the mathematical value

represented by the string.

Any other string

NaN (not a number)

Boolean true

Boolean false

Node set

First the XPath processor converts the node set to a

concatenated string as if by a call to the string() function
for the first node in the node set, in document order. The
XPath processor then converts this string the same way as
it would a string argument.

Obtaining the Sum of the Values in a Node Set

To obtain the sum of the values of the nodes in a set, call the sum() function. The format is
number sum(node-set)

For each node in the argument node-set, the XPath processor converts the string value of
the node to a number. The sum() function returns the sum of these numbers.

Obtaining the Largest, Smallest, or Closest Number

To obtain the largest integer that is not greater than a particular number, call the
function. The format is

floor()

number floor(number)

The floor() function returns the largest (closest to positive infinity) number that is not
greater than the argument and that is an integer. For example:

746

Stylus Studio User Guide

Comparing Values

floor(5.3) returns 5

floor(-5.3) returns -6

To obtain the smallest integer that is not less than a particular number, call the
function. The format is

ceiling()

number ceiling(number)

The ceiling() function returns the smallest (closest to negative infinity) number that is
not less than the argument and that is an integer. For example:

ceiling(5.3) returns 6

ceiling(-5.3) returns -5
To obtain the closest integer to a particular number, call the
is

round() function. The format

number round(number)

The round() function returns the number that is closest to the argument and that is an
integer. If there are two such numbers, the function returns the one that is closest to
positive infinity. For example:

round(5.3) returns 5

round(5.6) returns 6

round(5.5) returns 6

Comparing Values
In queries, you can specify operators that compare values. Comparison operations return
Boolean values. If you want to obtain the nodes for which a comparison tests true, enclose
the comparison in a filter.
This section discusses the following topics:

About Comparison Operators on page 748

How the XPath Processor Evaluates Comparisons on page 748

Comparing Node Sets on page 749

Comparing Single Values With = and != on page 750

Comparing Single Values With <=, <, >, and >= on page 751

Priority of Object Types in Comparisons on page 751

Stylus Studio User Guide

747

Writing XPath Expressions

Examples of Comparisons on page 752

Operating on Boolean Values on page 752

About Comparison Operators

The comparison operators you can specify are listed in Table 96:
Table 96. Comparison Operator Descriptions
Operator

Description

Equality

Inequality

Less than

Less than or equal

Greater than

Greater than or equal

You can specify single or double quotation marks (' or ") as string delimiters in
expressions. This makes it easier to construct and pass queries from within scripting
languages.

How the XPath Processor Evaluates Comparisons

A query can compare values of elements. For example:
last-name [. = "foo"]

The XPath processor compares the value of each last-name element in the current context
with the value "foo". The result of each comparison is a Boolean value. The XPath
processor returns the last-name elements for which the comparison yields true.
As mentioned before in Filtering Results of Queries on page 713, the XPath processor
evaluates filters with respect to a context. For example, the expression book[author]
means for every book element that is found, determine whether it has an author child
element. Likewise, book[author = "Bob"] means for every book element that is found,
determine whether it contains an author child element whose value is "Bob".

748

Stylus Studio User Guide

Comparing Values

Comparisons are case sensitive. For example, "Bob" and "bob" are not considered to be
equal.
Remember that comparisons return Boolean values. For example:
/bookstore/book/author/last-name="Bob"

You might think that this query returns authors whose last name is "Bob". But this is not
the case. This query returns a single Boolean value. It tests each last-name element to
determine if its value is "Bob". As soon as the XPath processor finds a last-name element
that tests true, it returns true. If no nodes test true, this query returns false.
To obtain author elements whose last name is "Bob", enclose the comparison in a filter as
follows:
/bookstore/book/author[last-name="Bob"]

Comparing Node Sets

You can compare

Two node sets

A node set and a number

A node set and a string

A node set and a Boolean value

Two Node Sets

Suppose the objects you want to compare are both node sets. The result is true only in the
following case. There is a node in the first node set and a node in the second node set such
that the result of performing a comparison on the values of the two nodes is true. For
string values, the comparison can be = or !=. For numeric values, the comparison can also
be <, >, <=, or >=.

A Node Set and a Number

Now suppose one object to be compared is a node set and the other is a number. The XPath
processor searches for a node in the node set that yields a true result when its number
value is compared with the number that is not in the node set. If necessary, the XPath
processor uses the number() function to convert values to numeric values. If and only if
the XPath processor finds such a node, the result is true.

Stylus Studio User Guide

749

Writing XPath Expressions

A Node Set and a String

Sometimes you want to compare a node set with a string. The XPath processor searches
for a node in the node set that yields a true result when its string value is compared with
the string that is not in the node set. If necessary, the XPath processor uses the string()
function to convert values to string values. If and only if the XPath processor finds such a
node, the result is true.

A Node Set and a Boolean Value

Finally, suppose you want to compare a node set with a Boolean value. This tests true if
and only if the result of performing the comparison on the Boolean value and on the result
of converting the node set to a Boolean value using the boolean() function is true.

Comparing Single Values With = and !=

When neither object to be compared is a node set and the operator is = or !=, the XPath
processor compares the objects by converting them to a common type and then comparing
them. The XPath processor converts the objects to a common type as follows:

If at least one object to be compared is Boolean, the XPath processor converts the
other object to Boolean as if by applying the boolean() function.

If at least one object to be compared is a number, and neither is Boolean, the XPath
processor converts the nonnumber object to a number as if by applying the number()
function.
If the objects to be compared are neither Boolean nor numeric, the XPath processor
compares the string values of the objects as if by applying the string() function to each
object.
The = comparison returns true if and only if the objects are equal. The != comparison
returns true if and only if the objects are not equal. Numbers are compared for equality
according to IEEE 754. Two Boolean values are equal if either both are true or both are
false. Two strings are equal if and only if they both consist of the same sequence of
Universal Character Set (UCS) characters.
Note Use single or double quotes to specify string values being used with a comparison

operator.

750

Stylus Studio User Guide

Comparing Values

Comparing Single Values With <=, <, >, and >=

When neither object to be compared is a node set and the operator is <=, <, >=, or >, the
XPath processor performs the comparison by converting both objects to numbers and
comparing the numbers according to IEEE 754.
Table 97. Comparison Operator Descriptions
Comparison

True If and Only If

The first number is less than the second number.

The first number is less than or equal to the second number.

The first number is greater than the second number.

The first number is greater than or equal to the second number.

The XPath processor always evaluates these comparisons in terms of numbers. You
cannot use the less than and greater than operators to order strings. This is especially
important to remember when you compare a number with a string. For example, suppose
you want to evaluate the expression
a < "foo"

The return value is always false. This is because number("foo") returns NaN, and the
resulting comparison, shown below, is always false.
a < NaN

Priority of Object Types in Comparisons

When the XPath processor performs a comparison, if either operand is a Boolean value,
the XPath processor automatically converts the other operand to a Boolean value, if
necessary, and makes a Boolean comparison.
If either operand is numeric and neither operand is Boolean, the XPath processor
automatically converts the other operand to a numeric value, if necessary, and performs a
numeric comparison.
If neither operand is numeric or Boolean, the XPath processor performs a string
comparison.

Stylus Studio User Guide

751

Writing XPath Expressions

Examples of Comparisons
The following query finds all authors whose last name is Bob:
author[last-name = "Bob"]

The next query finds authors whose degrees are not from Harvard:
author/degree[@from != "Harvard"]

The following query returns prices that are greater than 20 dollars. This assumes that the
current context contains one or more price elements.
price [. > 20]

Operating on Boolean Values

You can use the = or != operator to compare Boolean values. If you try to use any other
operator to compare Boolean values, you receive an error.

Finding a Particular Node

To find a specific node within a set of nodes, enclose an integer within brackets ( [ ] ). The
integer indicates the position of the node relative to its parent. This section discusses the
following topics:

About Node Positions on page 753

Determining the Position Number of a Node on page 753

Positions in Relation to Parent Nodes on page 754

Finding Nodes Relative to the Last Node in a Set on page 755

Finding Multiple Nodes on page 755

Examples of Specifying Positions on page 756

Finding the First Node That Meets a Condition on page 756

Finding an Element with a Particular ID on page 757

Obtaining Particular Types of Nodes By Using Node Tests on page 758

See also Obtaining the Current Node for the Current XSLT Template on page 766.

752

Stylus Studio User Guide

Finding a Particular Node

About Node Positions

The node positions for a node set start with 1. Evaluation of the position number is always
based on document order. For example, the following query returns the first author
element in the current context:
author[1]

The next query finds the author elements (in the current context) that contain a first-name
element. The query returns the third such author element.
(author[first-name])[position()=3]

When you specify an integer in brackets, it is equivalent to calling the position()

function. For example, the following queries both return the third y child element of each
x child element in the current context:
x/y[3]
x/y[position()=3]

Tip: If you do not know the position of the node you want, a call to the position()
function might help you. See Determining the Position Number of a Node on page 753.
The return value of the position() function depends on the specified axis. For example,
suppose the axis is one of the reverse axes, such as preceding, ancestor, or precedingsibling. The position() function returns the nth one in reverse document order that falls
in the specified axis.

Determining the Position Number of a Node

The position() function returns an integer that indicates the position of the node within
the parent. Positions start with 1; a node with a position of 1 is always the first node in the
collection.
For example, the following query returns the first three degree elements in the document:
(//degree)[position() < 4]

The next query finds the first two book children in the current context:
book[position() <= 2]

Stylus Studio User Guide

753

Writing XPath Expressions

The XPath processor executes the position() function with respect to the parent node.
Consider the following data:
<x>
<y/>
<y/>
</x>
<x>
<y/>
<y/>
</x>

The following expression returns the first y element contained in each x element:
x/y[position() = 1]

For more information, see also Finding an Element with a Particular ID on page 757.

Positions in Relation to Parent Nodes

Positions are relative to the parent. Consider the following data, which has line numbers
on the left for explanation only.
1
2
3
4
5
6
7
8
9
10
11
12

The following query returns the first y element contained in each x element. It returns the
elements on lines 6 and 10. The XPath processor finds all x elements. For each x element,
the XPath processor then returns the first y element it finds.
x/y[1]

The next query returns the first y element that is contained in an x element that is in the
context node set. It returns the element on line 6. The XPath processor finds all y elements
inside x elements. The XPath processor then returns the first element in that set.
(x/y)[1]

754

Stylus Studio User Guide

Finding a Particular Node

The next query returns the empty set. The XPath processor finds the first x element. It then
searches that first x element for the first y. Because the first x element does not contain a
y element, this query returns the empty set.
x[1]/y[1]

Finding Nodes Relative to the Last Node in a Set

To obtain nodes relative to the last node in the set, use the position() and last()
functions with arithmetic. For example, the following queries both obtain the last author
element in the current context:
author [position() = last()]
author [last()]

The following queries both return the next-to-last author element:

author [position() = last() 1]
author [last() - 1]

For information about position(), see Determining the Position Number of a Node on
page 753. For information about last(), see Determining the Context Size on page 764.

Finding Multiple Nodes

To obtain several nodes in one operation, use the and or the or operator with the
position() and last() functions. For example, the following query returns the first and
the last author nodes in the current context:
author [(position() = 1) or (position() = last())]

You can also specify a range of nodes. For example, the next query returns the second,
third, and fourth author elements:
author [(position() >= 2) and ( position() <= 4)]

To obtain a range of nodes, m to n, relative to the last node, use the following format:
(m <= position()) and (position() <= n)

Stylus Studio User Guide

755

Writing XPath Expressions

For example, the following query obtains the last five nodes in the current context:
author [(last() 4) <= position()) and (position() <= last())]

Examples of Specifying Positions

The following query finds the first and fourth author elements:
author [(position() = 4) or (position() = 1)]

The next query finds the first, the third through the fifth, and the last author elements:
author [(position() = 1) or
(position() >= 3 and position() <= 5) or
(position() = last())]

The XPath processor removes duplicate values. For the previous query, if there are only
five elements in the collection, the query returns only one copy of the fifth element.
The next example finds all author elements in which the first degree is a Ph.D.:
author[degree[1] = "Ph.D."]

Finding the First Node That Meets a Condition

Suppose you want to obtain from a collection the first node that meets a certain condition.
For example, you want the first book whose authors last name is Bob. You can specify
the following query:
(//book[author/last-name="Bob"])[position()=1]

When the XPath processor evaluates this expression, it creates a collection of book
elements where the authors last name is Bob. The XPath processor then returns the first
node in this collection.
The following two expressions appear to also return the first book whose authors last
name is Bob, but they do not. Instead, these queries both return a book whose authors last
name is Bob only if that book is the first book in the document.
//book[author/first-name="Bob"][position()=1]
//book[author/first-name="Bob" and position() = 1]

756

Stylus Studio User Guide

Finding a Particular Node

Finding an Element with a Particular ID

To obtain the element that has a particular identifier (ID), the DTD must specify an
attribute for that element. The type of this attribute must be ID. The name of the attribute
is not significant, though it is typically id. If there is such an attribute, you can call the
id() function to obtain the element with a particular ID. The format is
node-set

id(object)

The id() function evaluates to a set. It ignores the context node set except to evaluate the
functions argument. The result set contains an element node that has an attribute of type
ID whose value is identical to the string the object argument evaluates to. The element
node can appear anywhere in the document that is being queried.
For example:
id("special")

This query searches for an element that has an attribute whose

Type is ID

Value is special
Details about working with IDs are in the following topics:

The id() Functions Argument on page 757

Unique IDs on page 757

The id() Functions Argument

When the id() functions argument is of type node-set, the result is the union of the
results of applying id() to the string value of each of the nodes in the argument node set.
When the argument of id() is any other type, the XPath processor converts the argument
to a string as if by a call to the string() function. The XPath processor splits the string
into a white-space-separated list of tokens. The result is a node set that contains the
elements in the same document as the context node that have a unique ID equal to any of
the tokens in the list.

Unique IDs
An element node can have a unique ID. This is the value of the attribute that is declared
in the DTD as type ID. No two elements in a document can have the same unique ID. If

Stylus Studio User Guide

757

Writing XPath Expressions

an XML processor reports two elements in a document as having the same unique ID
(which is possible only if the document is invalid), the second element is treated as not
having a unique ID.
If a document does not have a DTD, the id() function always returns an empty node list.

Obtaining Particular Types of Nodes By Using Node Tests

The node tests allow you to obtain nodes according to their type. Node test is an XPath
term. Although a node test looks like a function, it is not a function.
You can use node tests with filters and position specifiers. They resolve to the set of
children of the context node that meets the restrictions you specify.
Node tests for XPath 2.0 add to the set of node tests supported for XPath 1.0. Node tests
common to both XPath 1.0 and XPath 2.0 are shown in Table 98. Node tests unique to
XPath 2.0 are shown in Table 98.
Table 98. Node Test Return Values Common to XPath 1.0 and XPath 2.0
Node Test

Node Type Returned

comment()

Comment nodes.

node()

All nonattribute nodes.

processinginstruction("name")

Processing instruction nodes. The processing-instruction()

node test selects all processing instructions. When this node test
specifies a literal argument, it selects any processing instruction that
has a name equal to the value of the argument. If there is no
argument, this node test selects all processing instructions.

text()

Text nodes and CDATA nodes.

Table 99. Node Test Return Values Unique to XPath 2.0

758

Node Test

Node Type Returned

attribute()

Matches any attribute node.

document-node()

Matches any document node.

element()

Matches any element node.

item()

Matches any single item.

Stylus Studio User Guide

Finding a Particular Node

For each p element in the current context, the following query returns its second text child
node:
p/text()[2]

Following is a query that finds the third comment child in each foo element anywhere in
the document:
//foo/comment()[3]

About the Document Object

In the Document Object Model (DOM), a document contains comments, processing
instructions, and declarations, as well as the document element. As in XPath, the root
node is the root of the DOM tree, and the root node is not the same as the document
element. This allows comments, declarations, and processing instructions at the document
entity level.
For example, the following query finds all comments at the document entity level. In other
words, it finds all comments that are immediate children of the root node.
/comment()

This query returns the comment at the beginning of the bookstore.xml file:
"This file represents a fragment of a book store inventory database."

Getting Nodes of a Particular Type

A query like the following returns all the comments in a document:
//comment()

The following query returns the third comment in the document.

(//comment()) [3]

Stylus Studio User Guide

759

Writing XPath Expressions

Obtaining a Union
Specify the | operator to combine collection sets. For example, the following query
returns all last-name elements and all first-name elements in the current context:
first-name | last-name

The result set can contain zero or more of each element that the | operator applies to. For
example, using the previous query, it is possible for the query to contain only first-name
elements if no last-name elements are found. The following query finds all book elements
and magazine elements in the bookstore element:
/bookstore/book | /bookstore/magazine

The next query finds all books and all authors in the current context:
book | book/author

A union can appear only as the first step in a location path expression. Consequently, the
following is incorrect because there is a union specification that is not in the first step of
a location path expression.
(book | magazine)/author/(first-name | last-name | degree)

The following query finds all books for which the authors first name is Bob and all
magazines with prices less than 10 dollars:
/bookstore/book[author/first-name = "Bob"] | magazine[price < 10]

760

Stylus Studio User Guide

Obtaining Information About a Node or a Node Set

In a query, you can perform the following operations to obtain information about a node:

Obtaining the Name of a Node on page 761

Obtaining Namespace Information on page 761

Obtaining the URI for an Unparsed Entity on page 764

Determining the Number of Nodes in a Collection on page 764

Determining the Context Size on page 764

Obtaining the Name of a Node

The name() function returns a string that contains the tag name of the node, including the
namespace prefix, if any.
The following query returns the name of the third element in bookstore, which is
"magazine".
name(/bookstore/*[3])

Wildcards
An asterisk ( * ) specifies a wildcard name for element names. If there are comments
before the third element in the preceding example, this query does not include them in the
count. See Filtering Results of Queries on page 713.
Note Remember, an asterisk that is not preceded by an at sign (@) never returns attributes. The

XPath processor does not include attributes in node counts. See Attributes and
Wildcards on page 713.

Obtaining Namespace Information

You can call functions to obtain namespace information. This topic discusses

Obtaining the Namespace URI on page 762

Obtaining the Local Name on page 762

Obtaining the Expanded Name on page 762

In addition to a discussion of the functions you call, this section covers the following:

Specifying Wildcards with Namespaces on page 763

Examples of Namespaces in Queries on page 763

Stylus Studio User Guide

761

Writing XPath Expressions

Obtaining the Namespace URI

To obtain the URI for a namespace, call the

namespace-uri() function.

The format is

string namespace-uri(node-set?)

The namespace-uri() function returns the namespace URI of the expanded name of the
node in the node-set argument that is first in document order. If the node-set argument is
empty, the first node has no expanded name, or the namespace URI of the expanded name
is null, the XPath processor returns an empty string. If you omit the argument, it defaults
to a node set with the context node as its only member.
Call the

namespace-uri() function on element or attribute nodes. For example, the query

/bookstore/my:book/namespace-uri()

returns the string

"http://www.placeholder-name-here.com/schema/"

For any other type of node, the XPath processor always returns an empty string.

Obtaining the Local Name

To obtain the local portion of a node name, excluding the prefix, call the local-name()
function. The format is
string local-name(node-set?)

The local-name() function returns the local part of the expanded name of the node in the
that is first in document order. If the node-set argument is empty or
the first node has no expanded name, the function returns an empty string. If you omit the
argument, it defaults to a node set with the context node as its only member. For example,
the following query returns my:book nodes:

node-set argument

/bookstore/my:*[local-name()="book"]

Obtaining the Expanded Name

To obtain the expanded name of a node, call the name() function. The expanded name is
the namespace prefix, if any, plus the local name. The format is
string name(node-set?)

762

Stylus Studio User Guide

Obtaining Information About a Node or a Node Set

The name() function returns a string that represents the expanded name of the node in the
node-set argument that is first in document order. The returned string represents the
expanded name with respect to the namespace declarations in effect on the node whose
expanded name is being represented.
Typically, this is the name in the XML source. This need not be the case if there are
namespace declarations in effect on the node that associate multiple prefixes with the
same namespace.
If the node-set argument is empty or the first node has no expanded name, the XPath
processor returns an empty string. If you omit the argument, it defaults to a node set with
the context node as its only member.
Except for element and attribute nodes, the string that the name() function returns is the
same as the string the local-name() function returns.

Specifying Wildcards with Namespaces

Element and attribute names that include colons (:) can include wildcards; that is,
asterisks (*). For example, queries can include *:*, *:a, or a:*.

Examples of Namespaces in Queries

The following example finds all book elements in the current context. This query does not
return any book elements that are not in the default namespace. For example, it does not
return my:book elements.
book

The next query finds all book elements with the prefix my. This query does not return
unqualified book elements; that is, book elements in the default namespace.
my:book

The following query finds all book elements with a my prefix that have an author
subelement:
my:book[author]

The following query finds all book elements with a my prefix that have an author
subelement with a my prefix:
my:book[my:author]

Stylus Studio User Guide

763

Writing XPath Expressions

The next example returns the style attribute with a my prefix for book elements in the
current context:
book/@my:style

Obtaining the URI for an Unparsed Entity

To obtain the URI for an unparsed entity, call the unparsed-entity-uri() function. The
format is
string unparsed-entity-uri(string)

This function returns the URI of the unparsed entity with the specified name that is in the
same document as the context node. If there is no such entity, this function returns an
empty string.

Determining the Number of Nodes in a Collection

To obtain the number of nodes in a node set, call the count() function. The format is
number count(node-set)

The count() function returns the number of nodes in the specified set. For example, the
following query finds all authors who have more than ten publications:
//author[count(publications) > 10]

To obtain the number of nodes in the current context, call the

in the next section.

last()

function, described

Determining the Context Size

To obtain the number of nodes in the current context, call the
is

last()

function. The format

number last()

The last() function returns a number equal to the context size of the expression
evaluation context. Essentially, the last() function returns the position number of the last
node in document order for the current context. For example, the following query returns

764

Stylus Studio User Guide

Using XPath Expressions in Stylesheets

all books if there are three or more of them. There are three book elements in the current
context. Consequently, this query returns three book elements.
/bookstore/book[last() >= 3]

Using XPath Expressions in Stylesheets

This section provides information about using XPath expressions in stylesheets. It
includes the following topics:

Using Variables on page 765

Obtaining System Properties on page 765

Determining If Functions Are Available on page 766

Obtaining the Current Node for the Current XSLT Template on page 766

Finding an Element with a Particular Key on page 767

Generating Temporary IDs for Nodes on page 769

Using Variables
In a query that you specify in a stylesheet, you can refer to variables that you defined
elsewhere in the stylesheet. Use the following format to refer to a variable:
$variable_name

In a stylesheet, you can define variables with either of the following instructions:

xsl:param on page 493

xsl:variable on page 503

Obtaining System Properties

In a query in a stylesheet, there are three system properties for which you can obtain
information:

xsl:version returns 1.0 as the version of XSLT that the Stylus Studio XSLT processor
implements.

xsl:vendor returns DataDirect as the vendor of Stylus Studios XSLT processor.

xsl:vendor-url returns http://www.stylusstudio.com as the vendor URL.

Stylus Studio User Guide

765

Writing XPath Expressions

To obtain this information, call the system-property() function. The format is

object system-property(string)

The string you specify must identify one of the three properties and must be a qualified
name. This function returns an object that represents the value of the system property you
specify.

Determining If Functions Are Available

In a query in a stylesheet, to determine whether the XPath processor supports a particular
function, call the function-available() function. The format is
boolean function-available(string)

Specify a string that identifies the name of the function. The XPath processor returns true
if it implements that function.

Obtaining the Current Node for the Current XSLT Template

In a stylesheet, the current node is the node for which the XSLT processor instantiates a
template. When the XPath processor evaluates an expression during stylesheet
processing, the initial context node for the expression is set to the current node for the
stylesheet instruction that contains the expression. Because the context node can change
during evaluation of subexpressions, it is useful to be able to retrieve, from within a
subexpression, the original context node for which the expression is being evaluated. You
can use the current() function for this purpose. The format is
node-set current()

The current() function returns a node set that contains only the current node for the
current template. The current() function is specified in the W3C XSLT
Recommendation.

766

Stylus Studio User Guide

Using XPath Expressions in Stylesheets

For example, the following stylesheet causes the XSLT processor to pass the bookstore
node to the outer xsl:for-each instruction:
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/XSL/Transform" version="1.0" >
<xsl:template match="/">
<xsl:for-each select="bookstore">
<xsl:for-each select=
"book[@style=current()/@specialty]">
...
</xsl:for-each>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>

The bookstore node is the current node within the outer xsl:for-each instruction. Within
the inner xsl:for-each instruction, a book node is the current node.
The current() function in the inner expression returns the bookstore element because the
bookstore element is the current node for the inner xsl:for-each instruction. The result
of the query contains book elements if the value of their style attribute is the same as the
value of the specialty attribute of the bookstore element (novel).
Suppose the select attribute in the inner
instead of the current() function:

xsl:for-each instruction

specified the dot (.)

<xsl:for-each select="book[@style=./@specialty]">

In a query, the dot specifies the context node. This query would return a book if the value
of its style attribute was the same as the value of its specialty attribute.
You can nest xsl:for-each instructions more than one level deep. In any given nested
xsl:for-each instruction, the current() function returns the current node for the closest
enclosing xsl:for-each instruction.

Finding an Element with a Particular Key

The key() function, defined in the XSLT Recommendation, obtains the node whose key
value matches the specified key. The format is
node-set key(string, object)

Stylus Studio User Guide

767

Writing XPath Expressions

The first argument specifies the name of the key. The value of this argument must be a
qualified name. The second argument specifies the node or nodes to examine. When the
second argument is a node set, the result is the union of the results of applying the key()
function to the string value of each of the nodes in the set. When the second argument is
any other type, the XPath processor converts the argument to a string, as if by a call to the
string() function. The key() function returns a node set that contains the nodes in the
same document as the context node that have a value for the named key that is equal to
this string.
For example, the videos.xml document, which is in the examples directory of the Stylus
Studio installation directory, contains the following elements:
<result>
<actors>
<actor id="00000003">Jones, Tommy Lee</actor>
...
</actors>
<videos>
<video id="id1235AA0">
<title>The Fugitive</title>
...
<actorRef>00000003</actorRef>
<actorRef>00000006</actorRef>
...
</video>
...
</videos>
</result>

When you display information about a video in a Web browser, you want to display the
names of the actors. Because the actors are referenced only by an ID number, you create
a key table in your stylesheet:
<xsl:key
name="actors"
match="/result/actors/actor"
use="@id"/>

This indexes all actors by their ID. To process a video, your stylesheet specifies the
following:
<xsl:for-each select="actorRef">
<xsl:value-of select="key('actors', .)"/>
</xsl:for-each>

768

Stylus Studio User Guide

Accessing Other Documents During Query Execution

This instructs the XPath processor to look up the actor element in the actors key table by
using the actorRef element as a key.

Generating Temporary IDs for Nodes

The generate-id() function, defined in the XSLT recommendation, generates temporary
IDs for nodes.
Caution The ID generated by the generate-id() function is not an object ID. The value generated

by the generate-id() function is guaranteed to be the same only during an XSL

transformation. If the source document changes, the value for this ID can change.

Format
The format for the generate-id() function is as follows:
string generate-id(node-set?)

The generate-id() function returns a string that uniquely identifies the node in node-set
that is first in document order. This string starts with xln and ends with eight hexadecimal
digits. Syntactically, the string is an XML name.
If the node-set argument is empty, the generate-id() function returns an empty string. If
you omit the node-set argument, the generate-id() function generates a temporary ID
for the context node.

Accessing Other Documents During Query Execution

During execution of a query, you might want to access data in another document. To do
this, call the document() function.
This section discusses the following topics:

Format of the document() Function on page 770

When the First Argument is a Node Set on page 770

Specification of Second Argument on page 770

Example of Calling the document() Function on page 771

Stylus Studio User Guide

769

Writing XPath Expressions

Format of the document() Function

To query multiple documents with a single query, call the document() function in a query.
During execution of a query on a particular document, this function allows you to access
another XML document.
The format for the document() function is
node-set document(object, node-set?)

The XPath processor examines the first argument. If it is a single value (that is, it is not a
node set) the XPath processor converts it to a string, if it is not already a string. Separate
directory names and the file name with a forward slash (/). See the following format:
This string must be an absolute path. The XPath processor retrieves the specified
document. The new context node is the root node of this document. Suppose you invoke
the document() function and the requested document does not exist. If the invocation is in
a stylesheet, the XPath processor returns an empty node set. If the invocation is anywhere
else, the XPath processor returns an error message.

When the First Argument is a Node Set

It is possible for the first argument of the document() function to be a node set. In this case,
the result is as if you had called the document() function on each node in this node set.
That is, the first argument of the document() function is each node in the node set in turn.
The second argument, if there is one, is the same for each iteration of the document()
function. This allows you to obtain the contents of multiple documents.

Specification of Second Argument

If you specify a second argument, it must be a node set. The XPath processor examines
the first node (in the context of document order) in the node set to determine the document
that this node belongs to. The XPath processor retrieves the name of the directory that
contains this document and appends the relative path from the first argument to the name
of the directory. This creates an absolute path, and the XPath processor retrieves the
specified document.
If there is no second argument, the query must be an expression in an XSLT stylesheet.
The XPath processor appends the relative path to the name of the directory that contains
the XSLT stylesheet. This allows the query to examine the stylesheet itself.

770

Stylus Studio User Guide

XPath Quick Reference

Example of Calling the document() Function

Suppose you have the following XML document:
<?xml version="1.0" encoding="UTF-8"?>
<books>
<bookstore>bookstore1:bookstore1.xml</bookstore>
<bookstore>bookstore2:bookstore2.xml</bookstore>
<bookstore>bookstore3:bookstore3.xml</bookstore>
</books>

The following query returns the bookstore elements:

/books/bookstore

Now suppose you pass this query to the document() function as follows:
document(/books/bookstore)

This query returns the root nodes of bookstore1.xml, bookstore2.xml, and

bookstore3.xml.

XPath Quick Reference

This section includes the following topics:

XPath Functions Quick Reference

XPath Syntax Quick Reference

XPath Abbreviations Quick Reference

See also Precedence of Query Operators on page 719.

Stylus Studio User Guide

771

Writing XPath Expressions

XPath Functions Quick Reference

Table 100 lists the functions you can call in a query and provides short descriptions.
Table 100. XPath Function Quick Reference
Function

Source

page 743.
772

Stylus Studio User Guide

XPath Quick Reference

Table 100. XPath Function Quick Reference
Function

Source

a particular string. See Finding Strings That Start
with a Particular String on page 740.

string()

XPath

String that is the result of converting some object

to a string. See Converting Objects to Strings on
page 739.

Stylus Studio User Guide

XPath Quick Reference

Table 100. XPath Function Quick Reference
Function

Source

XPath Syntax Quick Reference

This topic provides a quick reference for XPath expression syntax.

Axes
XPath provides the following axes:

ancestor

ancestor-or-self

attribute

child

descendant

descendant-or-self

following

following-sibling

namespace

parent

preceding

preceding-sibling

self

Node Tests
XPath provides the following node tests:

* selects all nodes of the specified name. For the attribute axis, attributes are
selected. For the namespace axis, namespace nodes are selected. For all other axes,
element nodes are selected.

comment() selects all comment nodes.

element_name selects all element_name nodes.

node() selects all nodes.

processing-instruction(["some_literal"]) selects all processing instructions. If

some_literal is specified, processing-instruction() selects all processing
instructions with some_literal as their name.

text() selects all text nodes.

776

Stylus Studio User Guide

XPath Quick Reference

Filters
A filter specifies a constraint on a node set with respect to an axis to produce a new node
set.

Location Steps
A location step has the following format:
AxisSpecifier::NodeTest[Filter][Filter]...

XPath Expression
An XPath expression has one of the following formats:
LocationStep[/LocationStep]...
FunctionCall()[Filter]/LocationStep[/LocationStep]...
(Expression)[Filter]/LocationStep[/LocationStep]...

A function call or an XPath expression in parentheses can appear only at the very
beginning of an XPath expression. An expression in parentheses always returns a node
set. Any function that appears at the beginning of an XPath location step expression must
return a node set.

XPath Abbreviations Quick Reference

Table 101 defines the abbreviations you can use in XPath expressions:
Table 101. XPath Abbreviations Quick Reference
Abbreviation

Description

No axis is specified in a
location step.

The child axis is assumed. For example, the following two

XPath expressions both return the para children of chapter
children of the context node:
chapter/para
child::chapter/child::para

The attribute axis. For example, the following two XPath

expressions both return para children of the context node that
have type attributes with a value of warning:
para[@type="warning"]
child::para[attribute::type="warning"]

Stylus Studio User Guide

777

Writing XPath Expressions

Table 101. XPath Abbreviations Quick Reference
Abbreviation

Description

The descendant-or-self axis. For example, the following two

XPath expressions both return all para descendants of the context
node:
//para
/descendant-or-self::node()/child::para

However, it is important to note that the following two expressions

are not equivalent:
/descendant::para[1]
//para[1]

The first expression selects the first para element that is a

descendant of the context node. The second expression selects each
para descendant that is the first para child of its parent.
.

A single dot is the abbreviation for self::node(). This selects the

context node. For example, the following two XPath expressions
both return all para descendants of the context node:
.//para
self::node()/descendant-or-self::node()/child::para

A double dot is the abbreviation for parent::node(). This selects

the parent of the context node. For example, the following two
XPath expressions both return the title children of the parent of the
context node:
../title
parent::node()/child::title

Table 102 shows examples of abbreviations in XPath expressions

Table 102. Abbreviations in XPath Expressions

778

Example

Description

para

Selects the para children of the context node

Selects all element children of the context node

node_test

Evaluates all children of the context node and returns those that test
true for the particular node_test

*/para

Selects all para grandchildren of the context node

para[1]

Selects the first para child of the context node

Stylus Studio User Guide

XPath Quick Reference

Table 102. Abbreviations in XPath Expressions
Example

Description

para[last()]

Selects the last para child of the context node

/doc/chapter[5]/sect

Selects the second section of the fifth chapter of the doc child of
the context node

ion[2]
para[@type="warning"
]
para[@type="warning"
][5]
para[5][@type="warni
ng"]

Selects para children of the context node that have type attributes
with a value of warning
Selects the fifth para child of the context node that has a type
attribute with a value of warning
Selects the fifth para child of the context node if that child has a
type attribute with a value of warning

chapter[title]

Selects the chapter children of the context node that have one or
more title children

//para

Selects all para descendants of the document root

chapter//para

Selects all para descendants of chapter children of the context

node

//olist/item

Selects all item elements that have olist parents

Selects the context node

.//para

Selects the para descendants of the context node

Selects the parent of the context node

Selects all attributes of the context node

@name

Selects the name attribute of the context node

../@name

Selects the name attribute of the parent of the context node

Stylus Studio User Guide

779

Writing XPath Expressions

780

Stylus Studio User Guide

Chapter 11

Working with XQuery in Stylus Studio

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite. Some features, like query plan, are
available only in Stylus Studio XML Enterprise Suite.
Stylus Studio provides many features for working with XML Query (XQuery), including
a graphical mapper that allows you to construct a query without writing any code, and
tools to help you run and debug XQuery.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XQuery
Mapper video.
You can learn more about other video demonstrations of the XQuery Mapper here:
http://www.stylusstudio.com/learn_xquery.html#xquery_1.
This chapter covers the following topics:

Getting Started with XQuery in Stylus Studio on page 782

An XQuery Primer on page 788

Understanding FLWOR Expressions on page 798

Building an XQuery Using the Mapper on page 813

User-Defined Functions on page 844

Working with Relational Data Sources on page 850

Working with Zip Archive Format Files as Data Sources on page 862

Updating Relational Databases on page 866

Debugging XQuery on page 887

Using DataDirect XQuery Execution Plans on page 895

Stylus Studio User Guide

781

Working with XQuery in Stylus Studio

Creating an XQuery Scenario on page 900

Generating XQuery Documentation on page 913
Using XQuery to Invoke a Web Service on page 919
Using Web Services in XQuery on page 921
Generating Java Code for XQuery on page 933
Generating C# Code for XQuery on page 938

Getting Started with XQuery in Stylus Studio

This section describes working with XQuery in Stylus Studio. It covers the following
topics:

What is XQuery? on page 782

What is an XQuery? on page 783

The Stylus Studio XQuery Editor on page 783

What is XQuery?
XML Query (XQuery) is the World Wide Web Consortium (W3C) language for querying
XML. XQuery is a language developed by the W3C XML Query working group.

Example
The XQuery grammar allows you to define expressions like those shown in the following
sample XQuery, R-Q2.xquery:
<result>
{
for $i in doc("items.xml")/items/item_tuple
let $b := doc("bids.xml")//bid_tuple[itemno = $i/itemno]
where contains($i/description,"Bicycle")
order by $i/itemno
return
<item_tuple>
{$i/itemno}
{$i/description}
<high_bid>
{ max ( for $c in $b/bid return xs:decimal($c) ) }
</high_bid>
</item_tuple>
}
</result>

782

Stylus Studio User Guide

Getting Started with XQuery in Stylus Studio

This and other XQuery examples are provided in the Stylus Studio examples\XQuery
directory.

Sources for Additional XQuery Information

See An XQuery Primer on page 788 if you are just getting started with XQuery. For more
detailed information, including the formal W3C XQuery specification, visit
http://www.w3.org/XML/Query (the W3C page for XML Query).

What is an XQuery?
In Stylus Studio, an XQuery is a document with a .xquery extension. Stylus Studio
expects documents with this extension to contain a query expressed using the XML Query
language.

The Stylus Studio XQuery Editor

In Stylus Studio, you use the XQuery editors textual editor and graphical interfaces to
work with XQuery. The XQuery editor consists of the XQuery Source, Mapper, and Plan
tabs. You use the XQuery Source and Mapper tabs to compose an XQuery.
By default, Stylus Studio gives new XQuery files a .xquery extension. You can save
XQuery using any extension you choose. If you decide to use a different extension, use
the File Types page of the Options dialog box to associate that extension with the XQuery
editor.

XQuery Source Tab

You can use the XQuery Source tab to view, compose, preview, and debug your XQuery.
For example, you can edit query text directly, set breakpoints, and debug your XQuery on
this tab. The tab is divided into two panes:

An editing pane, which shows the XQuery code, and

A schema pane, which displays the schema of the source documents you are using to
build your XQuery. You can hide the schema pane to view more of the XQuery code
by clicking the show/hide button at the base of the splitter, which allows you to vary
the relative width of the two panes.
Tip

You can drag schema objects directly to the editing pane. This allows you to quickly
create FLWOR and XPath expressions, for example, without writing any code or
introducing typographical errors to the source.

Stylus Studio User Guide

783

Working with XQuery in Stylus Studio

Figure 322. XQuery Source Tab

Stylus Studios Sense:X automatic completion feature is supported for XQuery Sense:X
simplifies editing and helps ensure well-formed XML for queries you compose manually.
You can define other XQuery editor settings on the Editor General and Editor Format
pages of the Options dialog box. (Click Tools > Options.)
You can preview the XQuery result by clicking the Preview Result button (
). Results
are displayed in the Preview window at the bottom of the XQuery editor, and, optionally,
in any external application that you specify.

784

Stylus Studio User Guide

Getting Started with XQuery in Stylus Studio

Mapper Tab
The Mapper tab provides an interface that allows you to compose and view your XQuery
graphically.

Figure 323. XQuery Editor Mapper Tab

The Mapper tab consists of these areas:

Source document pane, in which you add one or more source documents.

Target structure pane, in which you specify the structure of the result you want the
XQuery to return.

Mapper canvas, on which you can define conditions, functions, and operations for
source document nodes to filter return values that are then mapped to the target node.

Text pane. The text pane allows you to view the XQuery code while using the mapper.
This is a great way to see how changes to the mapper affect the XQuery code, without
the need to switch to the XQuery Source tab. Of course, the XQuery Source tab is
available if you prefer working with the code using a full-page view. All views
Mapper tab, XQuery Source tab, and the text pane are synchronized.

Stylus Studio User Guide

785

Working with XQuery in Stylus Studio

As with the XQuery Source tab, you can preview XQuery results from the Mapper tab by
clicking the Preview Result button (
). Debugging, however, can be performed from
the XQuery Source tab only.
See Building an XQuery Using the Mapper to learn more about the features of the XQuery
editor Mapper tab.

Plan Tab
The Plan tab displays how the DataDirect XQuery processor will execute your XQuery
code and includes information about the type of SQL statements that are used to access
relational data, when XML streaming is being used, which temporary tables are being
created, when variables are being called, and so on.

Figure 324. Plan Tab Displays XQuery Execution Information

One of the main benefits of using the query plan feature is that it can help you tune your
queries for the best performance possible. See Using DataDirect XQuery Execution
Plans on page 895 for more information.

786

Stylus Studio User Guide

Getting Started with XQuery in Stylus Studio

XQuery Source and Mapper Tab Interaction

Changes made to an XQuery on the Mapper tab are reflected on the XQuery Source tab,
and vice versa. For example, if you start writing your XQuery on the XQuery Source tab
and then click the Mapper tab, Stylus Studio displays a graphic representation of your
XQuery code. If you next edit the XQuery graphically (adding a function or a FLWOR
block and mapping the return value to a node in the target structure, for example) and then
return to the XQuery Source tab, you will see that Stylus Studio has updated the XQuery
code based on your edits on the Mapper tab. Viewing the code on the XQuery Source tab
that Stylus Studio creates based on actions performed on the Mapper tab can be a useful
aid to learning XQuery syntax.
Note An incomplete XQuery artifact created on the Mapper tab is removed from the XQuery
you are composing when you click the XQuery Source tab because it cannot be expressed

in XQuery given its current definition. For example, imagine creating a FLWOR block
that is not mapped to a node in the target structure. The FLWOR (pronounced flower)
block appears on the Mapper tab, but Stylus Studio does not generate any code for it or
display it on the XQuery Source tab, and when you return to the Mapper tab you will see
that the FLWOR block has been removed.

Stylus Studio User Guide

787

Working with XQuery in Stylus Studio

An XQuery Primer
This XQuery primer was adapted from a whitepaper written by Dr. Michael Kay. You can
read the original document on the Stylus Studio Web site. This primer covers the
following topics:

What is XQuery For?

Your First XQuery

Accessing XML Documents with XQuery

XQuery and XPath

Introduction to FLWOR Expressions

Generating XML Output with XQuery

Accessing Databases with XQuery

What is XQuery For?

XQuery was devised primarily as a query language for data stored in XML form. So its
main role is to get information out of XML databases this includes relational databases
that store XML data, or that present an XML view of the data they hold.
Some people are also using XQuery for manipulating free-standing XML documents, for
example, for transforming messages passing between applications. In that role XQuery
competes directly with XSLT, and which language you choose is largely a matter of
personal preference.
In fact, some people like XQuery so much that they are even using it for rendering XML
into HTML for presentation. That's not really the job XQuery was designed for, and there
are other technologies, like XSLT, that are better suited for this purpose, but once you get
to know a tool, you tend to find new ways of using it.

Your First XQuery

Try a few simple examples to get acquainted with XQuery. Start Stylus Studio, and open
a new XQuery (File > New > XQuery File). Save the file now (if you do not, Stylus Studio
will prompt you to save it when you preview your first XQuery).
Type the following in the XQuery Editor:
Hello, world!

788

Stylus Studio User Guide

An XQuery Primer

Now, click the Preview Result button (

XQuery in the Preview window:

), and Stylus Studio displays the result of this

Hello, world!

Enter a simple equation (2+2) and click the Preview Result button (
result is:

). Predictably, the

Finally, try the XQuery function current-time() and click the Preview Result button
( ):
11:27:38Z

Your results, will vary based on several conditions. For example, the XQuery processor
you use to execute the XQuery will affect the precision of the time value (fractions of
seconds), and the time zone (here, shown as Z) is determined by how your system is
configured.
None of these is a very useful query on its own, but within a query language you need to
be able to perform little calculations and XQuery has this covered. Further, XQuery is
designed so that expressions can be fully nested that is, any expression can be used
within any other expression, provided that it delivers a value of the right type and this
means that expressions that are primarily intended for selecting data within a where clause
can also be used as free-standing queries in their own right.

Accessing XML Documents with XQuery

Though XQuery is capable of handling mundane tasks like those described in the previous
section, it is designed to access XML data. Right now, we will look at some simple queries
that require an XML document as their input. For this purpose, we will use videos.xml,
which is installed with Stylus Studio in the \examples\VideoCenter directory. You can also
find a copy of this XML document on the Stylus Studio Web site.
XQuery allows you to access the file directly from either of these locations, using a
suitable URL as an argument for its doc() function. If you wanted to retrieve and display

Stylus Studio User Guide

789

Working with XQuery in Stylus Studio

the entire file from your Stylus Studio installation directory, your doc() might look like
this:
doc('file:///c:/Program%20Files/Stylus%20Studio%20X14%20XML%20Professional
%20Suite/examples/VideoCenter/videos.xml')

To fetch this document from the Stylus Studio Web site, you would need a doc() like this:
doc('http://www.stylusstudio.com/examples/videos.xml')

(The latter doc() function will work only if you are online; and if you are behind a
corporate firewall you might have to modify your Java configuration to make it work.)

Handling URLs
URLs like those used in the previous example can be a bit unwieldy, but there are some
shortcuts you can use.

In Stylus Studio, you can specify the source document as the Main Input on the
General tab of the Scenario Properties dialog box. Once you browse to the
appropriate file and select it, you can refer to it in your XQuery code as simply .
(dot).

If you are working directly with a command line processor such as Saxon, you can
copy the file locally (c:\xquery\videos.xml, for example) and work with it from that
location. Once you have done this, you can use the command line option -s
c:\xquery\videos.xml and again be able to refer to the input document in your
XQuery code as . (dot).

The videos.xml Document

The videos.xml document contains a number of sections: video_template, actors, and
videos. You might want to open this document in the XML Editor to get acquainted with
it if you are not already familiar with it.

790

Stylus Studio User Guide

An XQuery Primer

XQuery and XPath

We can access the actors section of videos.xml using this expression: .//actors. When
we execute this XQuery we get the following result:
<actors>
<actor
<actor
<actor
<actor
<actor
<actor
<actor
<actor
<actor
...etc...
</actors>

id="00000015">Anderson, Jeff</actor>
id="00000030">Bishop, Kevin</actor>
id="0000000f">Bonet, Lisa</actor>
id="00000024">Bowz, Eddie</actor>
id="0000002d">Curry, Tim</actor>
id="00000033">Dullea, Keir</actor>
id="00000042">Fisher, Carrie</actor>
id="00000006">Ford, Harrison</actor>
id="00000045">Foster, Jodie</actor>

That was our first real query. If you are familiar with XPath, you might recognize that
all the queries so far have been valid XPath expressions. We have used a couple of
functions current-time() and doc() that might be unfamiliar because they are new
in XPath 2.0, which is still only a draft; but the syntax of all the queries so far is plain
XPath syntax. In fact, the XQuery language is designed so that every valid XPath
expression is also a valid XQuery query.
This means we can write more complex XPath expressions like this one:
.//actors/actor[ends-with(., 'Lisa')]

which gives us this output:

<actor id="0000000f">Bonet, Lisa</actor>
<actor id="0000001b">Spoonhauer, Lisa</actor>

Different systems might display this output in different ways. Technically, the result of
this query is a sequence of two element nodes in a tree representation of the source XML
document, and there are many ways a system might choose to display such a sequence on
the screen. Stylus Studio gives you the choice of a text view, like the one shown above,
and a tree view: you use the buttons next to the Preview window to switch from one to the
other. Here is what the tree view looks like:
This example used another function ends-with() that's new in XPath 2.0. We are
calling it inside a predicate (the expression between the square brackets), which defines a
condition that nodes must satisfy in order to be selected. This XPath expression has two
parts: a path .//actors/actor that indicates which elements we are interested in, and a

Stylus Studio User Guide

791

Working with XQuery in Stylus Studio

predicate [ends-with(., Lisa)] that indicates a test that the nodes must satisfy. The
predicate is evaluated once for each selected element; within the predicate, the expression
. (dot) refers to the node that the predicate is testing, that is, the selected actor.
The / in the path informally means go down one level, while the // means go
down any number of levels. If the path starts with ./ or .// you can leave out the
initial .. (This assumes that the selection starts from the top of the tree, which is always
the case in our examples.) You can also use constructs like /.. to go up one level, and
/@id to select an attribute. Again, this is all familiar if you already know XPath.
XPath is capable of doing some pretty powerful selections, and before we move on to
XQuery proper, let us look at a more complex example. Suppose we want to find the titles
of all the videos featuring an actor whose first name is Lisa. If we look at the videos.xml
file, we see that each video in the file is represented by a video element like this one:
<video id="647599251">
<studio></studio>
<director>Francesco Rosi</director>
<actorRef>916503211</actorRef>
<actorRef>916503212</actorRef>
<title>Carmen</title>
<dvd>18</dvd>
<laserdisk></laserdisk>
<laserdisk_stock></laserdisk_stock>
<genre>musical</genre>
<rating>PG</rating>
<runtime>125</runtime>
<user_rating>4</user_rating>
<summary>A fine screen adaptation of Bizet's popular opera.</summary>
<details>Placido Domingo does it again, this time in Bizet's popular opera.</details>
<vhs>15</vhs>
<beta_stock></beta_stock>
<year>1984</year>
<vhs_stock>88</vhs_stock>
<dvd_stock>22</dvd_stock>
<beta></beta>
</video>

The query required to provide the results we desire is written like this:
//video[actorRef=//actors/actor[ends-with(., 'Lisa')]/@id]/title

Again, this is pure XPath (and therefore a valid XQuery). You can read it from left-to-right
as:

Start at the implicitly-selected document (videos.xml)

Select all the <video> elements at any level

792

Stylus Studio User Guide

An XQuery Primer

Choose those that have an actorRef element whose value is equal to one of the values
of the following:

Select all the <actors> elements at any level

Select all their <actor> child elements

Select the element only if its value ends with Lisa

Select the value of the id attribute

Select the <title> child element of these selected <video> elements

When run against our source document, the result of this XQuery is:
<title>Enemy of the State</title>
<title>Clerks</title>

Many people find that at this level of complexity, XPath syntax gets rather mind-boggling.
In fact, this example just about stretches XPath to its limits. For this kind of query, and for
anything more complicated, XQuery syntax comes into its own. But it is worth
remembering that there are many simple things you can do with XPath alone, and that
every valid XPath expression is also valid in XQuery.

Stylus Studio User Guide

793

Working with XQuery in Stylus Studio

XPath Query Editor

Stylus Studio provides a built-in XPath Query Editor in its XML Editor that allows you
to visually edit and test complex XPath expressions, and it supports both version 1.0 and
2.0.

Figure 326. XPath Query Editor

See Using the XPath Query Editor on page 694 to learn more about using this tool.

Introduction to FLWOR Expressions

If you have used SQL, then you will have recognized the last example as a join between
two tables the videos table and the actors table. Join queries are not quite the same in
XML, because the data is hierarchic rather than tabular, but XQuery allows you to write
join queries in a similar way to the familiar SQL approach. The equivalent of the SQL
SELECT expression is called the FLWOR expression, named after its five clauses: for, let,

794

Stylus Studio User Guide

An XQuery Primer

where, order by, return. Here is the last example (all videos with an actor named Lisa,
rewritten this time as a FLWOR expression.
let $doc := .
for $v in $doc//video,
$a in $doc//actors/actor
where ends-with($a, 'Lisa')
and $v/actorRef = $a/@id
return $v/title

When we run this XQuery, we get the same result as before.

Lets examine the FLWOR expression:

The let clause simply declares a variable. We included this here because when we
deploy the query we might want to set this variable differently; for example, we might
want to initialize it to doc(videos.xml), or to the result of some complex query that
locates the document in a database.

The for clause defines two range variables: one processes all the videos in turn, the
other processes all the actors in turn. Taken together, the FLWOR expression is
processing all possible pairs of videos and actors.

The where clause then selects those pairs that we are actually interested in. We are
only interested if the actor appears in that video, and we are only interested if the
actors name ends in Lisa.

Finally the return clause tells the system what information we want to get back. In this
case we want the title of the video.
If you have been following very closely, you might have noticed one little XPath trick that
we retained in this query: most videos will feature more than one actor (though this
particular database does not attempt to catalog the bit-part players). The expression
$v/actorRef therefore selects several elements. The rules for the = operator in XPath (and
therefore also in XQuery) are that it compares everything on the left with everything on
the right and returns true if there is at least one match. In effect, it is doing an implicit join.
If you want to avoid exploiting this feature, and you want to write your query in a more
classically relational form, you could express it as follows:
let $doc := .
for $v in $doc//video,
$va in $v/actorRef,
$a in $doc//actors/actor
where ends-with($a, 'Lisa')
and $va eq $a/@id
return $v/title

Stylus Studio User Guide

795

Working with XQuery in Stylus Studio

This time we used a different equality operator, eq, which follows more conventional rules
than = does: it strictly compares one value on the left with one value on the right. (But like
comparisons in SQL, it has special rules to handle the case where one of the values is
absent.)
What about the O in FLWOR? That is there so you can get the results in sorted order.
Suppose you want the videos in order of their release date. Here's the revised query:
let $doc := .
for $v in $doc//video,
$a in $doc//actors/actor
where ends-with($a, 'Lisa')
and $v/actorRef = $a/@id
order by $v/year
return $v/title

If you are wondering why FLWOR is not really a LFWOR expression: the for and let
clauses can appear in any order, and you can have any number of each. To learn more
about the FLWOR expression, see Understanding FLWOR Expressions on page 798.

Generating XML Output with XQuery

So far all the queries we have written have selected nodes in the source document. We
have shown the results as if the system copies the nodes to create some kind of result
document, and if you execute the XQuery in Stylus Studio or run Saxon from the
command line that is exactly what happens. But this is simply a default mode of
execution. In a real application you want control over the form of the output document,
which might well be the input to another application perhaps the input to an XSLT
transformation or even another query.

796

Stylus Studio User Guide

An XQuery Primer

XQuery allows the structure of the result document to be defined using an XML-like
notation. Here is an example that fleshes out our previous query with some XML markup:
declare variable $firstName as xs:string external;
<videos featuring="{$firstName}">
{
let $doc := .
for $v in $doc//video,
$a in $doc//actors/actor
where ends-with($a, $firstName)
and $v/actorRef = $a/@id
order by $v/year
return
<video year="{$v/year}">
{$v/title}
</video>
}
</videos>

We have also changed the query so that the actor's first name is now an externally defined
parameter. This makes the query reusable. The way parameters are supplied varies from
one XQuery processor to another. In Stylus Studio, select XQuery > Scenario Properties;
click the Parameter Values tab, and Stylus Studio provides an area to specify values for
any variables defined in the XQuery.
Enter Lisa, in quotes (Stylus Studio expects an expression, so if the quotes are omitted,
this value would be taken as a reference to an element named <Lisa>).
If instead you are running Saxon from the command line, you can enter:
java net.sf.saxon.Query sample.xquery firstName=Lisa

Either way, our XQuery returns the following result:

<videos featuring="Lisa">
<video year="1999">
<title>Enemy of the State</title>
</video>
<video year="1999">
<title>Clerks</title>
</video>
</videos>

As you might recall from our previous XQuery, this version of the XQuery is not
especially well-designed as it returns videos featuring different actresses named Lisa.
Take some time and modify the XQuery to see if you can improve it.

Stylus Studio User Guide

797

Working with XQuery in Stylus Studio

Accessing Databases with XQuery

At the start of this section, we stated that the main purpose of XQuery is to extract data
from XML databases, but all our examples have used a single XML document as input.
People sometimes squeeze a large data set (for example, a corporate phone directory) into
a single XML document, and process it as a file without the benefit of any database
system. While there are preferable alternatives, if the data volumes do not go above a few
megabytes and the transaction rate is modest, then XML-document-as-database is a
perfectly feasible storage mechanism. In other words, the examples in this section are not
totally unrealistic.
If you have got a real database, however, the form of the queries used in this section will
not need to change all that much from these examples. Instead of using the doc() function
(or simply .) to select a document, you are likely to call the collection() function to
open a database, or a specific collection of documents within a database. The actual way
collections are named is likely to vary from one database system to another. The result of
the XQuery collection() function is a set of documents (more strictly, a sequence of
documents, but the order is unlikely to matter), and you can process this using XPath
expressions or FLWOR expressions in just the same way as you address a single
document.
There is a lot more to databases than doing queries, of course. Each product has its own
ways of setting up the database, defining schemas, loading documents, and performing
maintenance operations such as backup and recovery. XQuery currently handles only one
small part of the job. In the future it is also likely to have an update capability, but in the
meantime each vendor is defining his own.
One particularly nice feature of XQuery is that it has the potential to combine data from
multiple databases (and freestanding XML documents). DataDirect XQuery, which
supports access to Oracle, DB2, SQL Server, and Sybase is one product that addresses this
need.

Understanding FLWOR Expressions

This XQuery primer was adapted from a whitepaper written by Dr. Michael Kay. You can
read the original document on the Stylus Studio Web site. This section covers the
following topics:

Simple XQuery FLWOR Expressions

The Principal Parts of an XQuery FLWOR Expression

798

Stylus Studio User Guide

Understanding FLWOR Expressions

Other Parts of the XQuery FLWOR Expression

Grouping

Simple XQuery FLWOR Expressions

The simplest XQuery FLWOR expression might be something like this:
for $v in $doc//video return $v

This returns all of the video elements in $doc.

We can add a bit of substance by adding XQuery where and return clauses:
for $v in $doc//video
where $v/year = 1999
return $v/title

This returns all of the titles of videos released in 1999.

If you know SQL, that XQuery probably looks reassuringly similar to the equivalent SQL
statement:
SELECT v.title
FROM video v
WHERE v.year = 1999

And if you know XPath, you might be wondering why our XQuery cannot be written as
this:
$doc//video[year=1999]/title

Well, you can. This XPath expression is completely equivalent to the FLWOR expression
above, and furthermore, it is a legal XQuery query. In fact, every legal XPath expression
is also legal in XQuery. Thus the first query in this section can be written as:
$doc//video

Which style you prefer seems to depend on where you are coming from: if you have been
using XML for years, especially XML with a deep hierarchy as found in narrative
documents, then you will probably be comfortable with path expressions. But if you are
more used to thinking of your data as representing a table, then the FLWOR style might
suit you better.

Stylus Studio User Guide

799

Working with XQuery in Stylus Studio

As you will see, FLWOR expressions are a lot more powerful than path expressions when
it comes to doing joins. But for simple queries, the capabilities overlap and you have a
choice. Although it might be true that in SQL every query is a SELECT statement, it is
not so that in XQuery every query has to be a FLWOR expression.

The Principal Parts of an XQuery FLWOR Expression

The name FLWOR comes from the five clauses that make up a FLWOR expression: for,
let, where, order by, and return. Most of these clauses are optional: the only clause that
is always present is the XQuery return clause (though there must be at least one XQuery
for or let clause as well). To see how FLWOR expressions work, we will build up our
understanding one clause at a time.

F is for For
The behavior of the for clause is fairly intuitive: it iterates over an input sequence and
calculates some value for each item in that sequence, returning a sequence obtained by
concatenating the results of these calculations. In simple cases there is one output item for
every input item. So, this FLWOR expression:
for $i in (1 to 10)
return $i * $i

returns the sequence (1, 4, 9, 16, 25, 36, 49, 64, 81, 100). In this example, the input items
are simple numbers, and the output items are also simple numbers. Numbers are an
example of what XQuery calls atomic values; other examples are strings, dates, booleans,
and URIs. But the XQuery data model allows sequences to contain XML nodes as well as
atomic values, and the for expression can work on either.
Here is an example that takes nodes as input, and produces numbers as output. It counts
the number of actors listed for each video in a data file:
for $v in //video
return count($v/actorRef)

You can run this in Stylus Studio or in Saxon, using the example videos.xml file as input.
(Tips on setting up these tools are described in the previous section, An XQuery Primer.)
Here's the output from Stylus Studio:
The Preview window shows the result: a rather mundane sequence of numbers (2, 4, 3, 3,
3...).

800

Stylus Studio User Guide

Understanding FLWOR Expressions

This gives us a good opportunity to point out that a FLWOR expression is just an
expression, and you can use it anywhere an expression is allowed: it doesn't have to be at
the top level of the query. There is a function, avg(), to compute the average of a sequence
of numbers, and we can use it here to find the average number of actors listed for each of
the movies in our data file:
avg(
for $v in //video
return count($v/actorRef)
)

The answer is 2.2941176 and a bit the number of decimal places shown will depend on
the XQuery processor that you use. If you are only interested in the answer to two decimal
places, try:
round-half-to-even(
avg(
for $v in //video
return count($v/actorRef)
),
2)

which gives a more manageable answer of 2.29. (The strange name round-half-to-even
is there to describe how this function does rounding: a value such as 2.145 is rounded to
the nearest even number, in this case 2.14.) This is all designed to demonstrate that
XQuery is a functional language, in which you can calculate a value by passing the result
of one expression or function into another expression or function. Any expression can be
nested inside any other, and the FLWOR expression is no exception.
If you are coming from SQL, your instinct was probably to try and do the averaging and
rounding in the return clause. But the XQuery way is actually much more logical. The
return clause calculates one value for each item in the input sequence, whereas the avg()
function applies to the result of the FLWOR expression as a whole.
As with some of the examples in An XQuery Primer, XPath 2.0 allows you to write this
example using path expressions alone if you prefer:
round-half-to-even(avg(//video/count(actorRef)), 2)

We have seen a for expression that produces a sequence of numbers from another
sequence of numbers, and we have seen one that produces a sequence of numbers from a

Stylus Studio User Guide

801

Working with XQuery in Stylus Studio

sequence of selected nodes. We can also turn numbers into nodes: the following query
selects the first five videos.
for $i in 1 to 5 return (//video)[$i]

And we can get from one sequence of nodes to another sequence of nodes. This example
shows all the actors that appear in any video:
for $actorId in //video/actorRef
return //actors/actor[@id=$actorId]

In fact, this last example probably represents the most common kind of for expression
encountered, but we introduced it last to avoid leaving you with the impression that it is
the only kind there is.
Once again, you could write this example as an XPath expression:
//actors/actor[@id=//video/actorRef]

You might ask yourself at this point, Isnt a variable being updated when we write
something like the following?
for $v in //video
let $x := xs:int($v/runtime) * xdt:dayTimeDuration("PT1M")
return concat($v/title, ": ",
hours-from-duration($x), " hour(s) ",
minutes-from-duration($x), " minutes")

(This query shows the running time of each video. It first converts the stored value from
a string to an integer, then multiplies it by one minute (PT1M) to get the running time as a
duration, so that it can extract the hours and minutes components of the duration. Try it.)
Here the variable $x has a different value each time around the XQuery for loop. This feels
a bit like an update. Technically though, each time round the for loop you are creating a
new variable with a new value, rather than assigning a new value to the old variable. What
you cannot do is to accumulate a value as you go around the loop. Try doing this to see
what happens:
let $totalDuration := 0
for $v in //video
let $totalDuration := $totalDuration + $v/runtime
return $totalDuration

The result is not a single number, but a sequence of numbers, one for each video. This
example is actually declaring two separate variables that happen to have the same name.
You are allowed to use the same variable name more than once, but this is probably not a
good idea, because it will only get your readers confused. You can see more clearly what
this query does if we rename one of the variables.
let $zero := 0
for $v in //video
let $totalDuration := $zero + $v/runtime
return $totalDuration

which is the same as this:

for $v in //video
return 0 + $v/runtime

Hopefully it is now clear why this returns a sequence of numbers rather than a single total.
The correct way to get the total duration is to use the sum function:
sum(//video/runtime).

Stylus Studio User Guide

805

Working with XQuery in Stylus Studio

W is for Where
The XQuery where clause in a FLWOR expression performs a very similar function to the
WHERE clause in a SQL select statement: it specifies a condition to filter the items we are
interested in. The where clause in a FLWOR expression is optional, but if it appears it must
only appear once, after all the for and let clauses. Here is an example that restates one
of our earlier queries, but this time using a where clause:
for $genre in //genre/choice
for $video in //video
for $actorRefs in $video/actorRef
for $actor in //actor
where $video/genre = $genre
and $actor/@id = $actorRefs
return concat($genre, ": ", $actor)

This style of coding is something that SQL users tend to be very comfortable with: first
define all the tables you are interested in, then define a WHERE expression to define all the
restriction conditions that select subsets of the rows in each table, and join conditions that
show how the various tables are related.
Although many users seem to find that this style comes naturally, an alternative is to do
the restriction in a predicate attached to one of the for clauses, like this:
for $genre in //genre/choice
for $video in //video[genre = $genre]
for $actorRefs in $video/actorRef
for $actor in //actor[@id = $actorRefs]
return concat($genre, ": ", $actor)

Perhaps there is a balance between the two; you will have to find the style that suits you
best. With some XQuery processors one style or the other might perform better (and with
Stylus Studio, you can easily create multiple XQuery scenarios that execute the same code
but use different XQuery processors), but a decent optimizer is going to treat the two
forms as equivalent.
Do remember that in a predicate, you select the item that you are testing relative to the
context node, while in the where clause, you select it using a variable name. A bare name
such as genre is actually selecting ./child::genre that is, it is selecting a child of the
context node, which in this case is a <video> element. It is very common to use such
expressions in predicates, and it is very uncommon to use them (except by mistake!) in
the where clause. If you use a schema-aware processor like Saxon, then you might get an
error message when you make this mistake; in other cases, it is likely that the condition

806

Stylus Studio User Guide

Understanding FLWOR Expressions

will not select anything. The where condition will therefore evaluate to false, and you will
have to puzzle out why your result set is empty.

O is for Order By
If there is no order by clause in a FLWOR expression, then the order of the results is as
if the for clauses defined a set of nested loops. This does not mean they actually have to
be evaluated as nested loops, but the result has to be the same as if they were. That is an
important difference from SQL, where the result order in the absence of any explicit
sorting is undefined. In fact, XQuery defines an alternative mode of execution, unordered
mode, which is similar to the SQL rules. You can select this in the query prolog, and the
processor might even make it the default (this is most likely to happen with products that
use XQuery to search a relational database). Some products (Stylus Studio and Saxon
among them) give you exactly the same result whether or not you specify unordered mode
since the XQuery specification says that in unordered mode anything goes, that is
perfectly acceptable.
Often however you want the query results in sorted order, and this can be achieved using
the order by clause. Let's sort our videos in ascending order of year, and within that in
decreasing order of the user rating:
for $x in //video
order by $x/year ascending, number($x/user-rating) descending
return $x/title

Note that we have not actually included the sort keys in the data that we are returning
(which makes it a little difficult to verify that it is working properly; but it is something
you might well want to do in practice). We have explicitly converted the user-rating to a
number here to use numeric sorting: this makes sure that 10 is considered a higher rating
than 2. This is not necessary if the query is schema-aware, because the XQuery processor
then knows that user-rating is a numeric field.
Ordering gets a little complicated when there is more than one for clause in the FLWOR
expression. Consider this example:
for $v in //video
for $a in //actor
where $v/actorRef = $a/@id
order by $a, $v/year
return concat($a, ":", $v/title)

To understand this we have to stop thinking about the two for clauses as representing a
nested loop. We cannot compute all the result values and then sort them, because the result
Stylus Studio User Guide

807

Working with XQuery in Stylus Studio

does not contain all the data used for sorting (it orders the videos for each actor by year,
but only shows their titles). In this case we could imagine implementing the order
specification by rearranging the for clauses and doing a nested loop evaluation with a
different order of nesting; but that doesn't work in the general case. For example, it
wouldn't work if the order by clause changed to:
order by substring-after($a, ","),
$v/year,
substring-before($a, ",")

to sort first on the surname, then on the year, then on the first name (admittedly,
nonsensical coding, but we show it only to illustrate that it is allowed).
The XQuery specification introduces a concept of tuples, borrowed from the relational
model, and describes how the sort works in terms of creating a sequence of tuples
containing one value for each of the variables, and then sorting these notional tuples.

R is for Return
Every XQuery FLWOR expression has a return clause, and it always comes last. It
defines the items that are included in the result. What more can one say about it?
Usually the XQuery return clause generates a single item each time it is evaluated. In
general, though, it can produce a sequence. For example, you can do this:
for $v in //video[genre="comedy"]
return //actor[@id = $v/actorRef]

which selects all the actors for each comedy video. However, the result is a little
unsatisfactory, because we cannot tell which actors belong to which video. It is much
more common here to construct an element wrapper around each result:
for $v in //video[genre="comedy"]
return
<actors video="{$v/title}">
{//actor[@id = $v/actorRef]}
</actors>

We have not discussed XQuery element and attribute constructors until now. But in
practice, a FLWOR expression without element constructors can only produce flat lists of
values or nodes, and that is not usually enough. We usually want to produce an XML
document as the output of the query, and XML documents are not flat.

808

Stylus Studio User Guide

Understanding FLWOR Expressions

This means that very often, instead of doing purely relational joins that generate a flat
output, we want to construct hierarchic output using a number of nested FLWOR
expressions. Here is an example that (like the previous query) lists the videos for each
actor, but with more structure this time:
for $v in //video[genre="comedy"]
return
<actors video="{$v/title}">
{for $a in //actor[@id = $v/actorRef]
return
<actor>
<firstname>{substring-after($a, ",")}</firstname>
<lastname>{substring-before($a, ",")}</lastname>
</actor>
}
</actors>

Here we really do have two nested XQuery loops. The two queries below are superficially
similar, and in fact they return the same result:
for $i in 1 to 5
for $j in ("a", "b", "c")
return concat($j, $i)

and:
for $i in 1 to 5
return
for $j in ("a", "b", "c")
return concat($j, $i)

But now add an order by clause to both queries so they become:

for $i in 1 to 5
for $j in ("a", "b", "c")
order by $j, $i
return concat($j, $i)

and:
for $i in 1 to 5
return
for $j in ("a", "b", "c")
order by $j, $i
return concat($j, $i )

Stylus Studio User Guide

809

Working with XQuery in Stylus Studio

The difference now becomes apparent. In the first case the result sequence is a1, a2, a3,
b1, b2, b3,. In the second case it remains a1, b1, c1, a2, b2, c2. The reason is that the
first query is a single FLWOR expression (one return clause), and the order by clause
affects the whole expression. The second query consists of two nested loops, and the
order by clause can only influence the inner loop.
So, the return clause might seem like the least significant part of the FLWOR, but a
misplaced return can make a big difference in the result. Consider always aligning the F,
L, O, W, and R clauses of a single FLWOR expression underneath each other, and
indenting any nested expressions, so that you can see what is going on. You can do this
easily with the Stylus Studio XQuery Editor.

Other Parts of the XQuery FLWOR Expression

We have explored the five clauses of the FLWOR expression that give it its name. But
there are a few details we have not touched on, partly because they are not used very often.
They are summarized in this section.

Declaring XQuery Types

In the for and let clauses, you can (if you wish) declare the types of each variable. Here
are some examples.
for $i as xs:integer in 1 to 5 return $i*2

for $v as element(video) in //video return $v/runtime

let $a as element(actor)* := //actor return string($a)

Declaring types can be useful as a way of asserting what you believe the results of the
expressions are, and getting an error message (rather than garbage output) if you have
made a mistake. It helps other people coming along later to understand what the code is
doing, and to avoid introducing errors when they make changes.
Unlike types declared in other contexts such as function signatures (and unlike variables
in XSLT 2.0), the types you declare must be exactly right. The system does not make any
attempt to convert the actual value of the expression to the type you declare for example
it will not convert an integer to a double, or extract the string value of an attribute node.

810

Stylus Studio User Guide

Understanding FLWOR Expressions

If you declare the type as string but the expression delivers an attribute node, that is a fatal
error.

XQuery Position Variables

If you have used XSLT and XPath, you have probably come across the position()
function, which enables you to number the items in a sequence, or to test whether the
current item is the first or the last. FLWOR expressions do not maintain an implicit
context in this way. Instead, you can declare an auxiliary variable to hold the current
position, like this:
for $v at $pos in //video
where $pos mod 2 = 0
return $v

This selects all the even-numbered videos useful if you are arranging the data in a table.
You can use $pos anywhere where you might use the primary variable $v. Its value ranges
from 1 to the number of items in the //video sequence. If there are no order by clauses,
then the position variables in each for clause follow a nested-loop model as you would
expect. If there is an order by clause, the position values represent the position of the
items before sorting (which is different from the rule in XSLT).
There are various keywords in the order by clause that give you finer control over how
the sorting takes place. The most important is the collation: unfortunately, though, the
way collations work is likely to be very product-dependent. The basic idea is that if you
are sorting the index at the back of a book, or the names in a phone directory, then you
need to apply rather more intelligent rules than simply sorting on the numeric Unicode
code value of each character. Upper-case and lower-case variants of letters may need to
be treated the same way, and accents on letters have some quite subtle rules in many
languages. The working group defining XQuery settled on the simple rule that every
collating sequence you might want has a name (specifically, a URI rather like a
namespace URI), and it is up to each vendor to decide what collations to provide and how
to name them.
Other things you can say in the order specification include defining whether empty values
of the sort key (XQuery's equivalent of null values in SQL) should go at the start or end
of the sequence, and whether the sort should be stable, in the sense that items with equal
sort key values preserve their original order.

Stylus Studio User Guide

811

Working with XQuery in Stylus Studio

Multiple Assignments
One simple syntax note. Instead of writing
for $i in ("a", "b", "c")
for $j in 1 to 5
return concat($i, $j)

you can write:

for $i in ("a", "b", "c"),
$j in 1 to 5
return concat($i, $j)

The meaning of both is the same. This same technique applies to let statements as well.

Grouping
If you are used to SQL, then you might have been wondering what the equivalent to its
DISTINCT and GROUP BY keywords is in XQuery FLOWR expressions. Well, SQL does not
have one.
You can, however, get a fair amount of mileage from the distinct-values() function.
Here is a query that groups videos according to who directed them:
<movies>
{for $d in distinct-values(//director) return
<director name="{$d}">
{ for $v in //video[director = $d] return
<title>{$v/title}</title>
}
</director>
}
</movies>

This is not an ideal solution: apart from anything else, it depends heavily on the ability of
the query processor to optimize the two nested loops to give good performance. But for
the time being, this is all there is. This is an area where vendors are very likely to offer
extensions to the language as defined by W3C.
Grouping was a notoriously weak point of XSLT 1.0, and the problem has been addressed
with considerable success in the 2.0 version of the language. XQuery will likely follow
suit.

812

Stylus Studio User Guide

Building an XQuery Using the Mapper

This section describes how to build a new XQuery using Stylus Studios XQuery Mapper.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XQuery
Mapper video.
You can learn more about other video demonstrations of the XQuery Mapper here:
http://www.stylusstudio.com/learn_xquery.html#xquery_1.
This section covers the following topics:

Process Overview

Data Sources

Specifying a Target Structure

Modifying the Target Structure

Mapping Source and Target Document Nodes

Simplifying the Mapper Canvas Display

Exporting Mappings

Searching Document Panes

FLWOR Blocks

Function Blocks

IF Blocks

Condition Blocks

Predicate Blocks

SQL Function Blocks

Process Overview
The process of using the XQuery mapper to build a new XQuery consists of the following
steps:
1.

Create a new XQuery file in Stylus Studio (File > New > XQuery File).

Click the Mapper tab in the XQuery editor.

Add one or more data sources (documents or relational database tables, for example).

Specify a target structure.

Stylus Studio User Guide

813

Working with XQuery in Stylus Studio

Map data source nodes to target structure nodes. As part of this step, you can
optionally define function, FLWOR (For each, Let, Where, Order by, Return), If, and
condition blocks to perform actions on source document nodes and map the return
value to the target structure node.

Stylus Studio uses the information expressed on the Mapper tab to compose an XQuery
that returns as its result an XML document that conforms to the structure represented by
the target structure you specify.
Each of these steps is described in greater detail in the following sections.

Working with Existing XQuery

You can, of course, open an existing XQuery in Stylus Studio. When you do, the XQuery
Source page displays the XML used to compose the XQuery, and the Mapper tab displays
the source documents, target structure, and source-target mappings that can be inferred
from the source XQuery file. All of the procedures described in this section can be
performed on new or existing XQuery files.

Saving the Mapping

You can save the XQuery mapping source and target document trees, as well as the
contents of the Mapper canvas as an image. See Exporting Mappings on page 832.

Data Sources
The role of a data source is to provide Stylus Studio with a structure that it can use to
compose the XQuery based on how you map individual source objects (XML elements
and attributes, or table rows, for example) to nodes in the target structure. Stylus Studio
infers the structure from the data source you specify and displays this structure on the Add
Source Document pane of the Mapper tab.
In Stylus Studio, a data source can be one or more of the following:

XML document

XML Schema (XSD)

Document type definition (DTD)

Relational database table

Microsoft Office Open XML documents

OpenDocument Format documents

814

Stylus Studio User Guide

Building an XQuery Using the Mapper

Zip files

This section covers the following topics:

Choosing a Data Source

Source Documents and XML Instances

How to Add a Source Document

How to Remove a Source Document

How Source Documents are Displayed

For information on using a relational database table as a source for XQuery mapper, see
Working with Relational Data Sources on page 850. For information on using
Microsoft Office Open XML, OpenDocument Format, and .zip files as data sources, see
Working with Zip Archive Format Files as Data Sources on page 862.

Choosing a Data Source

You can use one or more data sources to build an XQuery in Stylus Studio. You might
want to select multiple data sources if you need their elements or attributes to fully
describe the target structure or the desired XQuery result content, for example.
If you choose an XSD or DTD document, you must also choose an XML instance
document to associate with it. Stylus Studio uses the instance document associated with
a XSD or DTD source document to generate the XPath doc() function in the finished
XQuery code. This document is also used to preview XQuery results.
See Source Documents and XML Instances to learn more about how Stylus Studio treats
source documents. See Creating an XQuery Scenario to learn more about XQuery
scenarios.

Source Documents and XML Instances

As described previously, Stylus Studio uses the source document you specify to infer a
structure you can use to create mappings to the target structure. In addition to the
document structure, Stylus Studio needs document content information in order to
compose a complete XQuery. You provide this information by associating a XML
instance to each source document you specify.
Source documents can have one of three associations, each of which has implications for
the XPath expressions written by Stylus Studio when it composes the XQuery code. A
source document can be associated with

Stylus Studio User Guide

815

Working with XQuery in Stylus Studio

Itself. That is, the document represented by structure displayed on the Mapper tab and
the XML instance are one in the same. In this situation, Stylus Studio generates the
doc() function in the XQuery code. For example:

for $book in doc("file://c:\Program Files\Stylus Studio\examples\

simpleMappings\catalog.xml")/books/book

The XML document specified in the optional XQuery scenario. Only one source
document can be associated with the XQuery scenario. In this situation, Stylus Studio
does not generate the doc() function in the XQuery code. For example:
for $book in /books/book

The doc() function is not necessary because Stylus Studio uses the XQuery input
document specified in the Scenario Properties dialog box.
By default, Stylus Studio uses the first XML document you add to the XQuery mapper
as the source XML for the XQuery scenario, as shown here:

Figure 331. Default Source Document

The document specified in the Source XML URL field on the Scenario Properties
dialog box is the document used to preview XQuery results. You can select this
association for another XML document if you choose, but only one source document
may have this association.
Note

816

Creating a scenario for an XQuery is optional. See Creating an XQuery Scenario.

Stylus Studio User Guide

Building an XQuery Using the Mapper

Some other XML instance. A XSD or DTD document used as an XQuery source
document must always be associated with an XML instance. In this situation, Stylus
Studio generates the doc() function in the XQuery code.

Source icons
Stylus Studio uses different icons to indicate how a source is associated with the other
sources used to compose the XQuery.
Table 103. Source Document Icons
Icon

Meaning
The source document is associated with itself. This is the default for
most XML documents (and XML documents only).
The source document is associated with the XML document
specified in the XQuery scenario. This is the case with the first XML
document you add to XQuery mapper, but you can change this
association manually if you choose. See How to Change a Source
Document Association.
The source document is associated with a separate XML document
instance. XSD and DTD source documents are always associated
with an XML instance.
The source is a relational database table. A relational data source can
only be associated with itself.

How to Add a Source Document

This procedure describes how to add an XML document, an XML Schema, or a DTD as
a data source. To learn how to add a relational database table as a data source, see
Working with Relational Data Sources on page 850.
To add an XQuery source document to XQuery mapper:
1.

Click the Mapper tab if necessary.

Click the Add Source Document button at the top left of the Mapper tab.
The Open dialog box appears.

Select the document you want to use as the source document for building the XQuery.

Stylus Studio User Guide

817

Working with XQuery in Stylus Studio

Figure 332. Choose Root Element Dialog Box

You use this dialog box to associate the XSD or DTD with an XML instance.
The Associate With field appears only when you add a second document to the
XQuery mapper source and that document is an XSD or DTD. You use it to specify
the XML instance that you want to associate with the XSD or DTD. This field does
not appear if the XSD or DTD is the first source document you add to the XQuery
mapper Stylus Studio uses the XML Source document specified in the Scenario
Properties dialog box as the XML instance in this case.

Note

818

Select the element from the XSD or DTD document that you want to use as the
root element. The Choose root element drop-down list displays elements defined
in the document you selected in Step 3.

Use the Browse (

) button to specify the XML instance to which you want to
map the root element you have selected. The root element of the XML document
you select must be the same as the element you selected as the root element from
the XSD or DTD document.

Click OK.
The document appears in the source document pane of the Mapper tab. Go to
Step 5.

To add another source document, return to Step 2.

Stylus Studio User Guide

Building an XQuery Using the Mapper

How to Change a Source Document Association

To change a source document association:
1.

Right click the source document whose association you want to change.
The source document shortcut menu appears.

Click Associate With, and then select the document you want to associate with the
source document.

How to Remove a Source Document

Note A source document cannot be removed from XQuery mapper if it is mapped to the target

structure. See Removing Source-Target Map.

To remove a source document from XQuery:
1.

Remove any maps from the source document to the target schema. (See Removing
Source-Target Map if you need help with this step.)

Right click on the source document.

The source document shortcut menu appears.

Select Remove Schema.

How Source Documents are Displayed

A source document is represented using a page icon, and its name is displayed using a
different color to help distinguish it from element and attribute names. The page icon is
modified based on the source documents association with other documents. See Source
Documents and XML Instances for more information on this topic.

Stylus Studio User Guide

819

Working with XQuery in Stylus Studio

By default, only the file name itself is displayed; if you want, you can display the
documents full path by selecting Show Full Path on the documents shortcut menu.
(Right-click on the document name to display the shortcut menu.)

Figure 333. Source Document Display

Source documents are displayed using the tree view; you can use your keyboards *, +,
and - number pad keys to expand and collapse selected documents.

Document structure symbols

Stylus Studio uses the following symbols to represent nodes in both source and target
document structures:
Table 104. Document Structure Symbols
Symbol

Meaning
Repeating element
Element
Attribute

See Source icons to learn about the different ways source document icons are depicted.
Tip If a node is required by the XML Schema or DTD associated with the target document,

a red check appears over the node symbol.

Getting source document details

If you want details about the document that are not available in tree view, you can open
the document by selecting Open from the documents shortcut menu. When you open a
document this way, Stylus Studio displays it in its own editor (the XML editor if it is an
XML document, for example).

820

Stylus Studio User Guide

Building an XQuery Using the Mapper

Specifying a Target Structure

There are two ways to specify an XQuery target structure:

You can select an existing document from which Stylus Studio infers a structure and,
optionally, modify the structure. Existing nodes in a target structure are displayed in
blue. Nodes that you add are displayed in red. If a node is required by the associated
XML Schema or DTD, a red check appears over the node symbol.

Using an Existing Document

Building a Target Structure

See Modifying the Target Structure to learn about the types of changes you can make to
a target structure.

Using an Existing Document

To use an existing document to provide the XQuery target structure:
1.

Click the Mapper tab if necessary.

Click the Set Target Document button at the top left of the Mapper tab.
The Open dialog box appears.

Select the document you want to use to provide the target structure for defining the
XQuery.

Click Open.
The structure of the document you select appears in the target document pane of the
Mapper tab.

Building a Target Structure

To build a target structure from scratch, you first create a root element, and then define
child elements and attributes as needed.

Stylus Studio User Guide

821

Working with XQuery in Stylus Studio

How to create a root element

To create a root element:
1.

Click the Mapper tab if necessary.

Right click the area underneath the Set Target Document button.
The target document shortcut menu appears.

Select Create Root Element.

The Name dialog box appears.

Figure 334. Name Dialog Box

Type a name for the root element and click OK.

The root element you specified appears in the target document pane of the Mapper tab.
You can create elements and attributes in a new or existing target structure.

Note

How to create elements and attributes

To create elements and attributes:

822

Click the Mapper tab if necessary.

Select the attribute or element to which you want to add a child element or attribute.
If you have just created a root element, select the root element.

Right click the area underneath the Set Target Document button.
The target document shortcut menu appears.

Choose one of the following:

Add Attribute

Add Child Element

Insert Element After (This choice is not applicable to the root element; it creates
the element as a sibling of the selected element.)

Stylus Studio User Guide

Building an XQuery Using the Mapper

The Name dialog box appears.

Figure 335. Name Dialog Box

Type a name for the node and click OK.

The node you specified is added to the target structure in the Mapper tab.

Modifying the Target Structure

This section describes the techniques you can use to modify the structure and content of
an XQuery mapper target structure. It covers the following topics:

Adding a Node

Removing a Node

Setting a Text Value

Adding a Node
See How to create elements and attributes.

Removing a Node
Note Before you can remove a node, you must delete any links to that node. See Removing

Source-Target Map.
To remove a node from the target structure:
1.

Remove any links to the node you want to remove from the target structure. See
Removing Source-Target Map if you need help with this step.

Select the node and press the Delete key.

Alternative: Right-click the node and select Remove Node from the shortcut menu.

Stylus Studio User Guide

823

Working with XQuery in Stylus Studio

Setting a Text Value

You can set text values for target structure elements and attributes. You might want to do
this if you are composing an XQuery with an element or attribute that requires a fixed
value, instead of using a value gathered from an input XML document.
Here is the XQuery code Stylus Studio generates for the Title element when a text value
is specified for it:
<Book>
<Title>Confederacy of Dunces</Title>
</Book>

Stylus Studio displays a red letter T for nodes for which you define a text value:

To set a text value for a target structure node:

Right-click the node for which you want to set the text value.
The shortcut menu appears.

Select Set Text Value from the shortcut menu.

The Value dialog box appears.

Figure 336. Value Dialog Box

Type the string you want to use as the text value and click OK.

Mapping Source and Target Document Nodes

You map a source document node to a target structure node using drag and drop to create
a link between the two nodes. Stylus Studio composes XQuery code based on these maps.
This section covers the following topics:

Preserving Mapper Layout

Left and Right Mouse Buttons Explained

How to Map Nodes

Link Lines Explained

824

Stylus Studio User Guide

Building an XQuery Using the Mapper

Removing Source-Target Map

Preserving Mapper Layout

As you add function blocks to the XQuery mapper, Stylus Studio places them in the center
of the mapper canvas. You can change the default placement of function blocks by
dragging and drag and dropping them where you like. Stylus Studio preserves the
placement you select within and across sessions (as you toggle between the mapper and
the XQuery Source tab, for example).
As you use the splitter in the XQuery mapper to widen the source and target document
panes, the size of the mapper canvas is reduced. The Fit in Mapper Canvas button (
),
located at the top of the XQuery mapper, redraws the diagram in whatever space is
currently available to the mapper canvas. This feature is also available from the mapper
short-cut menu (right-click anywhere on the mapper canvas to display the short-cut
menu).
Tip You can also show links for visible nodes, or links for just the node you select. See

Simplifying the Mapper Canvas Display.

Left and Right Mouse Buttons Explained

You can use either the left or the right mouse button to perform the drag and drop
operation used to create source-target mappings in XQuery.
If you use the left mouse button to perform the drag operation, the link always maps the
source node to the target node, one-to-one, without making any changes to the target
structure.

Stylus Studio User Guide

825

Working with XQuery in Stylus Studio

If you use the right mouse button, Stylus Studio displays a shortcut menu that provides
you with alternatives for modifying the target structure.

Figure 337. Linking Using the Right Mouse Button Displays a Shortcut Menu

Using this menu, you can easily perform many operations. For example, you can

Map a source document node to an existing target structure node this menu choice,
Map to This Node, is the same as creating the link using the left mouse button.

Add a source document node (element or attribute) as an attribute of the target

structure node you select and map the two nodes.

Add a source document node as a child element of the target structure node you select
and map the two nodes.

Add a source document node as a sibling of the target structure node you select and
map the two nodes.

Copy the entire source document node its structure and its content to the target
structure and map it.

How to Map Nodes

To map nodes:

826

Using either the left or right mouse button, drag the source document element or
attribute to the appropriate node on the target structure.

When the pointer is on the appropriate target element, release the mouse button to
complete the link.

Stylus Studio User Guide

Building an XQuery Using the Mapper

Link Lines Explained

Stylus Studio draws lines for the maps you create from source document nodes to target
structure nodes. Different line styles are used to convey information about the XQuery
represented by the node mapping. There are three line styles:

Thin

Dashed

Thick
The sample files used to illustrate these styles are books.xml and catalog.xml, from the
Stylus Studio examples\simpleMappings directory.
Thin line
A thin line indicates that the XQuery code generated by Stylus Studio copies content from
the source node to the target node. Such a line is created when you map one element or
attribute to another using the left mouse button, or any of the following choices on the map
shortcut menu:

Create Root Element and Map It

Add Attribute and Map It

Add Child Element and Map It

Insert Element After and Map It

In addition, the structure required to navigate to the node is also generated if it does not
already exist in the XQuery. For example, consider the map between the title element in
books.xml and the Title element in catalog.xml:

Figure 338. Thin Lines in XQuery Mapper

Stylus Studio User Guide

827

Working with XQuery in Stylus Studio

This map results in Stylus Studio composing the following XQuery code:
<Catalog>
<Book>
<Title>
{/books/book/title/text()}
</Title>
</Book>
</Catalog>

The content is expressed as {/books/book/title/text(), and this statement is preceded by

the structure needed to locate the title element content.
Dashed line
A dashed line indicates that only structure code is being generated. Such a line is created
when you use a FLWOR or IF block. For example, consider the map between the book and
Book repeating elements:

Figure 339. Dashed Lines in XQuery Mapper

A map involving a FLWOR block results in the following code:

<Catalog>
{
for $book in /books/book
return
<Book>
<Title/>
</Book>
}
</Catalog>

828

Stylus Studio User Guide

Building an XQuery Using the Mapper

Notice that the FOR loop returns only structure (shown in italics), not content. To add
content, we could also map the title element to the Title element, which results in the
following:
<Catalog>
{
for $book in /books/book
return
<Book>
<Title>
{$book/title/text()}
</Title>
</Book>
}
</Catalog>

Of course, the FLWOR block can be used to define much more complex expressions,
involving maps from source document nodes to its WHERE and ORDER BY ports, for
example.
Thick line
A thick line indicates that the XQuery code generated by Stylus Studio replicates the
complete structure and content of the source document node in the target. Such a map is
created when you use the Copy Node choice on the link shortcut menu. Consider the
following map the bookid attribute on the source was copied to the target as a child of
the Book repeating element:

Figure 340. Thick Lines in XQuery Mapper

Stylus Studio User Guide

829

Working with XQuery in Stylus Studio

For this type of map, Stylus Studio creates the XQuery code required to duplicate the
source structure and content in the target, as shown in the following sample:
<Catalog>
<Book>
{/books/book/@bookid}</Book>
</Catalog>

Notice that the bookid attribute is displayed in gray in the target structure pane. This
indicates that you cannot edit it.

Removing Source-Target Map

To remove a map from a source document node to a target element node:
1.

Select the line that represents the map you want to delete.
Select the portion of the line that is drawn on the XQuery mapper canvas.

Note
2.

Press the Delete key.

Alternative: Select Delete from the line shortcut menu (right click on the line to
display the shortcut menu).

Simplifying the Mapper Canvas Display

By default, the XQuery Mapper displays all links between source and target document
nodes, regardless of whether or not the node associated with a link is currently visible in
the Source Document or Target Document pane. Further, as your XQuery code becomes
more complex, the mapper canvas can become dense with graphical representations of the
functions defined in the code and the links that represent them. Consider this example of

830

Stylus Studio User Guide

Building an XQuery Using the Mapper

XML-Q4.xquery, one of the sample XQuery files in the Examples project installed with

Stylus Studio.

Figure 341. Mapper Shows Links to All Nodes, Visible or Not

You can hide links for nodes that are not currently visible in the Source Document or
Target Document pane by clicking the Hide Links for Nodes that are not Visible button,
as shown in Figure 342:

Figure 342. Simply the Mapper by Hiding Links

When you use this feature, Stylus Studio displays

Links in the Mapper canvas only if both nodes are currently visible in the document
panes

Stylus Studio User Guide

831

Working with XQuery in Stylus Studio

Green arrows (like the ones shown in Figure 343) in the document panes if only one
of two linked nodes is currently visible.

Figure 343. Arrows Identify Partially Available Links

Other Mapper Display Features

In addition to displaying links for only those nodes that are visible in both document
panes, you can use the document node shortcut menu (right-click on a node in a document
pane) to

Show links to a specific node

Hide links to a specific node

Show/hide all links

Exporting Mappings
You can export a mapping source and target document trees and Mapper canvas contents
as an image file. The default image format is JPEG (.jpg), but you can choose from
other popular image file formats such as .bmp and .tiff.
The exported image reflects the document trees at the time you export the image if you
have collapsed a node in Stylus Studio, for example, that node is also collapsed in the
exported image. However, the exported image includes the entire document tree and
Mapper canvas, not just what is currently visible on the Mapper tab.
By default, all source-target document links are displayed. However, if you have chosen
to hide or show links for only certain nodes, the exported image reflects that choice and
displays only the links for the nodes as you have specified. See Simplifying the Mapper
Canvas Display on page 830 for more information on hiding and showing links.

832

Stylus Studio User Guide

Building an XQuery Using the Mapper

To export an XQuery mapping:
1.

Optionally, hide links for any nodes in the source or target documents that you do not
want to appear in the exported image.

Select XQuery > Export Mapping as Image from the Stylus Studio menu.
Stylus Studio displays the Save As dialog box.

Specify a URL for the file.

Optionally, change the image type. (The default is JPEG; .bmp and .tiff are also
available.)

Click Save.

Searching Document Panes

You can search document panes using the Find dialog box.

Figure 344. You Can Search Document Panes

You can restrict your search to elements and/or attributes, and you can even search using
regular expressions to define your match pattern.
To display the Find dialog box:
1.

Right-click in the document pane.

Select Find from the shortcut menu.

FLWOR Blocks
This section describes how to work with FLWOR blocks in the XQuery Mapper tab. It
covers the following topics:

Parts of a FLWOR Block

Creating a FLWOR Block

Stylus Studio User Guide

833

Working with XQuery in Stylus Studio

Parts of a FLWOR Block

FLWOR blocks are drawn as a green block with an illustration of a flower at its center,
and five connectors, called ports, placed along the blocks border:

Figure 345. FLWOR Block

For, Order by, and Return ports

You define a FLWOR statements For and Order by clauses by mapping source document
elements and attributes to them, as appropriate. For example, if you wanted your XQuery
to return a list of books ordered by publication date, you would map the book repeating
element in books.xml to the FLWOR blocks For port, and the Return port to the Book
repeating element in catalog.xml. (As an alternative, you could map the two repeating
elements directly, and Stylus Studio would create the FLWOR block and this mapping for
you automatically, as described in Creating a FLWOR Block). Next, you would map the
source document pubdate attribute to the Order by port. For a FLWOR block defined in
this way, Stylus Studio generates the following XQuery:
<Catalog>
{
for $book in /books/book
order by $book/@pubdate
return
<Book/>
}
</Catalog>

Where port
The input for the Where port must be the output port of another block, such as a condition,
IF, or function block. Imagine you have two source documents you can create an Equal
condition block, and specify that the content of an element in one source document must
match the content of an element in the other source document, and map the return value
834

Stylus Studio User Guide

Building an XQuery Using the Mapper

of this condition to the Where port on the FLWOR block. Creating an Equal condition that
specifies that the bookid attribute must be equal to the title element results in Stylus
Studio generating the following XQuery code, for example:
<Catalog>
{
for $book in /books/book
where $book/@bookid = $book/title
order by $book/@pubdate
return
<Book/>
}
</Catalog>

See IF Blocks and Function Blocks for information on using other types of blocks in
XQuery mapper.
Flow port
The Flow port, which is also present on IF and function blocks, allows you to link the
result from other FLWOR, IF, and function blocks to define a conditional execution order
for your XQuery expressions. You might decide you want a particular For each statement
executed only after performing a certain function, for example. Inputs for the Flow port
include the Return port of IF, function, and other FLWOR blocks.

Creating a FLWOR Block

You can create FLWOR blocks in the XQuery Mapper tab in one of two ways:

Right-click on the mapper canvas and select New | FLWOR Block from the shortcut
menu.

Map one repeating element to another Stylus Studio automatically creates a

FLWOR block, mapping the source document node to the For port, and the Return
port to the target structure node. Consider this code, which Stylus Studio generated
after mapping the book repeating element in books.xml to the Book repeating element
in catalog.xml:
<Catalog>
{
for $book in /books/book
return
<Book/>
}
</Catalog>

Stylus Studio User Guide

835

Working with XQuery in Stylus Studio

Function Blocks
Stylus Studio supports standard functions defined by the W3C and any user-defined
functions you might have created. This section describes how to work with function
blocks in Stylus Studio and covers the following topics:

Standard Function Block Types

Creating a Function Block

Parts of a Function Block

User-Defined Functions

concat Function Blocks

See Using Web Services in XQuery on page 921 to learn about the wscall function.

Standard Function Block Types

Stylus Studio provides graphic support for the following types of XQuery functions:

anyURI

Accessor

Aggregate

Boolean

Context

DataDirect XQuery

Date/time, duration

Error

Node

Numeric values

QName

Sequence

Sequence generator

Special constructor

String

Trace
If a standard function does not provide the functionality you need, create a user-defined
function. See User-Defined Functions.

836

Stylus Studio User Guide

Building an XQuery Using the Mapper

Creating a Function Block

The procedure for creating standard and user-defined function blocks varies slightly:
To create a standard function block:
1.

Right-click on the mapper canvas.

Select New > Function Block from the shortcut menu. Available functions are
displayed in submenu categories.

To create a user-defined function block:

Right-click on the mapper canvas.

Select New > User Functions from the shortcut menu.

Any user-defined functions defined in the XQuery source are displayed in a sublist.
See User-Defined Functions to learn more about creating user-defined functions in
Stylus Studio.

Parts of a Function Block

Function blocks are drawn as a purple block with an italic f at its center, and connectors,
called ports, placed along the blocks border. Input ports (none or more based on the
function), the Flow port at the top, and the Return port on the right:

Figure 346. Function Block

Input ports
Input ports are on the left side of the function block. The number and definition of input
ports varies from function to function. To specify a value for an input port, drag a source
document element or attribute to the port and release it.
Flow port
Flow ports, on the top of function blocks, are the same for FLWOR, function, and IF
blocks. See Flow port.

Stylus Studio User Guide

837

Working with XQuery in Stylus Studio

Return port
The Return port is on the right side of the function block. You use the Return port to map
the function result directly to a target structure element or attribute, or to a FLWOR, IF,
condition, or another function block.

User-Defined Functions
You can declare your own functions in XQuery. Such functions are referred to as userdefined functions. For more information, see User-Defined Functions on page 844.

concat Function Blocks

There are three types of concatenation (concat) functions for strings:

concat() as string allows you to specify a literal value that you might wish to
concatenate to some other value in your XQuery.

Figure 347. concat() as string

concat($op1 as string?) as string allows

you to specify a variable that you might

wish to concatenate to some other value.

Figure 348. concatn($op1 as string?)

concat($op1 as string?, $op2 as string?, ...) as string allows

you to

concatenate two or more variables.

Figure 349. concat($op1 as string?, $op2 as string?, ...)

Note that only the first two input ports are associated with variables ($op1 as string?
and $op2 as string?). When you map a value to the third input port (...), Stylus
Studio automatically adds a fourth input port to allow you concatenate a fourth value.
This behavior is repeated for each additional string you define.

838

Stylus Studio User Guide

Building an XQuery Using the Mapper

IF Blocks
IF blocks have a single input port, labeled condition; a Flow port; and two result ports: if
then, and if else.

Figure 350. IF Block

You use IF blocks to compose if

then, else XQuery

expressions, such as the following:

<Book>
{
if( $book/title ) then
<Title/>
else
<ISBN/>
}
</Book>

This expression, for example, was composed by mapping

The title element in the source document to the IF blocks input port.

The if then result port to the Title element in the target structure.

The if else result port to the ISBN element in the target structure.
IF blocks create a structure if the if then or if else branches are true. These ports can
be connected to the target schema; otherwise they can be connected to Flow ports of
FLWOR, function, and other IF blocks.

Condition Blocks
The Stylus Studio XQuery mapper allows you to graphically define the following types
of conditions:

Equal (=)

Less than (<)

Stylus Studio User Guide

839

Working with XQuery in Stylus Studio

Greater than (>)

Less than or equal to (<=)
Greater than or equal to (>=)
and (&)
or (||)

All condition blocks have two input ports and a single Return port, as shown in this
example of a greater than block.

Figure 351. Greater Than Block

You can map the Return port to a target structure element or attribute, or to the input port
on a FLWOR, function, IF, or another condition block.

Predicate Blocks
A predicate allows you to filter data returned from an XQuery. For example, in books.xml,
you might want to return only those books whose bookid attribute was within a specified
range of values. In Stylus Studio, you can display (and create) predicates as predicate
blocks in XQuery Mapper.
A predicate block in XQuery Mapper is rendered as a pair of binoculars. It has two input
ports Context (shown as data in the predicate blocks tool tip) and Expression and a
single Return port, as shown in this example of a greater than block.

Figure 352. Predicate Block

Enabling Predicate Blocks

You can create predicates in the XQuery source at any time, but if you want them
displayed in the Mapper canvas and/or you want to be able to create them graphically, you
need to first enable them.

840

Stylus Studio User Guide

Building an XQuery Using the Mapper

To enable predicate blocks:
1.

Select Tools > Options from the Stylus Studio menu.

Navigate to Module Settings > XQuery > Mapper.

Select the Display predicates in XPath expressions in the canvas option.

Predicates will be displayed in the next XQuery file you open in Stylus Studio.

Creating a Predicate Block

To create a predicate block:
1.

Ensure that predicates have been enabled in Stylus Studio. See Enabling Predicate
Blocks on page 840 if you need help with this step.

Open an XQuery file.

Click the Mapper tab.

Right-click the Mapper canvas.

Select Conditional Block > XPath predicate.

Example
Following is a simple example that selects all books books.xml whose bookid attribute
equals 2. This example uses the books.xml and catalog.xml files in the simpleMappings
folder in the examples project.
1.

Ensure that predicates have been enabled in Stylus Studio. See Enabling Predicate
Blocks on page 840 if you need help with this step.

Open an XQuery file.

Click the Mapper tab.

Drag and drop books.xml to the Add Source Document pane, and drag and drop
catalog.xml to the Set Target Document pane.

Drag title to Title.

Right-click the Mapper canvas and select Conditional Block > XPath predicate.
The predicate block appears on the Mapper canvas.

Stylus Studio User Guide

841

Working with XQuery in Stylus Studio

Since we want to look for all book elements, drag book to the predicate blocks Context
port.
Next, we use the conditional block to create predicate expression (that is, only those
book elements whose bookid attribute equals 2).

Right-click the Mapper canvas and select Conditional Block > =.

The equal block appears on the Mapper canvas.

Drag bookid to the first input port on the equal block.

10.

Double-click the second port on the equal block and specify 2 for the value.

11.

Drag the output port on the equal block to the expression port on the predicate block.

12.

Finally, drag the output port on the predicate block to the control port on the link
connecting title to Title.
At this point, your diagram should look something like this.

Figure 353. Predicate Block Defined in XQuery Mapper

As you can see, Stylus Studio created the predicate, [./@bookid = 2], as part of the
XPath expression used to query books.xml. (Note that we defined the document using
the variable $a to simplify the XPath expression.)
842

Stylus Studio User Guide

Building an XQuery Using the Mapper

13.

Preview the XQuery by clicking the Preview Result button (

The result appears in the Preview window:

Figure 354. Predicate Result

SQL Function Blocks

A SQL function block is used to represent one of three DataDirect XQuery built-in
functions that can be used to update relational data bases. Supported SQL statements and
the SQL function blocks used to represent them are shown in the following table.
Table 105. SQL Block Symbols
SQL Statement

SQL Block Symbol

INSERT
UPDATE
DELETE

For more information about using SQL blocks to create XQuery code, see Updating
Relational Databases on page 866.

Stylus Studio User Guide

843

Working with XQuery in Stylus Studio

User-Defined Functions
A user-defined function is an XQuery function that you define. Consider the following
example, which illustrates the total-price user-defined function:
declare function total-price( $i as element) as xs:decimal
{
let $subtotals := for $s in $i return $s/quantity * $s/USPrice
return sum( $subtotals )
};

The total-price user-defined function takes an inventory element as its argument and
returns a sum reflecting the dollar value of that inventory (quantity * price). Here is an
example of how it might be used (the user-defined function is shown in italics):
<Catalog>
{
for $book in /books/book
return
<Book>
<Price>
{total-price($book/@bookid)}
</Price>
</Book>
}
</Catalog>

When you create a user-defined function, Stylus Studio adds it to the New > User
Functions shortcut menu available when you right-click the mapper canvas.

Figure 355. User-Defined Functions

This makes it easy to reuse a user-defined function on the Mapper tab once it has been
defined in the XQuery source. See Building an XQuery Using the Mapper on page 813
for more information.
Another way to use user-defined functions is to include them in a library module. You can
then import this library module into other XQuery instead of rewriting the user-defined

844

Stylus Studio User Guide

User-Defined Functions

function each time you need it. See Working with XQuery Library Modules on
page 882

Creating a User-Defined Function

You can create a user-defined function by typing its definition in the XQuery Source tab,
but it can be easier to have Stylus Studio create a user-defined function for you. You do
this by selecting existing code and refactoring that code as a user-defined function. Any
complete block of code can be used for refactoring. Examples include XML fragments
and FLWOR expressions.
When you create a user-defined function using the refactoring feature, Stylus Studio

Creates a function declaration for the newly created user-defined function

Replaces the code you selected with a function call to the user-defined function
To create a user-defined function:
1.

In the XQuery Source tab or the Text pane of the XQuery Mapper tab, select the
fragment you want to use to create your user-defined function.

Stylus Studio User Guide

845

Working with XQuery in Stylus Studio

Consider the following example, which uses the createFullOrder.xquery that is part
of the pipelines example project installed with Stylus Studio.

Figure 356. Creating a User-Defined Function

Drag select the code you want to use to create the user-defined function.

Right-click to display the short-cut menu and choose Refactor as Function:

Figure 357. Refactoring Code as a User-Defined Function

846

Stylus Studio User Guide

User-Defined Functions

Stylus Studio displays the New Function dialog box.

Figure 358. New Function Dialog Box

A default name, udFunctionN, where ud stands for user-defined and N is a unique

number, appears in the Enter the name for the new function field.
4.

Click OK to use the default name, or type any valid name you choose and then click
OK.
The function declaration and a call to that function are added to your XQuery code.
For example:

Figure 359. Function Declaration for User-Defined Function

Stylus Studio User Guide

847

Working with XQuery in Stylus Studio

Working with User-Defined Functions

The Stylus Studio XQuery Editor provides several useful tools to help you work with
user-defined functions in your XQuery code.

Find all uses

Go to definition

Rename
Tip You can use all of these tools for variables defined in your XQuery code.

Finding Uses of a User-Defined Function

To identify all uses of a user-defined function:

848

Place the pointer on the user-defined function declaration.

Right-click the function declaration.

Choose Find Function Use from the short-cut menu.

Stylus Studio User Guide

User-Defined Functions

Stylus Studio displays a teal bookmark adjacent to each occurrence of the user-defined
function, including the line on which the user-defined function is declared.

Figure 360. Finding All Uses of a User-Defined Function

Locating a User-Defined Function Declaration

To locate a user-defined function declaration:
1.

Place the pointer on an occurrence of the user-defined function.

Right-click.

Choose Go to Function Definition from the short-cut menu.

Stylus Studio moves the focus to the function declaration and displays the function
name in reverse video.

Renaming a User-Defined Function

When you rename a user-defined function, the name is changed throughout the current
XQuery.

Stylus Studio User Guide

849

Working with XQuery in Stylus Studio

To rename a user-defined function:
1.

Place the pointer on any instance of the user-defined function name.

Right-click.

Choose Rename from the short-cut menu.

Stylus Studio displays the Rename dialog box.

Figure 361. Renaming a User-Defined Function

The current name appears by default.

Enter a new name and click OK.

The user-defined functions name is changed throughout the XQuery.

Working with Relational Data Sources

Support for the XQuery collection() function is available only in Stylus Studio XML
Enterprise Suite.
As implemented in Stylus Studio, the XQuery collection() function allows you to
include relational database tables and views in your XQuery as if they were XML
documents. (The collection() function is implementation-specific different vendors
have implemented it in different ways. In some implementations, for example, the
collection() function takes as its argument a URL that specifies an XML document.)
This section describes how to work with the collection() function in Stylus Studio.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XQuery Collections video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

Using the collection() Function in Stylus Studio on page 851

850

Stylus Studio User Guide

Working with Relational Data Sources

How the collection() Function is Processed on page 851

Creating a Database Connection on page 852
Creating a collection() Statement on page 857
Updating Relational Databases on page 866
Other Ways to Register a Database Configuration on page 861

Using the collection() Function in Stylus Studio

The process of using the collection() function in Stylus Studio consists of these basic
steps:
1.

Create a connection to the database server whose tables and/or views you want to
query. You create database connections from the File Explorer window.

Register the database connection with your XQuery file. This process allows the
databases tables and views to be used in your XQuery code.

Invoke the collection() function in your XQuery code. You can type the
collection() statement by hand, or have Stylus Studio create it for you.

Ensure that the processor specified in the XQuery scenario is the DataDirect
XQuery processor.

These steps are described in greater detail later in this section.

How the collection() Function is Processed

The DataDirect XQuery processor converts the XQuery code to SQL statements and
pushes the SQL directly to the database server. Results are returned to Stylus Studio as
XML and displayed in the Preview window.
Because it processes XQuery as SQL on the database server, the DataDirect XQuery
processor can provide performance superior to that of other XQuery processors when
querying relational data as XML.

Database Connections
The database connection is established when the XQuery code is executed and closed as
soon as a result is returned. Connection settings used are those associated with the data
source used to create the XQuery. See Creating a Database Connection on page 852 for
more information on this topic.

Stylus Studio User Guide

851

Working with XQuery in Stylus Studio

Handling Invalid Characters

Some characters, like spaces, are valid in SQL but are invalid in XML. Invalid characters
are escaped using SQL/XML escaping convention when the relational data is converted
to XML. For example, Stylus Studio would create an XML tag for a column named last
name as last_x0020_name.

Creating a Database Connection

Before you can execute a collection() function in an XQuery, you need to create a
database connection. This is part of the process of making the database tables and views
available to your XQuery code.
This section covers the following topics:

Supported Databases

The Connection Settings Dialog Box

Using the Server URL Field

How to Create a Database Connection

Supported Databases
Stylus Studio provides support for the following relational databases:

IBM DB2

Informix

Microsoft SQL Server

MySQL

Oracle

PostgreSQL

Sybase
For specific version support, see
http://www.datadirect.com/products/xquery/matrix/ddxquery.htm.

Drivers for most of these databases are bundled with Stylus Studio. For some, like
PostgreSQL, for example, you need to specify the classpath for the database driver.

852

Stylus Studio User Guide

Working with Relational Data Sources

The Connection Settings Dialog Box

In Stylus Studio, you use the Connection Settings dialog box to specify database
connection properties.

Figure 362. Connection Settings Dialog Box

Settings vary from database to database, but they typically include the following:

You use the Database Type field to specify the database to which you want to connect.
See Supported Databases for a complete list.

If you are using the PostgreSQL databases, you need to specify the location of the
JDBC driver for that database in the Driver Classpath field. (Drivers for other
relational databases are bundled with Stylus Studio.)

The server URL and other connection parameters. In addition to the servers location,
connection parameters can include the server name, the port through which the
connection is established, and other information, such as a server ID (SID). See Using
the Server URL Field for more information.

You use the Username and Password fields to specify the database user you want to
associate with this data source.

Using the Server URL Field

You use the Server URL field to identify the server hosting the database to which you want
to connect, the port to use, and any other required or optional parameters. For example,
the string used to connect to a Microsoft SQL Server database might look like this:
//invanuccio:1521;DataBaseName=pubs

Server address

Stylus Studio User Guide

Port

Database name

853

Working with XQuery in Stylus Studio

The specific syntax of the string you enter in the Server URL field varies based on
database type. Consult your database documentation for information regarding
connectivity syntax and optional parameters.
Tip Stylus Studio populates the Server URL field with a default string appropriate for the
database you specify in the Database Type field.

How to Create a Database Connection

To create a database connection:
1.

Display the File Explorer window if it is not already open (View > File Explorer).

In the File Explorer window, right-click the RelationalDB icon and select New Server
from the short-cut menu.
Stylus Studio displays the Connection Settings dialog box.

Figure 363. Connection Settings Dialog Box

854

Specify the information needed to create the database connection. See The
Connection Settings Dialog Box if you need help with this step.

Did you select a database in the Database Type field for which you must specify a
driver?
If yes, go to Step 5.
If no, go to Step 6.

When you select a database in the Database Type field for which you must specify a
driver, the Driver Classpath field becomes enabled. To specify the driver location:

Stylus Studio User Guide

Working with Relational Data Sources

Click the more button ( ).

The Set Classpath for the JDBC Driver dialog box appears.

Figure 364. Set Classpath for the JDBC Driver Dialog Box
b.

Click the browse folders (

) button.
A new entry field appears in the Locations list box. Two buttons appear to the
right of the entry field.

To add a JAR file to the classpath, click the browse jar files button (
Stylus Studio displays the Browse for Jar Files dialog box.

Figure 365. Browse for Jar Files Dialog Box

Stylus Studio User Guide

855

Working with XQuery in Stylus Studio

To add a folder to the classpath, click the browse folders button (

Stylus Studio displays the Browse for Folder dialog box.

Figure 366. Browse for Folder Dialog Box

When you have located the JAR file or folder you want to add to the classpath,
click OK.
The file appears in the Locations list box of the Set Classpath for the JDBC
Driver dialog box.

Click OK.
The JAR file or folder appears in the Driver Classpath field of the Connection
Settings dialog box.

Click OK on the Connection Settings dialog box.

The server connection appears in the File Explorer window.

Figure 367. New Database Server Connection

856

Stylus Studio User Guide

Working with Relational Data Sources

How to Edit a Database Connection

You can edit connection settings for an existing relational database connection.
To edit a database connection:
1.

Display the File Explorer window if it is not already open (View > File Explorer).

In the File Explorer window, right-click the server connection whose settings you
want to change and select Edit Server from the short-cut menu.
Stylus Studio displays the Connection Settings dialog box. The current connection
settings are displayed.

Make the changes you want and click OK.

Creating a collection() Statement

This topic describes how to create a collection() statement in your XQuery code
automatically. If you prefer, you can always write the collection() statement manually.
Regardless of how you input the collection() statement in your XQuery code, Stylus
Studio will be able to execute it only if you have created a database connection for the
database associated with the table or view referenced in the collection() function calls
and have registered that connection with the XQuery.

collection() Function Syntax

The collection() function takes as its argument a URI that identifies a specific database
table or view, such as this function referencing the title column of the books table in the
pubs2 database:
collection("pubs2.dbo.books")/books/title

You can always edit collection() functions created by Stylus Studio. As long as they
refer to an object that is available based on the database connection associated with the
XQuery, the collection() function will execute successfully. See Choosing a Database
Object on page 862 for more information on this topic.

Stylus Studio User Guide

857

Working with XQuery in Stylus Studio

What Happens When You Create a collection() Statement?

You create a collection() statement by selecting the table or view you want to query
from the File Explorer window, and dropping it on the editing pane of the XQuery Source
tab in the XQuery Editor. When you drop the table or view on the editing pane, Stylus
Studio

Automatically creates the collection() statement in the XQuery code based on the
table or view you selected

Registers with the XQuery the connection information for the database associated
with the selected table or view, and displays the database in the schema pane of the
XQuery Editor, as shown here:

Editing pane

Schema pane

Figure 368. collection() Statements are Created Automatically

Once the database connection information is registered with the XQuery, you can expand
the database nodes in the schema pane to display individual table and view columns.

858

Stylus Studio User Guide

Working with Relational Data Sources

Creating Multiple Connections

When you drop an object on the editing pane from the File Explorer window, Stylus
Studio displays the connection information in the schema pane of the XQuery Editor. If
you then drag and drop another object, Stylus Studio either

Adds a new connection, if the object was from a different server or port

Modifies the existing connection, if the object is from the same server and port
A new collection() statement is created for each object you drop on the editing pane of
the XQuery editor.

How to Create a collection() Statement

To create a collection() statement:
1.

Open a new XQuery if one is not already open. The XQuery Source tab should be
displayed.

Ensure that you have established a valid database connection as described in

Creating a Database Connection on page 852.

Stylus Studio User Guide

859

Working with XQuery in Stylus Studio

In the File Explorer window, expand the database and tablespace to display the tables
or views you want to access in your XQuery, as shown in this example:

Figure 369. Expanded Database Connection

Optionally, display table and view columns by selecting Read Structure from the
table or view shortcut menu (right-click).
4.

860

Drag the desired table or view and drop it on the editing pane of the XQuery Source
tab.
Optionally, drop the table or view on the schema pane of the XQuery Source tab. If
you do this, you must then drag the desired table or view from the schema pane to the
editing pane to create the collection() statement.
Stylus Studio creates the collection() statement based on the table or view you
selected in Step 4. It also displays the tables or views database in the schema pane
of the XQuery Editor (see Figure 368).

Stylus Studio User Guide

Working with Relational Data Sources

Other Ways to Register a Database Configuration

If you choose, you can explicitly register a database connection by dropping any elements
from a database connection displayed in the File Explorer window (the connection
representation, database, schema, table, or view) on the schema pane of the XQuery
Source tab. You might want to do this when you want to view a tables or views columns
prior to writing your XQuery code, so you can see what data structures are available, as
shown here:

Figure 370. Schema Pane Shows Table and View Columns

This also gives you the ability to close the File Explorer window after creating your
database connection providing more room to work, and simplifying the Stylus Studio
desktop display.
Tip You can also gain access to column-level information about a databases tables and views
directly from the File Explorer window by selecting Read Structure from the table or

view shortcut menu (right-click).

Stylus Studio User Guide

861

Working with XQuery in Stylus Studio

Choosing a Database Object

You can register a database connection by dragging any database object from the File
Explorer window. The object you select affects which objects you can then query in your
XQuery code:

Server all of the servers databases and their child tables and views can be queried

Database all of the databases tablespaces and their child tables and views can be
queried

Tablespace any of the tablespaces tables or views can be queried

Table/View only the table or view can be queried

Column only the column can be queried

Once you register a database connection to the XQuery, the configuration information
remains associated with the XQuery until you explicitly delete it from the schema pane in
the XQuery Editor.

Working with Zip Archive Format Files as Data Sources

Microsoft Office Open XML, OpenDocument Format, and .zip files can all be used as
data sources in XQuery Mapper. All of these documents are based on the Zip Archive
format. The process for using any of these document types as a source in XQuery Mapper
is the same as it is for, say, an XML document simply drag the Zip Archive formatted
document from a file system and drop it on the Add Source Document pane in XQuery
Mapper.

862

Stylus Studio User Guide

Working with Zip Archive Format Files as Data Sources

Example
Consider the books.xml file that is installed with the simpleMappings project installed
with Stylus Studio. This is what the books.xml file looks like when displayed using the
XML Editors Grid tab.

Figure 371. Grid View of books.xml

In this example, well use a zipped copy of books.xml, books.zip, as the source for a
simple XQuery that will return information for all books with some variant of begin in
their title.
We start by creating a new XQuery, which we save as zip_source.xquery. To start the
mapping process, we click the Mapper tab. Next, we can select the source and target
documents required for our XQuery.
When you click the Add Source Document button, Stylus Studio displays the Open
dialog box. You can use the Files of drop-down menu to filter the types of files. As you

Stylus Studio User Guide

863

Working with XQuery in Stylus Studio

can see, Stylus Studio supports numerous document types based on the Zip Archive
format.

Figure 372. Stylus Studio Supports Numerous Zip Archive File Formats

Well choose the books.zip file we created previously. (Of course, you can drag source
and target files from your file systems and drop them directly on the source and target
document panes.) Once the .zip file is added as a source, we can navigate it just as we
would any other XML file:

Figure 373. Zipped XML Is Accessed Just Like XML

Next, we add catalog.xml from the simpleMappings project as our target document.
864

Stylus Studio User Guide

Working with Zip Archive Format Files as Data Sources

Well use a FLWOR expression to iterate over the source XML. Mapping the contents of
a zipped XML file is just like mapping plain XML just expand the tree to locate the node
you want to map, drag, and drop. In this case, we drag the book repeating element from
the zipped books.xml and drop it on the Book repeating element in the target document.
Stylus Studio creates the FLWOR block automatically when mapping one repeating
element to another.
Next, we create a contains function to select only those books that have the string Begin
as part of their title. Right-click the mapper canvas and choose Function Block >
Functions on Strings > contains/2 from the short-cut menu. Stylus Studio adds the
contains function to the Mapper canvas. To specify the contains function, we map the
title element to the first input port on the contains function block ($arg1 as xs:string?).
To specify the partial string we want to search for, we double-click the second input port,
and enter Begin in the Value dialog box. When were done, we map the contains
function output port to the Where port on the FLWOR block.

Figure 374. Mapping Zipped Sources

Finally, we map the title element in the zipped source XML to the Title element in the
target XML. When we preview the XQuery, we can see that Stylus Studio was able to read

Stylus Studio User Guide

865

Working with XQuery in Stylus Studio

the zipped XML document and provide the titles for all the books that contain some
portion of the string Begin.

Figure 375. Finished XQuery Using Zipped Sources

Updating Relational Databases

In addition to using relational database tables as data sources in XQuery Mapper, you can
use the XQuery Mapper to create XQuery code that performs SQL INSERT, UPDATE,
and DELETE operations.
This section covers the following topics:

Overview on page 867

Using SQL Function Blocks in XQuery Mapper on page 867

Creating an Insert Function Call on page 869

Creating an Update Function Call on page 874

Creating a Delete Function Call on page 878

866

Stylus Studio User Guide

Updating Relational Databases

Overview
In XQuery Mapper, simple drag-and-drop techniques create calls to built-in DataDirect
XQuery functions ddtek:sql-insert, ddtek:sql-update, and ddtek:sql-delete that
perform update operations on relational databases. For example, this XQuery code, which
performs an INSERT operation on the Products table, was created with a few simple
mappings:
ddtek:sql-insert("sqlserver_pcipeduzz
:Northwind.dbo.Products",
"ProductName",$Products/ProductName,
"SupplierID",$Products/SupplierID,
"CategoryID",$Products/CategoryID)

Stylus Studio provides support for numerous relational databases, including Microsoft
SQL Server, Informix, and Oracle. For a complete list, see Supported Databases on
page 852.
For information on connecting to a relational database, see Creating a Database
Connection on page 852.

Using SQL Function Blocks in XQuery Mapper

When you create a call to a SQL update function using XQuery Mapper, a SQL function
block representing the function appears on the Mapper canvas. For example, consider the
SQL block created for a ddtek:sql-update function call on the Products table:

Figure 376. Update Function Block

The first port on the left is colored because it already has a value it is the table used to
create the SQL update block; "myServer:pubs.dbo.authors", for example. The other two
ports are column name/value pairs. They are empty because they do not contain values
when the function call is first created. You provide these values by mapping, or, in the case
of update functions, by explicitly providing a value for the port by double-clicking it.

Stylus Studio User Guide

867

Working with XQuery in Stylus Studio

To map column name/value pairs, you first expand the SQL function block by doubleclicking it. When you double-click a SQL function block, it expands to show the table
name and each of the columns that make up the table:

Figure 377. Expanded SQL Functions Block

Each column has an associated port. You use these ports to map nodes from XML data
sources in the Add Source Document pane. Always perform mapping operations using
the ports on the expanded SQL function block when you are building your XQuery using
the XQuery Mapper.
For a summary of SQL function blocks, see SQL Function Blocks on page 843.

About the Output Port

All function blocks in Stylus Studio have an output port on the right side. In most cases,
output from a function is mapped to either another function (a conditional expression, for
example) or to a node on the target document.
Unlike most other XQuery source-target mappings, SQL functions do not generate any
output any changes specified by the XQuery are performed directly on the database.
However, a link from the SQL function blocks output port to the Set Target Document
pane is required in order to commit the XQuery mapping to Stylus Studio. This link is
completed automatically for you by Stylus Studio when you create SQL insert and update
functions using drag and drop. If you create these functions using the short-cut menu
(right-click the Mapper canvas and select Function Block > DataDirect XQuery...), you
must create this link manually. The same is true for delete functions, which cannot be
created using drag-and-drop.
Further, nothing is displayed in the Output window when you preview the XQuery any
changes resulting from the XQuery are reflected directly in the database.

868

Stylus Studio User Guide

Updating Relational Databases

For general information on mapping, see Building an XQuery Using the Mapper on
page 813.

Creating an Insert Function Call

In Stylus Studio, you can create an insert function call using

Drag-and-drop

The short-cut menu on the Mapper canvas

When you use drag-and-drop, Stylus Studio creates the link from the insert function block
for you, which automatically commits the XQuery mapping to Stylus Studio.

How to Create an Insert Function Call

Use the following procedure to create an insert function call in XQuery Mapper. Note that
specifics will vary based on the requirements for your XQuery you might need to use
an equal condition instead of a greater-than condition to select records, for example.
To create an insert function call:
1.

Connect to the relational database that contains the table or tables you want to update.
See Creating a Database Connection on page 852 if you need help with this step.

In the File Explorer, expand the database tree to expose the table you want to update.

Drag the table from the File Explorer and drop it on the Mapper canvas.
A short-cut menu appears with two choices: Create SQL Insert Call and Create SQL
Update Call.

Select Create SQL Insert Call.

The function block for the ddtek:sql-insert call appears on the Mapper canvas.

Create a FLWOR block to loop over the database table. See Creating a FLWOR
Block on page 835 if you need help with this step.

Map the output of the FLWOR block to the flow port on the top of the function block.

Expand the function block by double-clicking it.

Map source document nodes to the corresponding input ports on the function block.

Save and preview the XQuery; check results on the database table you have updated.

Stylus Studio User Guide

869

Working with XQuery in Stylus Studio

Alternative:
1.

Right-click the Mapper canvas.

Select Function Block > DataDirect XQuery > sql-insert from the short-cut menu.
The insert function block appears on the Mapper canvas.

When you have finished defining the XQuery, map the insert function blocks output
port to the Set Target Document pane. Your XQuery mapping is not committed to
Stylus Studio until you complete this step.

Example
In this example, we use the SQL insert function call to add a new set of records to the
Products table.
In a new XQuery that we have saved as INSERT.xquery, we drag the Products table and
drop it on the XQuery Mapper canvas. After choosing Create SQL Insert Call from the
short-cut menu, the database table is automatically added as a source for the XQuery, and
that the outline for the DataDirect XQuery ddtek:sql-insert function is displayed in the
Mappers text pane:

Figure 378. Using a Relational Table to Create a SQL INSERT

870

Stylus Studio User Guide

Updating Relational Databases

Next, we create a FLWOR block (right-click on the Mapper canvas and select FLWOR
Block) to loop through all the records in the Products table. We use the Products repeating
element to specify the FLWOR blocks Where clause, and map its output to the flow port
on the SQL block. Again, notice that the XQuery code displayed in the text pane is
updated with the code for the FLWOR block:

Figure 379. FLWOR Block to Loop Through Database Table Records

Values for new records can come from existing records if they are mapped; otherwise,
they are created as empty records or use default values depending on how the database is
configured.
For this example, lets use existing values for the ProductName, SupplierID, and
CategoryID columns. In order to map these values, we first expand the SQL block created

Stylus Studio User Guide

871

Working with XQuery in Stylus Studio

for the Products table by double-clicking it, and then mapping the element names in the
Add Source Document pane to the corresponding ports on the SQL block:

Figure 380. Mapped Columns Use Existing Values for New Records

872

Stylus Studio User Guide

Updating Relational Databases

Before we preview the XQuery, lets take a look at the Products table on the database. If
we double click the Products table in the File Explorer, Stylus Studio renders the table as
an XML document.

Figure 381. Viewing a Relational Table as XML

Using a simple XPath expression (count(//Products)), we can see that there are 77
records in the Product table. When we preview the XQuery, we can see that 77 new
records have been added to the Products table, for a total of 154:

Figure 382. Updated Relational Table

Stylus Studio User Guide

873

Working with XQuery in Stylus Studio

Creating an Update Function Call

In Stylus Studio, you can create an update function call using

Drag-and-drop

The short-cut menu on the Mapper canvas

When you use drag-and-drop, Stylus Studio creates the link from the update function
block for you, which automatically commits the XQuery mapping to Stylus Studio.

How to Create an Update Function Call

To create an update function call:
1.

Connect to the relational database that contains the table or tables you want to update.
See Creating a Database Connection on page 852 if you need help with this step.

Drag the table you want to update from the File Explorer and drop it on the XQuery
Mapper canvas.

Map the repeating element that represents the table you want to update to the first
input port ($row-node as element()*).

Create a FLWOR block to locate the record you want to update in the database table.
See Creating a FLWOR Block on page 835 if you need help with this step.

Map the output of the FLWOR block to the flow port on the top of the update function
block.

Create a condition expression to select the records you want to update. See Creating
a Function Block on page 837 if you need help with this step.

Expand the update function block by double-clicking it.

Double-click the input port that corresponds to the column whose value you want to
change.

Save and preview the XQuery; check results on the database table you have updated.

Alternative:

874

Right-click the Mapper canvas.

Select Function Block > DataDirect XQuery > sql-update from the short-cut menu.
The update function block appears on the Mapper canvas.

Stylus Studio User Guide

Updating Relational Databases

When you have finished defining the XQuery, map the update function blocks output
port to the Set Target Document pane. Your XQuery mapping is not committed to
Stylus Studio until you complete this step.

Example
In this example, we update the Shippers table to change the telephone for the Speedy
Express company.
If we double-click the Shippers table in the File Explorer, the Shippers table is rendered
as XML. Looking at Grid tab, we can see that the Shippers table has three records, and
that the current telephone number for Speedy Express is (503) 555-9831.

Figure 383. Shippers Table

To get started, we create a new XQuery and save it as UPDATE.xquery. As with the insert
function, we drag and drop the table from the File Explorer and drop it on the XQuery
Mapper canvas. After dropping the table, choose Create SQL Update Call from the shortcut menu to add the SQL block and the corresponding code to the XQuery.
In order to update a record, we need to:

Specify the table whose records we need to fetch

Fetch the record we want to update

Specify a new value for the table column we want to change

Stylus Studio User Guide

875

Working with XQuery in Stylus Studio

First, we map the Shippers repeating element to the first port ($row-node as element()*)
on the SQL block created for the update function. This creates a collection based on the
Shippers table. (See Using the collection() Function in Stylus Studio on page 851 for
more information on collections.)
Next, we create a FLWOR expression to iterate over the Shippers table by mapping the
Shippers repeating element to the For port on the FLWOR block, and mapping the
FLWOR blocks output port to the flow port on the SQL block. At this point, our XQuery
Mapper canvas, and the resulting XQuery code, looks something like this:

Figure 384. FLWOR Expression Iterates Over the Shippers Table

Next we need to specify which record we want to update, and how we want to change it.
Well do this by creating a simple condition expression that locates the shipper whose
phone number we want to change (the ShipperID for Speedy Express is 1). To do this, we

Add the Equal conditional block to the Mapper canvas

Map the ShipperID node to the blocks first input port

Double-click the second input port to specify the ShipperID value for the record we
want to update

876

Stylus Studio User Guide

Updating Relational Databases

As you can see from the resulting XQuery code, the update function still needs values
specified for the column in the Shippers table we want to update, and the new value

Figure 385. Before the Update Block is Mapped for Values

To specify values to update the Shippers table, we first double-click the SQL update block
to expose the ports for each of the tables columns, and then double-click the Phone port:

Figure 386. Specifying the New Value for the Phone Column

Stylus Studio User Guide

877

Working with XQuery in Stylus Studio

If we preview the XQuery and then check open Shippers table as XML in Stylus Studio,
we can see that the telephone number has been updated from (503) 555-9831 to
(503) 555-3099:

Figure 387. Updated Phone Column on Shippers Table

Creating a Delete Function Call

When you create a delete function call in XQuery Mapper, you must

Use the XQuery Mapper short-cut menu

Map the function blocks output port to the Set Target Document pane.

How to Create a Delete Function Call

To create a delete function call:

878

Right-click the Mapper canvas.

Select Function Block > DataDirect XQuery > sql-delete from the short-cut menu.
The delete function block appears on the Mapper canvas.

Drag the table you want to update from the File Explorer and drop it on the Add
Source Document pane.

Stylus Studio User Guide

Updating Relational Databases

Create a FLWOR block to iterate over the table to locate the records you want to
update. See Creating a FLWOR Block on page 835 if you need help with this step.

Create a condition expression to select the records you want to update. See Creating
a Function Block on page 837 if you need help with this step.

Example
In this example, we delete one of the products from the Products table, Queso Cabrales,
as it as been discontinued by the supplier. As shown in the following illustration, Queso
Cabrales corresponds to ProductID 11 in the Products table:

Figure 388. Record to Be Deleted from the Products Table

In a new XQuery we save as DELETE.xquery, we first add the Products table to our
XQuery by dragging it from the File Explorer and dropping it on the Add Source
Document pane. We start building the XQuery by creating a FLWOR block; well use the
FLWOR expression to iterate over the Products table to locate the record we want to
delete. When the FLWOR block is added, we map the Products repeating element to the
FLWOR blocks For port.

Stylus Studio User Guide

879

Working with XQuery in Stylus Studio

Next, we add a simple condition expression that locates the Product table record by
matching the ProductID to the value of the record we want to delete (the ProductID for
Queso Cabrales is 11). We can then map the output of this condition expression to the
Where port on the FLWOR block.
Finally, we add the SQL delete function by right-clicking the Mapper canvas and selecting
Function Block > DataDirect XQuery > sql-delete from the short-cut menu. (SQL delete
functions cannot be created using drag-and drop.) We map the FLWOR blocks output
port to the flow port on the top of the SQL delete function block, and map the Products
repeating element to the SQL delete function blocks input port. At this point, our XQuery
looks something like this:

Figure 389. XQuery Mapper Before Code is Committed

Notice that the text pane of the XQuery Mapper is blank. This is because the mapping has
not been committed to Stylus Studio. To commit a mapping to Stylus Studio, you simply
map the function blocks output port to the Set Target Document pane. This mapping,
which is completed automatically for you by Stylus Studio when you create SQL insert
and update functions using drag and drop, is needed to commit the XQuery mapping to
Stylus Studio; as with SQL insert and update functions, no output results from a SQL
delete function. Any changes specified in the XQuery occur directly on the database.

880

Stylus Studio User Guide

Updating Relational Databases

When we commit the XQuery mapping to Stylus Studio, our XQuery code appears in the
text pane, as shown here:

Figure 390. XQuery Mapping Committed to Stylus Studio

Stylus Studio User Guide

881

Working with XQuery in Stylus Studio

After we preview the XQuery, we can see that the record for Queso Cabrales has been
deleted from the Products table:

Figure 391. Queso Cabrales Deleted from the Products Table

Working with XQuery Library Modules

In XQuery, a library module is an XQuery that contains one or more user-defined
functions. An XQuery library module cannot contain any executable code.

Creating a Library Module

An XQuery module consists of:

The module namespace definition

One or more function declarations for user-defined functions

882

Stylus Studio User Guide

Working with XQuery Library Modules

Consider the following example of a simple XQuery library module that contains two
user-defined functions total-price and titleQuantity:
module namespace ns = "urn:utils";
declare function ns:total-price( $i as element) as xs:decimal
{
let $subtotals := for $s in $i return $s/quantity * $s/USPrice
return sum( $subtotals )
};
declare function ns:titleQuantity($GROUP_28, $row)
{
<book>
<title>
{$row/title/text()}
</title>
<quantity>
{$GROUP_28/QTY/QTY01/QTY0102/text()}
</quantity>
<ISBN>
{$GROUP_28/LIN/LIN03/LIN0301/text()}
</ISBN>
</book>
};

You create an XQuery library module by typing the module definition in the XQuery
editor. If you copy/paste user-defined functions from other XQuery, make sure to change
the namespace prefix for each user-defined function as described in the following section,
About Namespaces on page 883.

About Namespaces
An XQuery library module requires a namespace definition. You can specify the
namespace using

A symbolic name, like the one shown in the previous example

A URI, such as "http://example.com/xquery/library/book"

The prefix you assign to the namespace must be used with any user-defined functions you
declare in the XQuery library module. For example, if you create a user-defined function
using the Stylus Studio refactoring feature, you must replace the default namespace that
was created with the user-defined function (local:) with the namespace associated with
the XQuery library module (ns:, in the previous example).

Stylus Studio User Guide

883

Working with XQuery in Stylus Studio

Importing a Library Module

Once you have created an XQuery library module, you can import it into another XQuery.
To import a library module:
1.

Open the XQuery into which you want to import the library module.

Click the Mapper tab.

Right-click the Mapper background and choose Imported Modules from the short-cut
menu.
The Imported Modules dialog box appears.

Figure 392. Imported Modules Dialog Box

If the XQuery already has an imported library module, its information is displayed.

884

Click the Add button.

The Open dialog box appears.

Locate the XQuery that contains the library module definition and click OK.

Stylus Studio User Guide

Working with XQuery Library Modules

The library module appears in the Imported Modules dialog box; the Namespace field
displays the library modules namespace; the Location field displays its path.

Figure 393. Imported Library Module

Click OK to import the module into the XQuery.

The XQuery code now contains an import statement for the newly imported library
module. For example:

import module namespace ns="urn:utils" at "file:///c:/temp/modules.xquery";

Using a Library Module

Once you have created a library module and imported it into an XQuery, you can easily
add user-defined functions to your XQuery.
Earlier, we showed the creation of a library module consisting of two user-defined
functions, total-price and titleQuantity. Once the library module is imported, the userdefined functions defined in the module are available by right-clicking the XQuery
Mapper canvas and choosing User Defined Functions from the short-cut menu.

Stylus Studio User Guide

885

Working with XQuery in Stylus Studio

All user-defined functions that are specified in any library modules you have imported are
available from the User Defined Functions short-cut menu, as shown in the following
illustration:

Figure 394. Adding User-Defined Functions to an XQuery

Removing a Library Module

To remove a library module:

886

Follow Step 1 through Step 3 in the procedure Creating a Library Module on

page 882.

In the Imported Modules dialog box, select the library module you want to remove.

Click the Remove button.

Click OK.
The import statement is removed from your XQuery.

Stylus Studio User Guide

Debugging XQuery

Alternative
To remove an imported module from your XQuery, delete the code directly in the XQuery
editor.

Debugging XQuery
Complex XQuery requires robust debugging tools.

Figure 395. Debugging XQuery in Stylus Studio

With Stylus Studio, you can

Set breakpoints in your XQuery

Monitor the value of XQuery variables.

Trace the sequence of XQuery expressions that created output. With a click anywhere
in the result, Stylus Studio Visual Backmapping technology displays the XQuery
expression responsible for creating that result.

Stylus Studio User Guide

887

Working with XQuery in Stylus Studio

This section covers the following topics:

Using Breakpoints

Viewing Processing Information

Using Bookmarks

Profiling XQuery

Using Breakpoints
The Stylus Studio debugger allows you to interrupt XQuery processing to gather
information about variables and XQuery expression execution at particular points.

Inserting Breakpoints
To insert a breakpoint:
1.

In the XQuery in which you want to set a breakpoint, place your cursor where you
want the breakpoint to be.

Click Toggle Breakpoint

or press F9. Stylus Studio inserts a blank stop sign
to the left of the line with the breakpoint.

Removing Breakpoints
To remove a breakpoint:
1.

Click in the line that has the breakpoint.

Press F9 or click Toggle Breakpoint.

Alternative: In the Stylus Studio tool bar, click Breakpoints
to display a list of
breakpoints in all open files. You can selectively remove one or more, remove them
all, or jump to one of them.

Start Debugging
When your XQuery has one or more breakpoints set, start processing by clicking Start
or pressing F5. When Stylus Studio reaches the first breakpoint, it
Debugging
suspends processing and activates the debugging tools. After you examine the
information associated with that breakpoint (see Viewing Processing Information on
page 889) you can choose to

Step into click

or press F11.
888

Stylus Studio User Guide

Debugging XQuery

Step over click

or press F10.
Step out click
or press Shift+F11.
Run to cursor click
.
Continue processing press F5.
Stop processing click Stop Debugging
in the Stylus Studio tool bar, or click
Cancel in the lower right corner of the XQuery editor, or press Shift+F5.

Note You can also click Pause

to suspend XQuery processing. Stylus Studio flags the line

it was processing when you clicked Pause.

Viewing Processing Information

Stylus Studio provides several tools for viewing processing information. The tools
become active when processing reaches a breakpoint. This section discusses the following
topics:

Watching Particular Variables

Evaluating XPath Expressions in the Current Processor Context

Obtaining Information About Local Variables

Displaying a List of Process Suspension Points

Displaying XQuery Expressions for Particular Output

Watching Particular Variables

Use the Watch window to monitor particular variables. To display the Watch window,
click Watch
in the Stylus Studio tool bar. This button is active when Stylus Studio
suspends processing because it reached a breakpoint. Stylus Studio displays the Watch
window only when processing is suspended.
Enter the names of the variables you want to watch. You can enter as many as you like.
When Stylus Studio suspends processing, it displays the current values for any variables
listed in the Watch window. You can expand and collapse complex structures as needed.
During XQuery debugging, you can enter XPath expressions in the Watch window fields.
Stylus Studio uses the current context to evaluate these expressions, and displays the
results with the same kind of interface Stylus Studio uses for nodeList and node variables.

Stylus Studio User Guide

889

Working with XQuery in Stylus Studio

Evaluating XPath Expressions in the Current Processor Context

When you suspend processing, you can evaluate an XPath expression in the context of the
suspended process. You do this in the Watch window. Click
in the Stylus Studio tool
bar to display the Watch window. Click in an empty name field and enter an XPath
expression. As soon as you press Enter, Stylus Studio displays the results of the evaluation
in the Value field of the Watch window.

Obtaining Information About Local Variables

Display the Variables window to obtain information about local variables. To display the
Variables window, click Variables
in the Stylus Studio tool bar. This button is active
when Stylus Studio suspends processing because it reached a breakpoint. Stylus Studio
displays the Variables window only when processing is suspended.
Information displayed in the Variables window includes:

Information about how the return value (displayed in the Variables window as
__Return_Value_3, for example) is being built

Local and global XQuery variable values

Also, you can navigate the structure associated with a variable, a parameter, or the current
context if it is a node list or a node.

Displaying a List of Process Suspension Points

Display the Call Stack window to view a list of the locations at which processing was
suspended. For XQuery files, Stylus Studio displays the XQuery file name and line
number.
To display the Call Stack window, click Call Stack
in the Stylus Studio tool bar. This
button is active when Stylus Studio suspends processing because it reached a breakpoint.
Stylus Studio displays the Call Stack window only when processing is suspended.
When processing is complete, the call stack is empty.
When execution is suspended you can use the Call Stack window to jump directly to the
XQuery source. Double-click on a stack line to go to that location. A green triangle
appears to indicate this location in the source file.

890

Stylus Studio User Guide

Debugging XQuery

Displaying XQuery Expressions for Particular Output

After you create an XQuery, or during XQuery debugging, Stylus Studio can display the
XQuery expression that generated a particular part of a result document. This can be
particularly helpful when the result is not quite what you want.
In the Preview window, click on the output for which you want to display the XQuery
expression. You can do this while either the text view or the browser view is active. Stylus
Studio flags the line in the XQuery source that contains the expression that generated the
output you selected.

Inserting
To insert a bookmark:
1.

Click in the line that you want to have a bookmark.

Click Toggle Bookmark

in the Stylus Studio tool bar. Stylus Studio inserts a
turquoise box with rounded corners to the left of the line that has the bookmark.

Removing
To remove a bookmark:
1.

Click in the line that has the bookmark you want to remove.

Click Toggle Bookmark in the Stylus Studio tool bar. Stylus Studio removes the
turquoise box.

To remove all bookmarks in a file, click Clear All Bookmarks

Moving Focus
To move from bookmark to bookmark, click Next Bookmark
Bookmark
.

Stylus Studio User Guide

or Previous

891

Working with XQuery in Stylus Studio

Profiling XQuery
XQuery profiling is available only in Stylus Studio XML Enterprise Suite.
In addition to debugging tools for XQuery, Stylus Studio provides the XQuery Profiler, a
tool that helps you evaluate the efficiency of your XQuery. By default, the performance
metrics gathered by the XQuery Profiler are displayed in a preformatted report, like the
one shown here:

Figure 396. XQuery Profiler Report

The report format is controlled by the default XSLT stylesheet, profile.xsl, in the \Stylus
Studio\bin directory. You can customize this stylesheet as required. You can save XQuery

Profiler reports as HTML.

Note XQuery and XSLT Profiler reports use the same XSLT stylesheet.

892

Stylus Studio User Guide

Debugging XQuery

In addition to generating the standard XQuery Profiler report, you can save the raw data
generated by the Profiler and use this data to create your own reports. See Enabling the
Profiler for more information about this procedure.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XQuery Profiling video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.

About Performance Metrics

The XQuery Profiler can record three different levels of performance metrics:

A call tree of execution times

Execution times by XQuery expression, and

A detailed log of step-by-step expression execution

Note Displaying the report for a step-by-step log can take significantly longer than evaluating

the XQuery itself. Consider using the Profiler with the first two performance metric
options. You can also use the Limit Trace To fields to further restrict the Profilers scope.
If you find you need still more detail (while troubleshooting a performance bottleneck,
for example), use the step-by-step setting.

Enabling the Profiler

The XQuery Profiler is off by default. You enable the Profiler on the Profiling Options tab
of the XQuery Scenario Properties dialog box.
To enable the XQuery Profiler:
1.

Open the Scenario Properties dialog box for the XQuery. (Click Browse
top of the XQuery editor window.)

Stylus Studio User Guide

at the

893

Working with XQuery in Stylus Studio

Click the Profiling Options tab.

Figure 397. XQuery Profiler Options

Select the settings for the performance metrics you want the Profiler to capture.

Optionally, save the raw Profiler data to a separate file.

This option is available only after you select one or more performance metrics
settings.

Note

Click OK.
The next time you preview the XQuery results, the performance metrics you selected
are available to you in the XQuery Profiler report (and as raw data if you selected that
setting and specified a file).

Displaying the XQuery Profiler Report

To display the XQuery Profiler report:

894

Ensure that the Profiler is enabled. (See Enabling the Profiler if you need help with
this step.)

Click the Preview Result button (

Click the Show Profiling Report button (

).
The XQuery Profiler report appears in the Preview window.

Stylus Studio User Guide

Using DataDirect XQuery Execution Plans

DataDirect XQuery execution plan support is available only in Stylus Studio XML
Enterprise Suite.
DataDirect XQuery generates an XQuery execution plan so that you can see how
DataDirect XQuery will execute your query. For example, if your query accesses a
relational data source, the plan will include the SQL statements that DataDirect XQuery
will send to the database.
One of the main benefits of using this feature is that you can tune your queries for the best
performance possible.

Query Plans in Stylus Studio

In Stylus Studio, a query plan for the DataDirect XQuery processor becomes available
as soon as your XQuery code is well-formed. (Query plans are created only by the
DataDirect XQuery processor.) The query plan changes with your XQuery code if you
add a new data source, for example, the query plan is modified to reflect the new source.
You can view query plans in Stylus Studio to gain insight into how the DataDirect
XQuery processor will execute your XQuery code, including seeing the type of SQL
statements that are used to access relational data, when XML streaming is being used,
which temporary tables are being created, when variables are being called, and so on.
Query plans are displayed on the Plan tab of the XQuery Editor. An example of a query
plan is shown in Figure 398.

Example of a Query Plan

The example query plan shown in Figure 398 provides information about how DataDirect
XQuery translates the following query, which accesses one relational data source, into a
SQL Select statement and how XML results are constructed.
declare option ddtek:plan-explain 'format=xhtml';
<myHoldings> {
for $holdings in collection("pubs.dbo.holdings")/holdings
where $holdings/userid = "Minollo"
return <holding
quantity="{$holdings/shares}">{$holdings/stockticker/text()}</holding>
}
</myHoldings>

Stylus Studio User Guide

895

Working with XQuery in Stylus Studio

In the following query plan, notice how the Relational Data Source node includes details
about the SQL Select statement, as well as information about how the result ($PT) is
constructed.

Figure 398. Example of a Query Plan Displayed in the XQuery Editor

Parts of a Query Plan

The graphic representation of a query plan is a tree structure that provides the details of
how DataDirect XQuery will execute the query for which the plan was generated. The
query plan tree diagram is read-only, though it does provide navigation and formatting
features. You can also print and save the query plan as HTML.

896

Stylus Studio User Guide

Using DataDirect XQuery Execution Plans

In addition to the Plan node, the query plan tree can include Adaptors, Global Variables,
and Local Functions nodes. These nodes are described in the following table.
Table 106. Query Plan Nodes
Node

Description

Adaptors

This node contains a list of database resources that will be involved

in the execution of the query. These resources can include JDBC
connections, temporary tables, and deferred SQL statements used in
the context of DataDirect XQuery update functionality.

Global Variables

This node contains a list of global variables that are available to the
query plan, such as external variables defined by the query and
variables defined as part of the generation of the execution plan.

Local Functions

This node contains a list of user-defined functions used during the

query evaluation. Each user-defined function listed in this node has
a plan description associated with it. Plan descriptions are described
next.

Plan

This node contains the description of the query execution plan. It

contains the nodes of the plan, for example, FLWOR nodes and the
nodes within the FLWOR nodes such as for, let, and return.

Navigation
You can navigate the tree to check where variables are defined and where they are
referenced. For example, you can navigate from one adaptors definition to its references
and vice-versa.
To navigate the tree, you can

Use the toolbar displayed at the top of the tree

Right-click an item in the tree and use the context-sensitive menu

Scroll through the nodes on the tree diagram individually

Stylus Studio User Guide

897

Working with XQuery in Stylus Studio

Query Plan Toolbar

The query plan toolbar has buttons that help you navigate the variables defined in your
XQuery code. These buttons are described in the following table.
Table 107. Query Plan Toolbar Buttons
Button

Description
Go to definition: given a selected variable reference, go to the
position in the plan where the variable is defined.
Go to first reference: given a selected variable definition, go to its
first reference in the plan.
Go to next reference: given a selected variable reference, go to the
next reference of the same variable (if any).
Go to previous reference: given a selected variable reference, go to
the previous reference of the same variable (if any).

Formatting
You can change the font size used to display query plan text and symbols by right-clicking
a tree node and selecting the font size you wish to use. Changes to font size affect the
entire query plan, but they are not saved when you save the query plan as HTML.

Saving a Query Plan as HTML

You can save a query plan as an HTML document; you might wish to do this for review
or presentation purposes, for example.
To save a Query plan as HTML:

898

Select XQuery > Save Plan as HTML from the Stylus Studio menu.
Alternative: Click the Save Plan button on the Plan tab.
The Save As dialog box appears.

Choose a path and name for the HTML file.

Click Save.

Stylus Studio User Guide

Using DataDirect XQuery Execution Plans

Displaying a Query Plan

This section describes the prerequisites and procedure for displaying a query plan in
Stylus Studio.

Prerequisites
In order to display a query plan in Stylus Studio, you need to specify the DataDirect
XQuery processor for your XQuery. See Selecting an XQuery Processor for more
information.

How to display a query plan

To display a Query plan:
1.

Open the XQuery whose query plan you want to view in the Stylus Studio XQuery
Editor.

Make sure your XQuerys processor is set to the DataDirect XQuery processor. See
Selecting an XQuery Processor if you need help with this step.

Click the Plan tab in the XQuery Editor.

Stylus Studio displays the query plan.

Optimizing Your XQuery

One of the main benefits of the query plan is that you can use it when tuning your queries
for the best performance possible. After viewing the query plan and executing the
XQuery, you might wish to make some changes to the XQuery code to see how they affect
the query plan and, consequently, how the XQuery code is processed.
See the DataDirect XQuery Users Guide and Reference for more information on
optimizing your XQuery code for data access.
Tip The Stylus Studio Profiler generates an HTML report that contains performance metrics

for your XQuery code. You might want to run and view this report before making changes
to your XQuery code. See Profiling XQuery for more information.

Stylus Studio User Guide

899

Working with XQuery in Stylus Studio

Creating an XQuery Scenario

An XQuery scenario is a group of settings you associate with an XQuery. Examples of
scenario settings include a main input document, XQuery processors, and whether or not
you want to perform validation on the XML that results from your XQuery. Each time you
preview an XQuery, Stylus Studio uses settings from the currently active scenario. For
example, if the currently active scenario specifies the DataDirect XQuery processor,
Stylus Studio executes the XQuery using that processor when you click the Preview
Result button (
).
You can create multiple scenarios for a single XQuery, and choose different settings for
each. This flexibility can aid the XQuery development process as it enables you to easily
test the XQuery against different input documents and using different processors before
making the XQuery available.
This section covers the following topics:

Specifying XML Input

Selecting an XQuery Processor

Setting Default Options for Processors

Setting Values for External Variables

Performance Metrics Reporting

How to Run a Scenario

Working with Relational Data Sources

How to Create a Scenario

How to Run a Scenario

How to Clone a Scenario

Specifying XML Input

When you create an XQuery scenario, you can optionally specify inputs XML
documents or other sources of XML that set the context for the XPath expressions in your
XQuery code. This XML source is referred to as the main input.
The main input is a URL for a specific XML document. Specifying a main input is an
alternative to using the XQuery doc() function in your XQuery code. When you specify
a main input document, expressions like \books\book in your XQuery code are evaluated
in the context of that document.

900

Stylus Studio User Guide

Creating an XQuery Scenario

You specify XML input on the General tab of the Scenario Properties dialog box.

Figure 399. XQuery Scenario General Properties

Note If you build your XQuery using the XQuery Mapper, Stylus Studio uses the first source

document you select as the main input XML document, though you can override this
default at any time. See Data Sources to learn more about the process of selecting and
working with XQuery source documents in XQuery mapper.

Stylus Studio User Guide

901

Working with XQuery in Stylus Studio

Selecting an XQuery Processor

You use the Processors tab of the Scenario Properties dialog box to specify the processor
you want to use to process your XQuery code.

Figure 400. XQuery Scenario Processor Properties

You can use

The DataDirect XQuery processor

The Saxon processor, which supports XQuery debugging and backmapping

The Raining Data TigerLogic XDMS XQuery processor, which runs on the
TigerLogic XDMS server

Any custom processor you specify

Tip You can define default settings for XQuery processors, and you can also choose to use

one of them as the default XQuery processor. See Setting Default Options for
Processors on page 907.
Using the Saxon Processor
Stylus Studio lets you execute XQuery using either the Saxon-B (basic) or Saxon-SA
(schema-aware) processor. You specify which processor you want to use with the
Execution mode property in the Saxon XQuery Settings dialog box. Settings that have

902

Stylus Studio User Guide

Creating an XQuery Scenario

command line equivalents in Saxon show the command in parentheses following the
property name. Some settings are available only if you are using Saxon-SA.
Support for Saxon-SA is available only in Stylus Studio XML Enterprise Suite.
Stylus Studios Sense:X syntax coloring and auto-completion provides full support for
Saxon syntax, so long as the Saxon XQuery processor is either associated with the current
XQuery scenario or has been set as the default XQuery processor.
If you want to use the Saxon processor:
1.

On the Processors tab, click Saxon.

The Settings button becomes active.

Click the Settings button.

The Saxon XQuery Settings dialog box appears.

Figure 401. Saxon XQuery Settings Dialog Box

Complete the settings as desired. Press F1 to access the Stylus Studio online help, or
refer to the Saxon documentation for more information.

Click OK.

Using the TigerLogic XDMS Processor

Stylus Studios Sense:X syntax coloring and auto-completion provides full support for
TigerLogic XDMS syntax, so long as the TigerLogic XDMS XQuery processor is either
associated with the current XQuery scenario or has been set as the default XQuery
processor.

Stylus Studio User Guide

903

Working with XQuery in Stylus Studio

If you want to use the TigerLogic XDMS processor:

Click TigerLogic XDMS.

The Settings button becomes active.

Click the Settings button.

The TigerLogic XDMS Server Settings dialog box appears.

Figure 402. TigerLogic XDMS Server Settings Dialog Box

Enter the host, port, username, and password information for the server on which the
TigerLogic XDMS is running.

Click OK.

Using Custom URI Resolvers

Stylus Studio supports several URI types, such as http://, file://, and ftp://. If you use the
DataDirect XQuery processor to process your XQuery, you can also create custom URI
resolvers that allow the DataDirect processor to recognize custom URI types. Custom
URI resolvers can be created for use with DataDirect XQuery doc and collection
functions, and import module statements.
The process for using custom URI resolvers in Stylus Studio involves:

904

Using the DataDirect XQuery and Java APIs to implement a Java interface for each
of the custom URI resolver types you intend to use.

Registering the Java class for each custom URI resolver with Stylus Studio. You can
do this on a per-XQuery basis using the XQuery Scenario Properties dialog box, or
as a default setting for all XQuery code you write in Stylus Studio using the
Processor Settings page of the Options dialog box.

Stylus Studio User Guide

Creating an XQuery Scenario

Implementing a Custom URI Resolver Interface

You use either the DataDirect XQuery API or the Java API to implement a custom URI
resolver interface, as summarized in the following table.
Table 108. URI Resolver Interfaces
For This Custom URI Resolver Type

Use This Interface

Document doc function

javax.xml.transform.URIResolver

Collection collection function

com.ddtek.xquery.CollectionURIResolver

Module import module statement

com.ddtek.xquery.ModuleURIResolver

For more information on implementing a custom URI resolver interface, see the
DataDirect XQuery Users Guide and Reference.

Registering a Custom URI Resolver

Use this procedure to register a custom URI resolver for an individual XQuery.
To register a custom URI resolver for an XQuery:
1.

Open the XQuery for which you want to register a custom URI resolver in the Stylus
Studio XQuery Editor.

Click the Edit scenario properties button ( .

The Scenario Properties dialog box appears.

Click the Processor tab.

If DataDirect XQuery is not specified as the processor, use the Processor drop-down
field to change it.

Stylus Studio User Guide

905

Working with XQuery in Stylus Studio

Click the Settings button.

The DataDirect XQuery Options dialog box appears.

Figure 403. DataDirect XQuery Options Dialog Box

Click the more button (

) for the custom URI resolver type you want to register.
The Java Class Browser dialog box appears.

Figure 404. Java Class Browser

906

Navigate the available folders to locate the file that implements the interface for the
type of custom URI resolver you are registering.

Click OK to register the custom URI resolver.

Click OK to close the Scenario Properties dialog box.

Stylus Studio User Guide

Creating an XQuery Scenario

Registering a Default Custom URI Resolver

Use this procedure when you want to register a custom URI resolver that will be used by
default for all XQuery code you create in Stylus Studio. You can always override the
default setting for individual XQuery.
To register a default custom URI resolver:
1.

In Stylus Studio, click Tools > Options on the menu bar.

The Options dialog box appears.

Navigate to the Module Settings > XQuery > Processor Settings folder.

Figure 405. XQuery Processor Settings

Follow Step 4 through Step 8 in the procedure Registering a Custom URI Resolver
on page 905.

Setting Default Options for Processors

You can set default values for all XQuery processors on the Processor Settings page of
the Options dialog box. In addition, you can select the processor you want to use as your
default XQuery processor.
Tip

You can always override the default processor and default processor settings at the
scenario level.

Stylus Studio User Guide

907

Working with XQuery in Stylus Studio

To set defaults for XQuery processors:
1.

From the Stylus Studio menu, select Tools > Options.

Stylus Studio displays the Options dialog box.

Select Module Settings > XQuery > Processor Settings.

Figure 406. Options for XQuery Processors

Select the processor for which you want to specify default settings from the
Processor drop-down list.

If required, complete processor-specific settings. (Click the Settings button.)

If you want to use this processor as the default processor for all XQuery scenarios,
click the Use as default processor check box.

Click OK.

Setting Values for External Variables

The Parameter Values tab of the Scenario Properties dialog box displays any external
variables you have defined in the XQuery source. You can specify the parameter value you
want to use for any external variables when you run the scenario. For example, imagine
your XQuery code contains the following:
declare variable $part_num external

908

Stylus Studio User Guide

Creating an XQuery Scenario

This variable is displayed on the Parameters tab as follows:

Figure 407. XQuery Scenario Parameters

When you run the scenario, you can specify the parameter value you want to use by
double-clicking the Expression field and typing a value. Valid values are XPath
expressions and must be entered using single or double quotes.

Performance Metrics Reporting

See Enabling the Profiler to learn more about the different ways in which Stylus Studio
can provide you with XQuery performance metrics.

Validating XQuery Results

You can optionally validate the XML document that results from XQuery processing. You
can validate using any of the customizable processors supported by Stylus Studio, such as
the .NET XML Parser and XSV, or using the built-in Stylus Studio validation engine.

Stylus Studio User Guide

909

Working with XQuery in Stylus Studio

To validate XQuery scenario result documents:
1.

Open the XQuery whose results you want to validate.

In the XQuery Editor, in the scenario name field, click the down arrow and click the
name of the scenario for which you want to perform validation.

Click Browse

Click the Validation tab.

to open the Scenario Properties dialog box.

Figure 408. Validation Tab for XQuery Scenarios

910

Click Validate query result.

If you are using Stylus Studios built-in validation engine, optionally, specify the
XML Schemas against which you want to validate the XML result document.
Otherwise, go to Step 7
a.

Click the Open file button ( ).

The Open dialog box appears.

Select the XML Schema you want to use for validation.

Click the Open button to add the XML Schema to the Validation tab.

Optionally, add other XML Schemas.

Go to Step 8.

Stylus Studio User Guide

Creating an XQuery Scenario

Click the Use custom validator button, and select the validation engine you want to
use from the drop-down list box.

Click OK.

How to Create a Scenario

To create a scenario:
1.

In the XQuery editor tool bar, click

.
Alternative: Select Create Scenario from the scenario drop-down list at the top of the
editor window.
Stylus Studio displays the Scenario Properties dialog box.

In the Scenario name: field, type the name of the new scenario.

In the Main input: field, type the name of the XML file to which you want to apply
to navigate to an XML file and select it.
the XQuery, or click Browse
If the first document you added to the XQuery is an XML document, Stylus Studio
uses that document as the XML source for the scenario and displays it in this field.

Note

If you are using DataDirect XQuery, specify one or more defined collections as
input. See Specifying XML Input if you need help with this step.

In the Output URL field, optionally type or select the name of the result document you
want the XQuery to generate. If you specify the name of a file that does not exist,
Stylus Studio creates it when you preview the XQuery.

If you want Stylus Studio to store paths relative to the XQuery path, ensure that the
Use relative paths option is checked.

If you check Preview result in an external application, Stylus Studio displays the
result Internet Explorer. In addition, Stylus Studio always displays XQuery results in
the Preview window.

If you want to specify values for XQuery parameters, click the Parameter Values tab.
Click the Variable Name field for the parameter Stylus Studio places the text cursor
in the Expression field, allowing you to type a value for the parameter.

If you want Stylus Studio to capture performance metrics, enable the XQuery Profiler
on the Profiling Options tab. See Profiling XQuery on page 892.

Stylus Studio User Guide

911

Working with XQuery in Stylus Studio

10.

To define another scenario, click Add and enter the information for that scenario. You
can also copy scenarios. See How to Clone a Scenario on page 912.

11.

Click OK.

If you start to create a scenario and then change your mind, click Delete and then OK.

How to Run a Scenario

To run a scenario:
1.

Select a scenario from the scenario drop-down list at the top of the editor window.
Alternative:
a.

In the XQuery editor tool bar, click

.
Stylus Studio displays the Scenario Properties dialog box.

On the General tab, select the scenario you want to run from the Existing
Scenarios list.

Click OK.

Click the Preview Result button (

How to Clone a Scenario

912

Display the XQuery in the scenario you want to clone.

In the XQuery editor tool bar, click

box.

In the Scenario Properties dialog box, in the Existing preview scenarios field, click
the name of the scenario you want to clone.

Click Clone.

In the Scenario name field, type the name of the new scenario.

to display the Scenario Properties dialog

Stylus Studio User Guide

Generating XQuery Documentation

Change any other scenario properties you want to change. See How to Create a
Scenario on page 911.

Click OK.

If you change your mind and do not want to create the clone, click Delete and then OK.

Working with XQuery in Stylus Studio

description is used in the Function Detail. Here is an illustration of the XQuery in the
XQuery Editor; the xqDoc comments are highlighted:

Figure 411. xqDoc Comments as Seen in XQuery Source

Save the XQuery

When you annotate an XQuery using xqDoc comments, make sure to save the XQuery
before generating documentation. Unsaved work is not detected by the report generating
mechanism.

ActiveX Controls
xqDoc reports use ActiveX controls for navigation and code sample generation. Make
sure to enable ActiveX controls for the browser displaying the xqDoc report.

916

Stylus Studio User Guide

Generating XQuery Documentation

Viewing Code Samples

You can view code samples from an xqDoc report by clicking the view code hyperlink, as
shown in the following illustration.

Figure 412. Viewing an XQuery Code Sample

The XQuery code sample appears in a separate Web browser.

How to Generate XQuery Documentation

To generate XQuery documentation:
1.

Optionally, annotate your XQuery code as described in Syntax and Usage on

page 914.

Save the XQuery.

Stylus Studio User Guide

917

Working with XQuery in Stylus Studio

Click XQuery > Generate xqDoc.

Stylus Studio displays the Browse for Folder dialog box, which allows you to choose
where you want to save the XQuery documentation.

Figure 413. Browse for Folder Dialog Box

By default, Stylus Studio selects the directory to which the XQuery is saved. After
that, Stylus Studio uses the last location to which you saved the XQuery
documentation.

918

Optionally, change the location to which you want to save the XQuery
documentation.

Click OK.
Stylus Studio displays processing information in the Output window. A new Internet
browser is launched; the XQuery documentation is displayed in this browser.

If you have not already done so, enable ActiveX controls for the browser window
displaying the xqDoc report.

Stylus Studio User Guide

Using XQuery to Invoke a Web Service

Web Service support is available only in Stylus Studio XML Enterprise Suite
.
This section describes how to use the XQuery code that Stylus Studio creates from a Web
service call. To learn more about creating XQuery from a Web service call, see Creating
XQuery from a Web Service Call on page 958.
This section covers the following topics:

Choosing an XQuery Processor on page 919

Invoking a SOAP Request in an XQuery on page 919

Invoking Multiple SOAP Requests on page 920

Choosing an XQuery Processor

The XQuery code created by Stylus Studio is compliant with the DataDirect XQuery
processor.

Invoking a SOAP Request in an XQuery

To invoke a SOAP request in an XQuery:
1.

Create a new Web service call and configure the SOAP request as required. See How
to Compose a Web Service Call on page 944 if you need help with this step.

Create XQuery code from the Web service call. See How to Create XQuery from a
Web Service Call on page 959 if you need help with this step.
As a result of this step, XQuery code is copied to your systems clipboard.

Open a new XQuery (File > New > XQuery File). Make sure you use the Saxon or
DataDirect XQuery processor. See Selecting an XQuery Processor on page 902 if
you need help with this step.

Paste the clipboard contents into the XQuery.

Preview the XQuery by clicking the Preview Result button at the top of the XQuery
Editor.
The results of the SOAP request contained in the XQuery appear in the Preview
window.

Stylus Studio User Guide

919

Working with XQuery in Stylus Studio

If you are satisfied with the results, save the XQuery.

Invoking Multiple SOAP Requests

You can invoke multiple SOAP requests in the same XQuery. These SOAP requests can
be from the same Web service, or from different Web services if they use the same
parameters.

Rules
When invoking multiple SOAP requests in the same XQuery, bear in mind the following
rules:

The XQuery must contain only one instance of the header that declares the namespace
used by the Web service. For example:
declare namespace tns = "http://swanandmokashi.com";

Separate each ddtek:wscall() function with a comma, to create a sequence.

How to Invoke Multiple SOAP Requests in the Same XQuery

To invoke multiple SOAP requests in the same XQuery:
1.

Make sure you understand the rules for including multiple SOAP requests in the same
XQuery code as described in the previous section, Rules on page 920.

Create the Web service call, and use Web Service Call > Copy XQuery Call to
Clipboard to create XQuery code for the SOAP request as described in Creating
XQuery from a Web Service Call on page 958.
The XQuery code created by Stylus Studio is copied to your systems clipboard.

920

Create a new XQuery, and paste the contents of your system clipboard into it.

Type a comma at the end of the ddtek:wscall() function.

Repeat Step 2 for the next Web service SOAP request you want to invoke from your
XQuery.

Paste the new XQuery code into the XQuery you created in Step 3. Before pasting,
place the text cursor after the comma you typed in Step 4.

From the XQuery code you just pasted, delete the namespace declaration that
precedes the ddtek:wscall() function.
Stylus Studio User Guide

Using Web Services in XQuery

Support for the ddtek:wscall function is available only in Stylus Studio XML
Enterprise Suite.
The ddtek:wscall function allows you to use a Web service as a data source in XQuery.
This section describes how to create a ddtek:wscall function in XQuery Mapper, and
provides a simple example on how to create an XQuery to retrieve Web service data.
This section covers the following topics:

Choosing a ddtek:wscall Function on page 921

Creating a ddtek:wscall Function on page 921

Examining the ddtek:wscall Function Block on page 924

Mapping ddtek:wscall Functions on page 927

Example: Querying a Web Service on page 928

Choosing a ddtek:wscall Function

The XQuery Mapper provides two ddtek:wscall functions from the Mapper canvas
shortcut menu: wscall/2 and wscall/3. Both ddtek:wscall types provide location and
payload input ports. The wscall/3 type also include a header port, which you can use to
specify header information if your Web service requires it.

Figure 414. Port Types for the wscall Function block

See Examining the ddtek:wscall Function Block on page 924 for more information.

Creating a ddtek:wscall Function

There are two ways to create a ddtek:wscall function in XQuery Mapper:

Automatically, by dragging and dropping a Web service call (.wscc file) on the
Mapper canvas. This method creates the ddtek:wscall function in a single operation
that does not require you to specify the WSDL URL or Web service operation.
Stylus Studio User Guide

921

Working with XQuery in Stylus Studio

Use this method when you have created a Web service call using the Stylus Studio
Web Service Call Composer. See , , on page 943 for more information on this topic.
Manually, by choosing the ddtek:wscall function from the XQuery Mapper canvas
short-cut menu (right-click to display). This method requires you to enter the URL for
the WSDL file, which you can do by typing or navigating a file system, and selecting
the Web service operation you want your XQuery code to execute.
Use this method when you want to use Web service operations that have not been
exposed using a Stylus Studio Web service call.

To create a ddtek:wscall function automatically:

Open an XQuery and click the Mapper tab.

Open the Stylus Studio File Explorer or some other tool that allows you to navigate a
file system.

Locate the Web service call (.wscc file) for the Web service whose operations you
want to include in your XQuery code.

Drag the .wscc file and drop it on the XQuery Mapper canvas.
Stylus Studio adds the ddtek:wscall function glyph to the Mapper canvas and code
for the ddtek:wscall function to your XQuery code.

If the Web service exposes multiple operations, the ddtek:wscall function is created with
the operation that was exposed in the Web Service Call Composer when the .wscc file was
last saved. You can choose the operation you want your XQuery code to execute by
modifying the Web service call in XQuery Mapper:
1.

Double-click the ddtek:wscall function glyph.

The Choose the WSDL Operation dialog box (see Figure 416) appears.

Click the down arrow in the Operation Name field to display the available Web
service operations, as shown here:

Figure 415. Selecting a Web Service Operation

922

Stylus Studio User Guide

Using Web Services in XQuery

Select the operation you want and click OK.

To create a ddtek:wscall function manually:

Open an XQuery and click the Mapper tab.

Right-click the Mapper canvas and select Function Block > DataDirect XQuery >
wscall/2.
There are two predefined wscall functions wscall/2 provides location and payload
input ports; wscall/3 also provides a header input ports.

Note

Stylus Studio displays the Choose the WSDL Operation dialog box.

Figure 416. Choose the WSDL Operation Dialog Box

Enter the URL of the WSDL whose operation you want your XQuery to execute in
the WSDL File field.
Example:
http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx?WSDL

You can use Stylus Studio to help locate WSDL documents. See Obtaining WSDL
URLs on page 947 for more information.

Tip

Stylus Studio displays the operations associated with the Web service represented by
the WSDL in the Operation Name field.
4.

Choose the Web service operation you want your XQuery to execute from the
Operation Name field.
Example: GetStockQuotes.

Click OK.

Stylus Studio User Guide

923

Working with XQuery in Stylus Studio

Stylus Studio displays the wscall function block on the XQuery Mapper canvas.

Figure 417. wscall Function Block on the XQuery Mapper Canvas

The illustration shown in Figure 417 shows a wscall defined with location and
payload input ports.

Examining the ddtek:wscall Function Block

The previous procedure, Creating a ddtek:wscall Function on page 921, provided an
example Web service (Swanand Mokashis StockQuote WSDL
(http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx?WSDL), and
an example of an operation (GetStockQuotes). This Web service, given a stock ticker
value, returns information about that stock, including the company name, a current stock
quote, daily high and low values, and related information.
Imagine we chose the GetStockQuotes operation for our wscall. Lets take a closer look at
the wscall function block created by Stylus Studio.
As seen in Figure 417, our ddtek:wscall function block was created with two input ports
(we could have created a ddtek:wscall function block with three input ports), a flow port,
and an output port. (See Parts of a Function Block on page 837 for general information
about function blocks in XQuery Mapper.)

Location Input Port

The location input port for the ddtek:wscall function describes information about the
Web service whose operation we selected for the XQuery, including its location (as a
URL) and operation (as a SOAP action). This port is on all ddtek:wscall function blocks.

924

Stylus Studio User Guide

Using Web Services in XQuery

If you double-click the port, Stylus Studio displays a configurable information box, as
shown in Figure 418. (The same is true for other input ports and the output port.)

Figure 418. ddtek:wscall Location Input Port

If we right-click the address node and choose Set Text Value, the Value dialog box
displays the URL for the Swanand Mokashi Web service WSDL, as shown in Figure 419:

Figure 419. Value for ddtek:wscall location

Similarly, we would see GetStockQuotes if we looked into the soapaction node.

Payload Input Port

The payload input port for the ddtek:wscall function describes the data the Web service
requires in order to execute the SOAP action. This port is on all ddtek:wscall function
blocks. (It is the second input port for functions added to XQuery Mapper using the
wscall/2 menu choice. It is the third input port if you used the wscall/3 menu choice.)
Stylus Studio User Guide

925

Working with XQuery in Stylus Studio

The payload for the Swanand Mokashi StockQuotes Web service, for example, is a
ticker value PRGS, GOOG, or EBAY, for example.

Figure 420. ddtek:wscall Payload Input Port

By default, no text value is defined for the payload port.

Header Input Port

The header port for the ddtek:wscall function appears on function blocks defined using
the wscall/3 menu choice. You use the header port to provide authentication and
authorization information, like a username and password, for example.

Output Port
The output port for the ddtek:wscall function displays the output of the Web service
represented by the ddtek:wscall function. In the case of the Swanand Mokashi
StockQuote Web service, available output includes company name, stock quote, change,
opening price, and so on, as shown in Figure 419.

Figure 421. ddtek:wscall Output Port

926

Stylus Studio User Guide

Using Web Services in XQuery

Displaying Port Information

To display port information, double-click the port.

Note that you can display information for only one input port at a time.

Moving Port Information

When you move a port information box, the ddtek:wscall function block moves with it,
and vice versa.

Mapping ddtek:wscall Functions

In most typical XQuery mapping operations, you map source and target document nodes
to function block ports, as shown in Figure 422.

Figure 422. Mapping Typical Function Blocks in XQuery Mapper

Stylus Studio User Guide

927

Working with XQuery in Stylus Studio

When use a ddtek:wscall function, however, you map source and target document nodes
to schema nodes in the port information blocks, as shown in Figure 422.

Figure 423. Mapping a ddtek:wscall Function Block

Example: Querying a Web Service

In this example, well use the ddtek:wscall function to query the Swanand Mokashi
StockQuotes Web service.
To query the Swanand Mokashi Web Service:
1.

Get started by creating a wscall/2 function as described in Creating a ddtek:wscall

Function on page 921. As in that procedure, we

Use this value for the WSDL URL in Step 3:

http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx?WSDL

928

Select GetStockQuote for the WSDL operation in Step 4.

For our source document, well use a simple XML document that contains only a
ticker value PRGS.
For the target, well create a root node (right-click the Set Target Document pane and
choose Create Root Element), and a child element, my_quote.

Stylus Studio User Guide

Using Web Services in XQuery

When were done, our Mapper canvas looks like this:

Figure 424. Adding Source and Target Documents

Before continuing, lets make a quick change to the source document because wed
like to use this XQuery with other sources, we can define the source as a global
variable:
a.

Right-click the source document URL, and choose Associate with > Global

In the Associate Schema with Variable dialog box, we enter ticker_source and
click OK.
Now the document URL appears as $ticker_source, allowing us to easily substitute
other source documents for use with this XQuery.
Stylus Studio specified location, payload, and output ports based on the Web service
we used to create the wscall function block. (Double-click the ports to display this
information.) However, not all of the values required to generate the output we need
the specific company stock ticker we want to look up, and what information about
that stock we want Swanand Mokashi to provide has been specified. Well do that
now.
b.

Double-click the payload port, and map the ticker node from the source document to
the tns:QuoteTicker node in the payload port information box.

Figure 425. Specifying a Payload Value

The Web service will be given the value of the ticker element from our source
document when the XQuery is run.

Stylus Studio User Guide

929

Working with XQuery in Stylus Studio

Close the payload information box.

Next, lets specify the information we want from the Swanand Mokashi Web service.

Since well want multiple pieces of information from the Web service (we want to see
the company name, ticker value, and current stock price in our output), we define a
FLWOR block so that we make one call to the Web service.
Right-click the Mapper canvas and choose FLWOR Block.
Stylus Studio adds a FLWOR block to the XQuery Mapper.

Double-click the output port and fully expand the output port information box.

Figure 426. Selecting Output

930

Map the repeating tns:Quote element to the for port on the FLWOR block.

Stylus Studio User Guide

Using Web Services in XQuery

Next, map the FLWOR blocks output port to the my_quote node we created in the
target document.

Figure 427. Mapping the Web Service to a FLWOR Block

10.

Now we can choose the output provided by the Web service we want to include in our
XQuery. For the tns:CompanyName, tns:StockTicker, and tns:StockQuote Web service
nodes, we do this drag-and-drop operation:
a.

Using the right mouse button (mouse button 2), drag the node to the my_quote
node in the target document.

When we release the mouse button to drop the Web service node, we choose Add
Child Element and Map It.

We rename the target node, dropping the tns: prefix, in the Name dialog box
when the target document element is created.

When finished, close the output port information box.

When were done with this step, our output mappings look like this:
d.

Figure 428. Finished Mapping

Stylus Studio User Guide

931

Working with XQuery in Stylus Studio

Sample XQuery Code

Heres the XQuery code that Stylus Studio created for us, based on the XQuery mapping:

Figure 429. XQuery Code Created by the Mapper

And when we preview the code, this is our result:

Figure 430. Result of Web Service Used in an XQuery

932

Stylus Studio User Guide

Generating Java Code for XQuery

Java code generation is available only in Stylus Studio XML Enterprise Suite
.
You can generate Java code for XQuery in Stylus Studio. This section describes the
generated code, scenario settings that affect the generated code, as well as procedures for
generating, compiling, and running generated code.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Java Code Generation video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This section covers the following topics:

What Does Stylus Studio Generate?

Scenario Properties Used for Generating Code

Java Code Generation Settings

How to Generate Java Code for XQuery

Compiling Generated Code

Deploying Generated Code

Tip You can also generate:

C# code for XQuery. See Generating C# Code for XQuery

Java code for XSLT. See Generating Java Code for XSLT

What Does Stylus Studio Generate?

Stylus Studio generates a complete Java application that implements the XQuery
represented by the current XQuery using settings from the current scenario. The Java code
can be compiled and run within Stylus Studio.

Scenario Properties Used for Generating Code

When you generate code for XQuery, Stylus Studio uses some of the information
associated with the active XQuery scenario, as specified in the Scenario Properties dialog
box.

Stylus Studio User Guide

933

Working with XQuery in Stylus Studio

The following tables summarizes the scenario properties that affect code generation.
Table 109. Scenario Properties that Affect Code Generation
Tab

Comment

General

The Code Generation wizard uses only the Source XML URL and the
Output URL field, if specified. All other properties on this page are
ignored.

Processor

You can use the following XQuery processors for generating Java code:

DataDirect XQuery

Saxon

If the Stylus Studio URI Resolver property is selected, the generated

code includes lines that import and register ConverterFactory and
ConverterResolver classes from DataDirect XML Converters.
Note: If the scenario specifies an XQuery processor for which Java code
generation is not supported, Stylus Studio uses the DataDirect XQuery
processor for code generation purposes. The processor specified in the
scenario is not changed.
Parameter Values

Parameters are always treated as XQuery expressions; they appear in the

generated code just as they are entered in the Expression field.

Profiling Options

Ignored.

Validation

You can use the following validation engines for validating your XQuery
Java code:

Saxon

Java built-in

If you choose a validation engine that is not supported, Stylus Studio uses
the Java built-in validation engine.
Post-process

934

Only post-processing using Apache FOP and RenderX XEP is specified in

the generated code. Resulting PDF is written to the output URL specified
on the General tab.

Stylus Studio User Guide

Generating Java Code for XQuery

Java Code Generation Settings

When you generate Java code for an XQuery, Stylus Studio displays the Java Code
Generation dialog box.

Figure 431. Java Code Generation Dialog Box

You use this dialog box to specify

The target directory in which you want the Java code created. c:\temp\myJavaCode, for
example. If the directory you name does not exist, Stylus Studio creates it when you
run the Code Generation wizard.
The default is a \sources directory created in your Windows user data directory
C:\Documents and Settings\sula\My Documents\Stylus Studio\sources , for
example.

Optionally, a package name. If you specify a package name, this name is used for a
subfolder created in the target directory you specify. If you specify myPackage as the
package name, for example, the generated code is written to
c:\temp\myJavaCode\myPackage. (Though optional, it is considered good practice to
create a package name.)

The class name. Stylus Studio also uses the class name for the .java file created by
the Code Generation wizard. For example, if you provide the name myClass, Stylus
Studio creates c:\temp\myJavaCode\myPackage\myClass.java.
The default class name is taken from the XQuery file name.

Whether or not you want to add the generated code to the current Stylus Studio
project. If you choose to add the generated code to the project, it creates a folder using
the package name you specify and places the .java file in that folder. If you do not
specify a package name, the .java file is added directly below the project root in the
Project window.
Stylus Studio User Guide

935

Working with XQuery in Stylus Studio

Whether or not you want to embed the XQuery source in the Java code. Embedding
the XQuery source allows the Java code to run without referencing any external
sources.

How to Generate Java Code for XQuery

To generate Java code for XQuery:
1.

Open the XQuery for which you want to generate Java code.

Define at least one scenario for the XQuery. The scenario must use the Saxon or
DataDirect XQuery processor. See Scenario Properties Used for Generating Code
for more information.

Select the scenario for which you want to generate Java code.

Close the Scenario Properties dialog box.

Select XQuery > Generate Code > Generate Java Code from the Stylus Studio menu.
The Generate Java Code dialog box appears.

Figure 432. Java Code Generation Dialog Box

936

Specify the settings you want for the target directory, package and class names, and
so on. See Java Code Generation Settings if you need help with this step.

Click OK.
Stylus Studio generates Java code for the XQuery. When the code generation is
complete, the resulting file (classname.java) is opened in the Stylus Studio Java
Editor.

Stylus Studio User Guide

Generating Java Code for XQuery

Compiling Generated Code

In order to compile generated code, these JAR files must be in your system classpath:

Saxonsa.jar
ddxq.jar

These files are in the \bin directory where you installed Stylus Studio.
In addition, if your XQuery or XLST code uses DataDirect XML Converters, these JAR
files must also be in your system classpath:

/Components/XML Converters for Java/lib/XMLConverters.jar

/Components/XML Converters for Java/lib/codehaus/wstx-asl.jar

Stylus Studio ensures that these files are added to your classpath when you generate code.
If you plan to compile the generated code outside Stylus Studio, you need to modify your
system classpath yourself.

How to Compile and Run Java Code in Stylus Studio

To compile Java code in Stylus Studio:
1.

Make sure the Java Editor is the active window.

Click the Compile button (

).
Alternatives: Press Ctrl + F7, or select Java > Compile from the Stylus Studio menu.
Stylus Studio compiles the Java code. Results are displayed in the Output window.

To run Java code in Stylus Studio:

Make sure the Java Editor is the active window.

Click the Run button ( ).

Deploying Generated Code

937

Working with XQuery in Stylus Studio

Converters. Licenses for DataDirect XML Converters are purchased separately from
Stylus Studio X14 XML Enterprise Suite.
Similarly, if you use the DataDirect XQuery processor, you must acquire additional
licences if you wish to deploy your XQuery code.
Write Stylus Studio at [email protected], or call 781.280.4488 for more
information.

Generating C# Code for XQuery

C# code generation is available only in Stylus Studio XML Enterprise Suite
.
You can generate C# code for XQuery in Stylus Studio. This section describes the
generated code, scenario settings that affect the generated code, as well as procedures for
generating, compiling, and running generated code.
This section covers the following topics:

What Does Stylus Studio Generate?

Scenario Properties Used for Generating Code

C# Code Generation Settings

How to Generate C# Code for XQuery

Compiling Generated Code

Deploying Generated Code

Tip You can also generate:

Java code for XQuery. See Generating Java Code for XQuery
C# code for XSLT. See Generating C# Code for XSLT

What Does Stylus Studio Generate?

Stylus Studio generates a C# application that implements the XQuery represented by the
current XQuery using settings from the current scenario. The C# code can be compiled
and run within Stylus Studio.

938

Stylus Studio User Guide

Generating C# Code for XQuery

Scenario Properties Used for Generating Code

When you generate code for XQuery, Stylus Studio uses some of the information
associated with the active XQuery scenario, as specified in the Scenario Properties dialog
box.
The following tables summarizes the scenario properties that affect code generation.
Table 110. Scenario Properties that Affect Code Generation
Tab

Comment

General

The Code Generation wizard uses only the Source XML URL and the
Output URL field, if specified. All other properties on this page are
ignored.

Processor

Only the Saxon processor supports C# code generation for XQuery.

Note: If the scenario specifies an XQuery processor for which C# code
generation is not supported, Stylus Studio uses the Saxon processor for
code generation purposes. The processor specified in the scenario is not
changed.

Parameter Values

Parameters are always treated as XQuery expressions; they appear in the

generated code just as they are entered in the Expression field.

Profiling Options

Ignored.

Validation

You can use the following validation engines for validating your XQuery
C# code:

.NET XML Parser

Saxon

If you choose a validation engine that is not supported, Stylus Studio uses
the .NET XML parser.
Post-process

Stylus Studio User Guide

Only post-processing using Apache FOP and RenderX XEP is specified in

the generated code. Resulting PDF is written to the output URL specified
on the General tab.

939

Working with XQuery in Stylus Studio

C# Code Generation Settings

When you generate C# code for an XQuery, Stylus Studio displays the C# Code
Generation dialog box.

Figure 433. C# Code Generation Dialog Box

You use this dialog box to specify

The target directory in which you want the C# code created.

c:\temp\myPipelineC#Code, for example. If the directory you name does not exist,
Stylus Studio creates it when you run the Code Generation wizard.
The default is a \sources directory created in your Windows user data directory
C:\Documents and Settings\sula\My Documents\Stylus Studio\sources, for example.

940

Stylus Studio User Guide

Generating C# Code for XQuery

The default class name is taken from the XQuery file name.
The location of Saxon .NET on your system. Stylus Studio adds this URL to the
Microsoft Visual Studio 2005 project, allowing the generated C# code for .NET to
compile.
Whether or not you want the resulting .cs file to contain a static void Main(String
[ ] args) method.
Whether or not you want to open the generated code file. If selected, the generated C#
file is opened in whatever application is registered to open .cs files.
Whether or not you want to embed the XQuery source in the generated C# code. This
option is available when using either the Saxon XQuery or DataDirect XQuery
processors.
Note: This option appears only if you are generating XQuery code.
Whether or not you want to either create a new Visual Studio 2005 project or update
an existing one. If a new project is created, it is automatically opened with whatever
application is registered to open .csproj files. The .csproj file contains all the
necessary references to the generated .cs file, as well as all the .dll files that the .cs
file requires.
To run the .cs file, simply press Ctrl+F5 in Visual Studio.

How to Generate C# Code for XQuery

To generate C# code for XQuery:
1.

Open the XQuery for which you want to generate C# code.

Define at least one scenario for the XQuery document. The scenario must use the
Saxon processor. See Scenario Properties Used for Generating Code for more
information.

Select the scenario for which you want to generate C# code.

Close the Scenario Properties dialog box.

Select XQuery > Generate Code > Generate C# Code from the Stylus Studio menu.
The Generate C# Code dialog box appears. (See Figure 433 on page 940.)

Specify the settings you want for the target directory, namespace and class names, and
so on. See C# Code Generation Settings if you need help with this step.

Click OK.

Stylus Studio User Guide

941

Working with XQuery in Stylus Studio

Stylus Studio generates C# code for the XQuery. When the code generation is
complete, the resulting file (classname.cs) is opened in a third-party editor if you
chose the Open the generated file option.

Compiling Generated Code

The generated code contains a commented list of the DLL files required in order to
compile.

Deploying Generated Code

If your XQuery uses built-in DataDirect XML Converters to convert CSV or EDI to
XML, for example you need to purchase licenses for the DataDirect XML Converters
you wish to use if you wish to deploy your code in any environment on a machine (such
as a test or application server) that does not have a license for the DataDirect XML
Converters. Licenses for DataDirect XML Converters are purchased separately from
Stylus Studio X14 XML Enterprise Suite.
Similarly, if you use the DataDirect XQuery processor, you must acquire additional
licences if you wish to deploy your XQuery code.
Write Stylus Studio at [email protected], or call 781.280.4488 for more
information.

942

Stylus Studio User Guide

Chapter 12

Composing Web Service Calls

The Web services features described in this chapter are available only in Stylus
Studio XML Enterprise Suite.
Using Stylus Studios Web service call composer, you can design, compose, and test a
Web service call without writing any code. Once Stylus Studio composes the Simple
Object Access Protocol (SOAP) request and you have successfully tested it, you can use
the SOAP response returned by the Web service as an XML source wherever you use
XML documents in Stylus Studio.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the Web Service
Call Composer video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This chapter covers the following topics:

Overview on page 944

Obtaining WSDL URLs on page 947

Modifying a SOAP Request on page 951

Testing a Web Service on page 953

Saving a Web Service Call on page 955

Querying a Web Service on page 958

Creating XQuery from a Web Service Call on page 958

Creating a Web Service Call Scenario on page 960

Stylus Studio User Guide

943

Composing Web Service Calls

Overview
The process of composing a Web service call in Stylus Studio involves the following
steps:
1.

Specify the Web Services Description Language (WSDL) URL associated with the
Web service you want to use. See Obtaining WSDL URLs on page 947.

Compose the Simple Object Access Protocol (SOAP) request.

Select the operation described by the WSDL for which you want Stylus Studio to
compose a SOAP request.

Provide values for the SOAP request parameters.

See Modifying a SOAP Request on page 951.
b.

Test the Web service. You can test a Web service call as you composed it, or you can
create a scenario to test the Web service call using parameters of your choosing. See
Testing a Web Service on page 953.

Once you are satisfied with the Web service call, you can optionally

Save the Web service call for later use. See Saving a Web Service Call on page 955.

Create a Web service scenario. See Creating a Web Service Call Scenario on
page 960.

How to Compose a Web Service Call

To compose a Web Service call:
1.

944

From the Stylus Studio menu bar, select File > New > Web Service Call.

Stylus Studio User Guide

Overview

Stylus Studio opens a new document in the Web Service Call Composer.

Figure 434. Web Service Call Composer

Type a WSDL address in the WSDL URL field, or use the UDDI button to browse
UDDI registries for published Web services. See Obtaining WSDL URLs on
page 947 for help with this step. (Any WSDL URLs that you have used previously are
displayed in the WSDL URL drop-down list.)
Web service operations for the WSDL you select are displayed in the Operations
field.

Select the Web service operation for which you want to create a SOAP request from
the Operations field.
Parameters for the operation you select are displayed in the Name field; the datatype
for each parameter is displayed in the Type field. The SOAP request is displayed
beneath the fields you use to define the operations parameters.

Set values for the parameters:

Click the parameter name.

Stylus Studio User Guide

945

Composing Web Service Calls

Type a value in the Value field.

Stylus Studio updates the SOAP request to reflect the parameter values you enter.

Alternative: You can manually edit the XML in the SOAP request. If you do, the
Value field is updated automatically.
See Modifying a SOAP Request on page 951 for help with this step.
5.

When you have provided values for all of the parameters, click the Send Request
button (
) to test the Web service.
If it is not already open, Stylus Studio opens the Preview window and displays the
SOAP response returned by the Web service, as shown in Figure 435:

Figure 435. SOAP Response

946

Optionally, save the Web service call. See Saving a Web Service Call on page 955
for help with this step.

Stylus Studio User Guide

Obtaining WSDL URLs

Every Web service is described by a Web Services Description Language (WSDL). The
WSDL defines the format of the SOAP messages used to send requests to and receive
responses from the Web service, the transfer protocol used, namespace declarations, and
other information. Several vendors, such as IBM, Microsoft, and SAP, have established
Universal Description, Discovery, and Integration (UDDI) registries, to make Web
services publicly available.
You can locate WSDLs on your own, or you can use Stylus Studio to search UDDI
registries for published Web services.

Browsing UDDI Registries

You browse UDDI registries and search for published Web services (and the WSDLs that
describe them) using the UDDI Browser dialog box.

Figure 436. UDDI Browser Dialog Box

Stylus Studio User Guide

947

Composing Web Service Calls

The UDDI Registry field displays a list of public UDDI registries. You use the Query field
(obscured by the UDDI Registry drop-down list in the preceding illustration) to specify the
keywords you want to use to search a UDDI registry from this list. For example, if you
are building a weather application, you might type weather in the Query field to search for
weather-related Web services. Keywords are matched against the Web service and
company information available in the UDDI registry, not against the WSDL itself.
Generally speaking, the same search executed against different UDDI registries will yield
different results.
In addition to specifying keywords, the UDDI Browser dialog box allows you to

Specify whether you want to search by Web service (the default) or by provider

Limit the search results to a number or rows (the default is 100)

When you execute the search (by clicking the Search button), Stylus Studio displays
search progress in a status bar. You can stop the search at any time by clicking the Stop
button.
When the search is complete, the URLs for any WSDLs that meet your search criteria are
displayed in the Result field. For example, if you search the XMethods UDDI registry for

948

Stylus Studio User Guide

Obtaining WSDL URLs

Web services related to weather, the Stylus Studio UDDI Browser returns the following
results:

Figure 437. UDDI Browser result

When you select a WSDL URL, Stylus Studio displays the operations supported by the
Web service in the Web Service Call Composer. The first operation is selected by default,
and the SOAP request that defines it is displayed in the XML editing area. Web services
can provide multiple operations. See Modifying a SOAP Request on page 951.
If you do not see a suitable WSDL URL in the UDDI registry you searched, modify your
query in the UDDI Browser and try your search again, or search a different UDDI registry.

How to Browse UDDI Registries

To browse UDDI registries:
1.

In the Web Service Call Composer, click the UDDI button.

The UDDI Browser dialog box appears.

Stylus Studio User Guide

949

Composing Web Service Calls

950

In the UDDI Registry field, type the URL of a UDDI registry, or select a UDDI registry
from the drop-down list.

In the Query field, enter the string you want to use to search the selected UDDI
registry for available Web services.

Optionally, change the following:

Max Rows the maximum number of results you want displayed in the Results
field.

Search By whether you want to search the UDDI registry by company or by

Web service (the default).

Click the Search button.

Search progress is displayed in a status bar. When the search is complete, WSDLs that
match the search criteria you specified are displayed in the Results field.

Select the WSDL that defines the Web service operation for which you want to
compose a SOAP request and click OK.
The UDDI Browser dialog box closes and you are returned to the Web Service Call
Composer.

Stylus Studio User Guide

Modifying a SOAP Request

When you select a WSDL from the Result field in the UDDI Browser and click OK, the
operations exposed by the Web service are displayed in the Stylus Studio Web Service
Call Composer.

Figure 438. Modifying a SOAP request

When you select an operation from the Operations pane, Stylus Studio displays

Parameters associated with that operation, including their datatype and a field in
which you can enter a value for testing purposes.

The XML that describes the SOAP request associated with that operation. You can
edit the SOAP request, but for initial testing you should restrict changes to providing
parameter values, and you can use the parameters Value field for this purpose.

Understanding Parameters
Stylus Studio displays the datatype for SOAP request parameters. It is not possible to
determine all of the details for parameters, however. A zipCode parameter might take the
following:
Stylus Studio User Guide

951

Composing Web Service Calls

12309, 02134, 90210

Or it might take only a single value. Sometimes this type of information is provided in the
WSDL itself. In some cases, however, you might have to contact the Web service provider
to obtain this information.

Displaying a WSDL Document

You can easily display a WSDL document within Stylus Studio once you have specified
the WSDL URL. You might want to look at a WSDL document to learn more about the
structure of the SOAP request, or to see if the Web service provider commented the XML
to include information for developers using their Web service.
How to display a WSDL document
To display a WSDL document, click the Open WSDL Document button (
top of the Web Service Call Composer.

) near the

Stylus Studio displays the WSDL document in its own XML editor, as shown in
Figure 439:

Figure 439. WSDL document editor

952

Stylus Studio User Guide

Testing a Web Service

How to Modify a SOAP Request

To modify a SOAP request:
1.

Select the Web service operation for which you want to compose a SOAP request
from the Operations pane.
The SOAP request for the Web service operation appears in the XML editing area.

In the Name field, select a parameter and enter a value for it in the Value field.

Repeat Step 2 for any remaining parameters.

Once you have specified values for the SOAP requests parameters, you can test the Web
service. See Testing a Web Service on page 953.

Testing a Web Service

You can test a Web service from within Stylus Studio. Testing allows you to quickly and
easily

Verify whether or not the Web service is available

Understand whether or not the Web service provides the type of information you
expect and require

Learn about the SOAP response returned by the Web service

Learn how parameters you might choose to specify in a Web service call scenario
affect the Web service operation

What Happens When You Test a Web Service

When you test a Web service, Stylus Studio submits the SOAP request to the WSDL URL
specified in the Web service call. The result, when it is returned, is displayed in the
Preview window of the Web Service Call Composer.
By default, Stylus Studio uses the HTTP transport protocol to submit the SOAP request
to the WSDL server. Stylus Studio uses the proxy server specified on the local machine if
one has been configured.

Other Options for Testing a Web Service

In addition to testing a Web service as described in this section, you can also create a Web
service call scenario. Web service call scenarios allow you to

Stylus Studio User Guide

953

Composing Web Service Calls

Use transport protocols besides HTTP

Specify overrides to the WSDL (changing the SOAP action, for example)
Change default settings (such as the time out value for executing SOAP requests)

See Creating a Web Service Call Scenario on page 960 to learn more about Web service
call scenarios.

How to Test a Web Service

To test a Web service, click the Send Request button (
request.

) to submit the SOAP

Stylus Studio displays the SOAP response in the Preview window as shown in Figure 440:

Figure 440. Testing a Web service

954

Stylus Studio User Guide

Saving a Web Service Call

You can save the Web service call composed by Stylus Studio. The file created when you
save a Web service call includes the WSDL URL and the last Web service operation that
you configured (including parameter values) prior to saving the file. For example, if you
are using a Web service that provides separate operations for temperature conversions
(one for Celsius to Fahrenheit and one for Fahrenheit to Celsius, for example), only the
last one you test is saved.
Saving a Web service call gives you the ability to easily recall a preconfigured SOAP
request for additional testing allowing you to modify the SOAP request and test it
without having to locate the WSDL.
This section covers the following topics:

Using Web Service Calls as XML on page 955

Querying a Web Service on page 958

How to Save a Web Service Call on page 957

Using Web Service Calls as XML

In addition to opening a Web service call in the Web Service Call Composer for testing
purposes, you can open a Web service call as an XML document anywhere in Stylus
Studio in the XML editor, or as a source document in the XQuery mapper for example.
When you open a Web service call as an XML document, Stylus Studio automatically
executes the SOAP request and displays the SOAP response.
Consider the following Web service call, stock.wsc. The Web service operation used in
this example returns current stock quote and other information based on the ticker
symbols provided as parameters. Here is the SOAP request composed by Stylus Studio:
<?xml version="1.0" standalone="no"?>
<SOAP-ENV:Envelope xmlns:SOAPSDK1="http://www.w3.org/2001/XMLSchema"
xmlns:SOAPSDK2="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/">
SOAP-ENV:Body>
<s0:GetStockQuotes xmlns:s0="http://swanandmokashi.com/">
<s0:QuoteTicker>prgs</s0:QuoteTicker>
</s0:GetStockQuotes>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Stylus Studio User Guide

955

Composing Web Service Calls

<soap:Body>
<GetStockQuotesResponse xmlns="http://swanandmokashi.com/">
<GetStockQuotesResult>
<Quote>
<CompanyName>PROGRESS SOFT</CompanyName>
<StockTicker>PRGS</StockTicker>
<StockQuote>20.10</StockQuote>
<LastUpdated>10:17am</LastUpdated>
<Change>+0.03</Change>
<OpenPrice>20.05</OpenPrice>
<DayHighPrice>20.40</DayHighPrice>
<DayLowPrice>20.00</DayLowPrice>
<Volume>13200</Volume>
<MarketCap>695.1M</MarketCap>
<YearRange>11.50 - 24.06</YearRange>
</Quote>
</GetStockQuotesResult>
</GetStockQuotesResponse>
</soap:Body>
</soap:Envelope>

And here is the SOAP response returned by the Web service:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

956

Stylus Studio User Guide

Saving a Web Service Call

The saved Web service call can be used as the source document for an XQuery in the
XQuery mapper, as shown in Figure 441:

Figure 441. Using a Web Service Call to Compose an XQuery

XQueries composed using a Web service call as a source document return real-time data
from the Web service as a result.

How to Save a Web Service Call

To save a Web service call:
1.

Select File > Save from the Stylus Studio menu bar.
The first time you save a Web service call, the Save As dialog box appears; for
subsequent save operations, Stylus Studio displays the Save dialog box.

Change the default name (Untitled.wscc, for example), and click Save.

Stylus Studio User Guide

957

Composing Web Service Calls

Querying a Web Service

You can use the ddtek:wscall function in XQuery Mapper to query Web services. See
Using Web Services in XQuery on page 921 for more information.

Creating XQuery from a Web Service Call

You can use Stylus Studio to create XQuery from a Web service call, and then use that
XQuery to invoke the Web service. The XQuery created by Stylus Studio uses a Java
extension function, ddtek:wscall(), that allows the built-in or DataDirect XQuery
processor to execute the Web service call.
This section covers the following topics:

Example on page 958

What Happens When You Create XQuery on page 959

How to Create XQuery from a Web Service Call on page 959

Example
Consider the following StockQuotesSoap SOAP request defined using the Swan and
Mokashi WSDL:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<tns:GetQuotes xmlns:s0="http://swanandmokashi.com">
<tns:QuoteTicker>prgs</tns:QuoteTicker>
</tns:GetQuotes>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This SOAP request was created using the Stylus Studio Web Service Call Composer, as
described in How to Compose a Web Service Call on page 944.

958

Stylus Studio User Guide

Creating XQuery from a Web Service Call

The XQuery created by Stylus Studio for this Web service call looks like this:
declare namespace tns = "http://swanandmokashi.com";
ddtek:wscall(
<ddtek:location
address="http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx"
soapaction="http://swanandmokashi.com/GetQuotes"/>,
<tns:GetQuotes xmlns:tns="http://swanandmokashi.com">
<tns:QuoteTicker/>
</tns:GetQuotes>
)

What Happens When You Create XQuery

When you create XQuery from a Web service call, Stylus Studio copies the resulting
XQuery to your systems clipboard. From there, you can paste it into a new or existing
XQuery document.
See Using XQuery to Invoke a Web Service on page 919 for more information on
working with XQuery created from a Web service call.

How to Create XQuery from a Web Service Call

To create XQuery from a Web service call:
1.

Create a Web service call as described in How to Compose a Web Service Call on
page 944.

Test the SOAP request by clicking the Preview Result button, and verify that it returns
the results you require.

Click WebServiceCall > Copy XQuery to Clipboard on the Stylus Studio menu.
Stylus Studio creates XQuery based on the SOAP request and copies the XQuery
code to your systems clipboard.

Open a new XQuery document (File > New > XQuery File), and paste the clipboard
contents into the new document.

Stylus Studio User Guide

959

Composing Web Service Calls

Creating a Web Service Call Scenario

A Web service call scenario is a group of customizable settings associated with a Web
service call composition. Stylus Studio uses these settings when you test a Web service
using a scenario. If you dont define a scenario, or dont test the Web service call using a
scenario, Stylus Studio uses the settings described in the WSDL. Examples of Web
service call scenario settings include the client used to perform the Web service call; a
username and password for Web services requiring authentication; and the length of time
Stylus Studio will try to access the Web service before timing out.
You should consider creating a Web service call scenario only after you have defined the
Web service call itself. This allows Stylus Studio to inherit values for the scenario from
the WSDL you select for your Web service call.
You can create multiple scenarios that use the same Web service call, and define different
settings for each. This flexibility can aid the Web service call development process as it
enables you to easily test different Web service parameters before making the Web service
call available in your XML applications. A scenario can be associated with only one Web
service call.
This section covers the following topics:

Overview of Scenario Features

How to Create a Scenario

How to Run a Scenario

How to Clone a Scenario

Overview of Scenario Features

This section describes the main features of Web service call scenarios. It covers the
following topics:

Scenario Names

Transport Protocol and Client Settings

Other Transport Setttings

960

Stylus Studio User Guide

Creating a Web Service Call Scenario

Scenario Names
You specify a name for a Web service call scenario on the Binding tab of the Scenario
Properties dialog box.

Figure 442. Binding Tab of the Web Service Call Scenario Properties Dialog Box

When you create a Web service call scenario, specify a name that makes it easy to
distinguish one scenario from another.

Transport Protocol and Client Settings

You specify the transport protocol you want to use when testing the Web service on the
Binding tab of the Scenario Properties dialog box.
When you use HTTP as the transport protocol, the Web service call client can be any one
of the following:

Microsoft .NET

Apache Axis

Other Transport Setttings

Once you specify the client, Stylus Studio displays a list of additional settings that you
can use to define properties for the scenario. Some values, such as the time out, are system

Stylus Studio User Guide

961

Composing Web Service Calls

defaults. Others, such as the SOAP action, are taken directly from the WSDL specified in
the Web Service Call Composer.
Note Values you specify on the Binding tab override those in the WSDL displayed in the Web

Service Call Composer.

HTTP Settings
The following table describes the scenario settings associated with the HTTP transport
protocol.
Table 111. HTTP Settings
Setting
end point

Description
The server on which the Web service is executed. For example:
http://glkev.webs.innerhost.com/glkev_ws/WeatherFetcher
.asmx.

This value is taken from the current Web service call. Required.
SOAPAction

The SOAP action described by the WSDL you selected for the Web
service call. For example:
http://www.myasptools.com/GetWeather

This value is taken from the current Web service call. Required.

962

user

The username used to access the Web service if authentication is

required. Optional.

password

The password used to access the Web service if authentication is

required. Optional.

time out

The time in milliseconds until the connection to the Web service

server is dropped due to inactivity. The default is 300000 (300
seconds). Required.

Stylus Studio User Guide

Creating a Web Service Call Scenario

How to Create a Scenario

To create a scenario:
1.

Create a Web service call if you havent already. See How to Compose a Web Service
Call if you need help with this step.

Display the Scenario Properties dialog box by clicking

in the Web service
editor tool bar.
Alternative: Select Create Scenario from the scenario drop-down list at the top of the
editor window:

Figure 443. Creating a Scenario

On the General tab, specify a name for the Web service call scenario.

Click the Binding tab.

Select the appropriate transport protocol from the Transport drop-down list.

Specify the binding properties you want to associate with this Web service call
scenario.

Click OK.
The Web service call scenario is saved with the name and settings you specified.

Stylus Studio User Guide

963

Composing Web Service Calls

How to Run a Scenario

To run a scenario:
1.

Select a scenario from the scenario drop-down list at the top of the editor window:

Figure 444. Picking a Saved Scenario

Alternative:

In the Web Service Call Composer tool bar, click

.
Stylus Studio displays the Scenario Properties dialog box.

On the General tab, select the scenario you want to run from the Existing preview
scenarios list.

Click OK.

Click the Send Request button (

How to Clone a Scenario

964

Display the Scenario Properties dialog box by clicking

Composer tool bar.

in the Web Service Call

In the Existing preview scenarios field, click the name of the scenario you want to
clone.

Click Clone.

Stylus Studio User Guide

Creating a Web Service Call Scenario

In the Scenario name field, type the name of the new scenario.

Change any other scenario properties you want to change. See Overview of Scenario
Features on page 960.

Click OK.
If you change your mind and do not want to create the clone, click Delete and then
OK.

Stylus Studio User Guide

965

Composing Web Service Calls

966

Stylus Studio User Guide

Chapter 13

Working with WSDL Documents

The Web services features described in this chapter are available only in Stylus
Studio XML Enterprise Suite.
The Stylus Studio WSDL Editor lets you create, review, and modify Web Services
Description Language (WSDL) documents using graphic or text interfaces. A WSDL
document is a document written using XML that describes a Web service.
This chapter covers the following topics:

Creating a WSDL Document in Stylus Studio on page 967

Opening WSDL Documents on page 968

Using the WSDL Editor on page 969

Working with WSDL Elements on page 978

Importing WSDL Documents on page 994

Printing a WSDL Document on page 997

Saving the WSDL Diagram as an Image on page 997

Creating a WSDL Document in Stylus Studio

To create a WSDL document, select File > New > WSDL Document from the Stylus
Studio menu.

Stylus Studio displays an untitled WSDL document (untitled1.wsdl, for example) in the
WSDL Editor. (See Figure 445.) WSDL documents in Stylus Studio are saved with a
.wsdl extension.
To learn more about the WSDL Editor, see Using the WSDL Editor on page 969.
Stylus Studio User Guide

967

Working with WSDL Documents

To begin defining a WSDL, see Working with WSDL Elements on page 978.

Opening WSDL Documents

You can open WSDL documents you create in Stylus Studio (.wsdl files), as well as
WSDL documents for existing Web services, like this one from Swanand Mokashi, for
example:
http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx?WSDL

To open a WSDL document:

Select File > Open from the Stylus Studio menu.

In the Open dialog box, enter the URL for the Stylus Studio .wsdl file or the WSDL
document you want to open.
If you are opening a WSDL document that does not use a .wsdl extension, Stylus
Studio prompts you to specify the editor you want to use to open the document.

Note

968

Click OK.

Stylus Studio User Guide

Using the WSDL Editor

The WSDL Editor is a graphical and text editor that lets you review, compose, and edit
WSDL documents in Stylus Studio.

Figure 445. WSDL Editor

The WSDL Editor consists of a

Diagram pane, which contains graphical representations of the elements, attributes,

and other nodes that make up your WSDL document.

Text pane, which displays the code for the WSDL document.

Properties window, which shows properties for the selected WSDL element.

Definition browser, which allows you to quickly navigate to a specific WSDL element
or embedded XML Schema.
This section covers the following topics:

Uses for the WSDL Editor on page 970

Similarities to the XML Schema Editor on page 970

Diagram Pane on page 971

Stylus Studio User Guide

969

Working with WSDL Documents

Text Pane on page 971

Properties Window on page 972
Symbols for WSDL Elements on page 973
Displaying Documentation on page 977
Error Detection on page 977
Back-Mapping on page 977
Background Color on page 977
Moving Around the Diagram on page 978

Uses for the WSDL Editor

You can use the WSDL Editor to

Create your own WSDL documents. You might want to use the WSDL Editor during
the design stage for a new Web service to describe the services the Web service will
expose, the Web services location, and other information.

Examine WSDL documents that describe existing Web services, to see what services
are exposed, the bindings they use, the types of messages used, and so on.
These and other features of the WSDL Editor are described in greater detail in the
following sections.

Similarities to the XML Schema Editor

The WSDL Editor shares a great deal of functionality with the XML Schema Editor
Diagram tab. Main points of interest concerning the WSDL Editor are covered here. See
these topics for additional information about diagram functionality:

Introduction to the XML Schema Editor Diagram Tab

Editing Tools of the XML Schema Diagram Tab

Working with XML Schema in Stylus Studio

Note Drag-and-drop editing is not supported in the WSDL Editor.

970

Stylus Studio User Guide

Using the WSDL Editor

Diagram Pane
The diagram pane contains graphical representations of the elements, attributes, and other
nodes that make up a WSDL document, including elements from any XML Schema
associated with the WSDL.

Figure 446. WSDL Diagram Pane

Text Pane
The text pane appears below the diagram pane. The two panes are separated by a
horizontal splitter, as shown in Figure 447.

Stylus Studio User Guide

971

Working with WSDL Documents

If you want, you can display WSDL document text and the diagram at the same time,
using the splitter to change the relative size of the text and diagram panes. You use the
splitter controls to hide either the text pane or the diagram pane with single click.

Figure 447. Diagram and Text Panes in the WSDL Editor

As you edit the document, using either the diagram or text area, Stylus Studio displays
informational messages as changes are being made and when the two views are
synchronized. Text and diagram views are synchronized automatically.
The default font for text is Courier New, but you can change it to whatever font you want
by clicking the Change Font button ( ).
Tip You can control font and other aspects of the text pane, like line numbers, using the Editor
General page of the Options dialog box.

Properties Window
You use the Properties window to set values for WSDL elements.

Figure 448. Properties Window

972

Stylus Studio User Guide

Using the WSDL Editor

Not all element values can be set using the diagram pane the Binding elements transport
type, for example. You can write the necessary XML by hand in the text pane if you
choose, but it can be easier, faster, and less error-prone to set these values using the dropdown lists for Values fields in the Properties window.
Tip The Properties window is a docking window you can move anywhere on the desktop.

Symbols for WSDL Elements

Each element in a WSDL document displayed in the diagram pane is represented by its
own symbol; tool tips, which are displayed when you hover over a node in the diagram,
identify the nodes type (binding, service, and so on). The symbols used in the diagram
are summarized in Table 112.
Table 112. Symbols Used in the WSDL Diagram
Symbol

Represents

Description

Service (wsdl:service)

Names a Web service.

See The Service Element.

Types (wsdl:types)

Data type definitions required by WSDL

Messages. Typically defined using an XML
Schema (either local or referenced).
See The Types Element.

Port (wsdl:port)

Defines a single address (SOAP or HTTP) for a

Binding.
See The Port Element.

Message (wsdl:message)

The messages used by the Web service.

Contains one or more parts elements.
See The Message Element.

Part (wsdl:part)

The name and type of parameters associated

with a Message.
See The Part Element.

portType (wsdl:portType)

Describes the Messages in a Web service

operation.
See The PortType Element.

Stylus Studio User Guide

973

Working with WSDL Documents

Table 112. Symbols Used in the WSDL Diagram
Symbol

Represents

Description

Operation (wsdl:operation)

A service (a stock quote service, for example)

hosted on the Internet.
See The Operation Element.

Binding (wsdl:binding)

Specifies the protocol (SOAP or HTTP) used to

communicate with the operation.
See The Binding Element.

Input (wsdl:input)

Describes the input required by the Operation

with which the Input is associated. (A text
string representing a stock ticker, for example.)
See The Input Element.

Output (wsdl:output)

Describes the output returned by the Operation

with which the Output is associated. (A text
string representing a stock value, for example.)
See The Output Element.

Fault (wsdl:fault)

Provides error handling for a Web service

Operation. An Operation can have one or more
Faults defined for it.
See The Fault Element.

Documentation
(wsdl:documentation)

Text that describes the element. You can

associate a documentation element with any
WSDL element.
See The Documentation Element.

Nodes can be expanded and collapsed using the plus and minus symbols, respectively, that
appear on the right side of the node. In Figure 446, for example, the Part1 Message Part
has been expanded; the certifyContactRequestMessage Message has not.

Symbols for XML Schema Elements

The WSDL Editor diagram pane displays symbols for XML Schema elements if you have
a Schema element defined in your WSDL document. See Table 1 for more information

974

Stylus Studio User Guide

Using the WSDL Editor

about symbols for XML Schema elements. See The Types Element to learn more about
using XML Schema in a WSDL.

Displaying Element Details

To streamline the diagram, most elements are displayed with their details hidden by
default. You can change the settings

For all WSDL documents using the WSDL Details page on the Options dialog box.

For the current WSDL document using the Schema Diagram Properties dialog box.
Using the Schema Diagram Properties dialog box overrides the default settings set
using the Options dialog box.
The mechanics of changing display settings are the same, regardless of where you change
them. For each node property, you can choose to

Show the property

Show the property only if it is not empty (that is, it has not been defined)

Hide the node

If all of an elements properties have the same show/hide setting, that value is displayed
in the Inline Visibility in Diagram field. If no value is displayed in the Inline Visibility in
Diagram field, it means that two or more properties have different show/hide settings.
You can change the display for classes of elements (all Message Parts, for example) using
the Schema Diagram Properties dialog box, shown in Figure 449. (The Properties

Stylus Studio User Guide

975

Working with WSDL Documents

window, which appears to the left of the Diagram tab, displays all the properties for any
node you select.)

Figure 449. Schema Diagram Properties Dialog Box

To display the WSDL Details page of the Options dialog box:
1.

Select Tools > Options from the Stylus Studio menu.

Navigate the Module Settings > WSDL Editor branch and click WSDL Details.

To display the Schema Diagram Properties dialog box:

Select Diagram > Properties from the Stylus Studio menu.

Select Properties from the diagram shortcut menu.

To change element properties display:

Display the either the Schema Diagram Properties dialog box, or the WSDL Details
page of the Options dialog box.

Select the element whose properties display you want to change.

To hide all properties, click the Hide All button. To restore defaults, click the Restore
Defaults button.

Tip

976

Click OK.

Stylus Studio User Guide

Using the WSDL Editor

Displaying Documentation
By default, text associated with documentation elements (wsdl:documentation) is hidden.
You can expand documentation elements in the diagram by clicking the Show
Documentation ( ) button, or by selecting Diagram > Show Documentation from the
Stylus Studio menu. When you do, the text associated with all documentation elements
defined in the WSDL document appears.

Error Detection
Stylus Studio flags any WSDL or XML Schema errors in the text pane lines that contain
errors are identified with a red triangle, and the type and location of the error is displayed
in the status area at the top of the text pane, as shown here:

Figure 450. Text Pane Highlights WSDL Errors

When you click the error message, Stylus Studio jumps to that part of the WSDL
document containing the error. When you correct one error, information about the next
error detected by Stylus Studio (if any) is displayed in the status area.

Back-Mapping
Stylus Studio supports back-mapping between the text pane and the diagram pane if you
click an element in the diagram, Stylus Studio scrolls the text pane to display the line of
the WSDL document that defines the element you clicked. A blue triangle is displayed to
the left of the exact line of code.

Background Color
Background color is used as another visual cue for information about the WSDL
document or the XML Schema it might contain:

Stylus Studio User Guide

977

Working with WSDL Documents

A tan, or light brown, color identifies global nodes these are elements that are
defined as children of the WSDL (wsdl:definitions). In Figure 451, the
gryphonWSFault Message is an example of a such a node.
A light yellow background identifies local instances of globally defined types. In
Figure 451, the GryphonWSFault element is a local instance of that type.

Figure 451. Background Colors Show Global and Local Types

Moving Around the Diagram

There are several ways to move around the diagram pane:

To move from node to node in the diagram, press the arrow keys. (A node must
already be selected.)

You can use the scroll bars to explore the diagram; the zoom slider lets you change
the magnification.

Click Go to Definition (
) on the shortcut menu to display a new page that shows
just the type definition.

Click Display Definition (

) on the shortcut menu to jump to the place in the XML
Schema where the type is defined.

Working with WSDL Elements

This section describes how to create and manage elements in a WSDL document. It covers
the following topics:

Sample WSDL A Stock Quote Service

The Definitions Element

The Types Element

The Service Element

The Port Element

The Message Element

978

Stylus Studio User Guide

Working with WSDL Elements

The Part Element

The PortType Element
The Operation Element
The Binding Element
The Input Element
The Output Element
The Fault Element
The Documentation Element

Sample WSDL A Stock Quote Service

The examples in this section refer to the Swanand Mokashi StockQuotes Web service.
You can find the WSDL for this Web service at:
http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx?WSDL

Tip Use this URL to open the Swanand Mokashi StockQuotes WSDL in Stylus Studio.

The Definitions Element

The Definitions element (wsdl:definitions) is the root element of a WSDL document.
Stylus Studio creates the Definitions element for you when you create a new WSDL
document. (See Creating a WSDL Document in Stylus Studio.) The Definitions element
defines the set of services that the Web service offers.
You can use the Diagram > Add or the Definitions elements short-cut menu (right-click,
select Add) to define the following elements as children of the Definitions element:

Types (wsdl:types)

Service (wsdl:service)

Message (wsdl:message)

Port type (wsdl:portType)

Binding (wsdl:service)

Documentation (wsdl:documentation)

Stylus Studio User Guide

979

Working with WSDL Documents

Importing a WSDL Document

You can import one WSDL document into another. You might want to do this, for
example, if you have established a WSDL document as a repository for Messages you
want to be able to across different Web services. Once you do this, you can use elements
defined in the imported WSDL as you would locally defined elements.
See Importing WSDL Documents on page 994 for more information.

Definitions Element Properties

The following table describes the properties of the Definitions element.
Table 113. Definitions Element Properties
Name

Description

Target Namespace

The target namespace you want to associate with the Web service
described by the WSDL.

The Types Element

You use the Types element to specify the XML Schema (xsd:schema) that is used to
describe the structure of a WSDL Part.
A WSDL document can have only one Types element; it must be named types.

How to Create a Types Element

To create a Types element:
1.

Select the Definition (root) element.

Select Diagram > Add > Types from the Stylus Studio menu.
Alternative: Right-click the Definition element and choose Add > Types from the
shortcut menu.
Stylus Studio adds a Service element to the WSDL.

Types Element Properties

The Types element has no editable properties.

980

Stylus Studio User Guide

Working with WSDL Elements

Adding a Schema Element

Once you add the Types element to the WSDL, you then add one or more Schema
elements. A Schema element represents an XML Schema, and is created using the xsd
namespace by default:
<wsdl:types>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
</wsdl:types>

Once it is part of the WSDL definition, you work on a Schema element as if it were an
XML Schema in Stylus Studio. For example, you can either define the XML Schemas
elements, attributes, global types, and so on directly in the WSDL, as shown in
Figure 452, or you can use the Schema element to reference existing XML Schemas
(Diagram > Reference Schemas).

Figure 452. XML Schema Editing Features Available for Schema Elements

See Working with XML Schema in Stylus Studio on page 581 for more information about
creating XML Schema elements from scratch. See Referencing External XML Schemas
on page 636 to learn about importing and including existing XML Schemas.

How to Create a Schema Element

To create a Schema element:
1.

Select the Types element.

Select Diagram > Add > Schema from the Stylus Studio menu.
Alternative: Right-click the Types element and choose Add > Schema from the
shortcut menu.
Stylus Studio adds a Schema element to the WSDL.

Stylus Studio User Guide

981

Working with WSDL Documents

Schema Element Properties

See About xsd:schema Properties on page 649 for more information.

The Service Element

The Service element defines the Web service, and typically consists of one or more Port
elements, and an optional Documentation element. You can define a name= attribute for a
Service element (the default name is Service-0). Service elements are always created as
children of the Definitions element.

How to Create a Service Element

To create a Service element:
1.

Select the Definitions (root) element.

Select Diagram > Add > Service from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Add > Service from the
shortcut menu.
Stylus Studio adds a Service element to the WSDL. The default name is Service-0,
but you can change it.

How to Rename a Service Element

To rename a Service element:
1.

Double-click the Service element symbol in the WSDL diagram.

The name becomes editable.

Type a new name and press Enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Service name in the Value field in the Properties window.

Alternative: You can change the Service name directly in the WSDL text.

982

Stylus Studio User Guide

Working with WSDL Elements

Service Element Properties

The following table describes the properties of the Definitions element.
Table 114. Service Element Properties
Name

Description

Name

The service name. Must be unique within a WSDL document.

The Port Element

The Port element defines a single address for a Binding. Port elements are always defined
as children of the Service element. By default, Port elements are created with a SOAP
address type, but you can change it to HTTP.

How to Create a Port Element

To create a Port element:
1.

Select the Service element for which you want to describe a port.

Select Diagram > Add > Port from the Stylus Studio menu.
Alternative: Right-click the Service element and choose Add > Port from the shortcut
menu.
Stylus Studio adds a Port element to the WSDL. The default name is Port-0, but you
can change it. Port names must be unique within a given Service element.

How to Rename a Binding Element

To rename a Port element:
1.

Double-click the Port element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Port name in the Value field in the Properties window.

Alternative: You can change the Port name directly in the WSDL text.
Stylus Studio User Guide

983

Working with WSDL Documents

Port Element Properties

The following table describes the properties of the Port element.
Table 115. Port Element Properties
Name

Description

Name

The Port name. Must be unique within a given Service element.

Binding

The name of a Binding element defined in the current or an

imported WSDL. You can select existing Binding elements using
the drop-down list in the Value field in the Properties window.

Address Type

The address type (SOAP or HTTP) associated with the binding.

Creates a child element, soap:address or http:address. The
default is SOAP.

Address

Specifies the location= attribute for the Address Type element

that is, the SOAP or HTTP endpoint.

The Message Element

The Message element consists of one or more Part elements, which describe the content
of a Message using element or type attributes. Message elements are always created as
children of the Definitions element.

How to Create a Message Element

To create a Message element:

984

Select the Definitions (root) element.

Select Diagram > Add > Message from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Add > Message from the
shortcut menu.
Stylus Studio adds a Message element to the WSDL as a child of the Definitions
element. The default name is Message-0, but you can change it. Message names must
be unique within a WSDL document.

Stylus Studio User Guide

Working with WSDL Elements

How to Rename a Message Element

To rename a Message element:
1.

Double-click the Message element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Message name in the Value field in the Properties window.

Alternative: You can change the Message name directly in the WSDL text.

Message Element Properties

The following table describes the properties of the Message element.
Table 116. Message Element Properties
Name

Description

Name

The Message name. Must be unique within a WSDL document.

The Part Element

The Part element is used to describe the content of a Message element using an XML
Schema element (tns:getQuoteResponse) or as an XML Schema type (xsd:string, for
example).

How to Create a Part Element

To create a Part element:
1.

Select the Message element whose Part elements you wish to describe.

Select Diagram > Add > Message Part from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Add > Message Part
from the shortcut menu.

Stylus Studio User Guide

985

Working with WSDL Documents

Stylus Studio adds a Part element to the WSDL as a child of the Message element.
The default name is Part-0, but you can change it. Part names must be unique within
a given Message.

How to Rename a Part Element

To rename a Part element:
1.

Double-click the Part element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Part name in the Value field in the Properties window.

Alternative: You can change the Part name directly in the WSDL text.

Part Element Properties

The following table describes the properties of the Part element.
Table 117. Part Element Properties
Name

Description

Name

The Part name. Must be unique within a given Message element.

Element

Defines the Part using an XML Schema element

(tns:getQuoteResponse, for example).

Type

Defines the Part using an XML Schema (xsd:string, for

example).

The PortType Element

The PortType element describes one or more Operation elements. PortType elements are
always created as children of the Definitions element.

986

Stylus Studio User Guide

Working with WSDL Elements

How to Create a PortType Element

To create a PortType element:
1.

Select the Definitions (root) element.

Select Diagram > Add > PortType from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Add > PortType from the
shortcut menu.
Stylus Studio adds a PortType element to the WSDL as a child of the Definitions
element. The default name is portType-0, but you can change it. PortType names must
be unique within a WSDL document.

How to Rename a PortType Element

To rename a PortType element:
1.

Double-click the PortType element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the PortType name in the Value field in the Properties window.

Alternative: You can change the PortType name directly in the WSDL text.

PortType Element Properties

The following table describes the properties of the PortType element.
Table 118. PortType Element Properties
Name

Description

Name

The PortType name. Must be unique within a WSDL document.

Stylus Studio User Guide

987

Working with WSDL Documents

The Operation Element

The Operation element typically consists of an Input element and an Output element,
though they can be used individually and in different orders to support different types of
operations. For example, if you are describing

A request-response Operation (a user provides a stock quote ticker, and the Web
service returns information about that stock, for example), the Operation would
contain both Input (the stock ticker) and Output (the Web service response) elements.

A one-way Operation (a user submits information to the Web service, without a

response from the Web service), the Operation would contain an Input element.

A solicit-response Operation (the Web service contacts a client, who provides the
requested input), the Operation would contain both Output (the Web service request)
and Input (the client response) elements.

A notification Operation (the Web service emits output, with no response required or
expected), the Operation would have a single Output element.
An optional Fault element can be used for error handling in both request-response and
solicit response Operation models.

Operation Element Code Sample

The structure of an Operation element might look like this:
<wsdl:operation name="Operation-0">
<wsdl:input/>
<wsdl:output/>
<wsdl:fault/>
</wsdl:operation>

How to Create an Operation Element

To create an Operation element:

988

Select the PortType element.

Select Diagram > Add > Operation from the Stylus Studio menu.
Alternative: Right-click the PortType element and choose Add > Operation from the
shortcut menu.
Stylus Studio adds an Operation element to the WSDL as a child of the PortType
element. The default name is Operation-0, but you can change it. Operation names
are not required to be unique.

Stylus Studio User Guide

Working with WSDL Elements

How to Rename an Operation Element

To rename an Operation element:
1.

Double-click the Operation element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Operation name in the Value field in the Properties window.

Alternative: You can change the Operation name directly in the WSDL text.

Operation Element Properties

The following table describes the properties of the Operation element.
Table 119. Operation Element Properties
Name

Description

Name

The Operation name.

The Binding Element

The Operation element typically consists of an Input element and an Output element,
which, using Message and Part elements, describe the input required by the operation (a
ticker symbol, for example) and the output returned by it (a stock value, for example).

How to Create a Binding Element

To create a Binding element:
1.

Select the Definitions (root) element.

Select Diagram > Add > Operation from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Add > Operation from
the shortcut menu.

Stylus Studio User Guide

989

Working with WSDL Documents

Stylus Studio adds a Binding element to the WSDL as a child of the Definitions
element. The default name is Binding-0, but you can change it. Binding names must
be unique within a WSDL document.

How to Rename a Binding Element

To rename a Binding element:
1.

Double-click the Binding element in the WSDL diagram.

The name becomes editable.

Type a new name and press enter.

Alternative: Using the Properties window

Display the Properties window if it is not already open. (View > Properties).

Change the Binding name in the Value field in the Properties window.

Alternative: You can change the Binding name directly in the WSDL text.

Binding Element Properties

The following table describes the properties of the Binding element. Note that properties
vary based on the binding type.
Table 120. Binding Element Properties
Name

Description

Name

The Binding name. Must be unique within a WSDL document.

Type

The PortType element associated with this Binding.

Binding Type

The communication protocol to be used by the binding. Valid

values are soap or http.

Transport

The WSDL binding for the SOAP protocol. The default value is
http://schemas.xmlsoap.org/soap/http. Sets the transport=
attribute for the soap:binding sub-element.
Note: This field is visible only the Binding Type property is set
to soap.

990

Stylus Studio User Guide

Working with WSDL Elements

Table 120. Binding Element Properties
Name

Description

Style

The structure for the contents of the SOAP body. Valid values are
document (unstructured) or rpc (Remote Procedure Style). Sets the
style= attribute for the soap:binding sub-element.
Note: This field is visible only the Binding Type property is set
to soap.

Method

The type of HTTP method used by the binding. Valid values are
GET and POST. Sets the verb= attribute for the http:binding subelement.
Note: This field is visible only the Binding Type property is set
to http.

The Input Element

Within an Operation element, the Input element is the message that is sent to the Web
service from the client. (The Output element is the message returned to the client in
request-response Operations.) An Operation may have only one Input element.
See The Operation Element for more information.

How to Create an Input Element

To create an Input element:
1.

Select the Operation element whose Input element you want to describe.

Select Diagram > Add > Input from the Stylus Studio menu.
Alternative: Right-click the Operation element and choose Add > Input from the
shortcut menu.
Stylus Studio adds an Input element to the WSDL as a child of the Operation element.
The default name is Input, and you cannot change it.

Stylus Studio User Guide

991

Working with WSDL Documents

Input Element Properties

The following table describes the properties of the Input element.
Table 121. Input Element Properties
Name

Description

Message

The Message associated with this Input element.

The Output Element

Within an Operation element, the Output element is the message that is returned to the
client from the Web service. (The Input element is the message sent by the client to the
Web service, typically initiating a request in a request-response Operation.) An Operation
may have only one Output element.
See The Operation Element for more information.

How to Create an Output Element

To create an Output element:
1.

Select the Operation element whose Output element you want to describe.

Select Diagram > Add > Output from the Stylus Studio menu.
Alternative: Right-click the Operation element and choose Add > Output from the
shortcut menu.
Stylus Studio adds an Output element to the WSDL as a child of the Operation
element. The default name is Output, and you cannot change it.

Output Element Properties

The following table describes the properties of the Output element.
Table 122. Output Element Properties

992

Name

Description

Message

The Message associated with this Output element.

Stylus Studio User Guide

Working with WSDL Elements

The Fault Element

Within an Operation element, the Fault element is used for error handling, typically with
the Web service sending a message to the client.
See The Operation Element for more information.

How to Create a Fault Element

To create a Fault element:
1.

Select the Operation element whose Fault element you want to describe.

Select Diagram > Add > Fault from the Stylus Studio menu.
Alternative: Right-click the Operation element and choose Add > Fault from the
shortcut menu.
Stylus Studio adds a Fault element to the WSDL as a child of the Operation element.
The default name is Fault, and you cannot change it.

Fault Element Properties

The following table describes the properties of the Fault element.
Table 123. Output Element Properties
Name

Description

Message

The Message associated with this Fault element.

The Documentation Element

The Documentation element is an optional element you can use to provide humanreadable information about any element in a WSDL. You might use a Documentation
element to describe an Operation or Message, for example.

How to Create a Documentation Element

To create a Documentation element:
1.

Select the WSDL element you want to document.

Select Diagram > Add > Documentation from the Stylus Studio menu.

Stylus Studio User Guide

993

Working with WSDL Documents

Alternative: Right-click the element and choose Add > Documentation from the
shortcut menu.
Stylus Studio adds a Documentation element to the WSDL element you selected in
Step 1. It appears in the Text pane as:
<wsdl:documentation>Documentation goes here</wsdl:documentation>
3.

Change Documentation goes here to whatever you choose.

Documentation Element Properties

The Documentation element has no editable properties.

Importing WSDL Documents

By importing one WSDL document into another, you can easily reuse elements that have
been defined in other WSDLs, rather than redefining elements locally.
You import WSDLs at the Definitions (root) element.
To import a WSDL document:
1.

Select the Definitions (root) element.

Select Diagram > Imported Files from the Stylus Studio menu.
Alternative: Right-click the Definitions element and choose Imported Files from the
shortcut menu.
Stylus Studio displays the Imported Files dialog box.

Figure 453. Imported Files Dialog Box

If the WSDL you are editing already has imported WSDL documents (wsdl:import),
they are listed here.
994

Stylus Studio User Guide

Importing WSDL Documents

Click the Add button.

Stylus Studio displays the Import File dialog box.

Figure 454. Import File Dialog Box

Enter a URL for the WSDL document you want to import, or use the more button
( ) to display the Open dialog box, which allows you to navigate your file systems.

Click OK.
The Import Files dialog box closes, and you are returned to the Imported Files dialog
box. The WSDL document you selected appears in the Files imported by the
document list box.

Click the Add button to import another WSDL; otherwise, click OK.
The Imported Files dialog box closes.

Making Imported WSDL Elements Available

In order to make elements of an imported WSDL available in the local WSDL document,
you need to load them into the local WSDL.
To make an imported WSDL available, select Diagram > Load All Schemas.

All imported XML Schema and WSDL documents are now available in the local WSDL.

Stylus Studio User Guide

995

Working with WSDL Documents

Example
In this example, we have imported the WSDL my_StockQuotes.wsdl into our local WSDL.
This WSDL is a copy of the Swanand Mokashi StockQuotes.wsdl. When imported, Stylus
Studio creates the following:
<?xml version="1.0"?>
<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:auto9="http://swanandmokashi.com">
<wsdl:import namespace="http://swanandmokashi.com"
location="file:///w:/testing/my_StockQuotes.wsdl"/>
</wsdl:definitions>

In addition to the default xmlns:xsd and xmlns:wsdl namespaces created with the
Definitions elements, notice that the xmlns:auto9 namespace has been added.
Now, if we load the imported WSDL and then create a Binding element, we see that the
Type property drop-down list contains several types with the auto9 namespace prefix:

Figure 455. Elements Defined in an Imported WSDL

996

Stylus Studio User Guide

Printing a WSDL Document

In addition, the imported WSDL now appears in the definitions browser.

Figure 456. Definition Browser Shows Imported WSDL

Printing a WSDL Document

To print a WSDL document:

Select the pane in the WSDL Editor you want to print.

Click Print
.
Alternative: Select File > Print from the Stylus Studio menu.

Saving the WSDL Diagram as an Image

You can save a graphical image of your WSDL diagram as a JPEG (.jpg) file or as an
Extended Meta File (.emf). When you save a WSDL as an image, Stylus Studio includes
the entire WSDL diagram, not just what is currently visible.
Stylus Studio uses a standard zoom level when saving the image; application zoom level
settings are ignored.

Stylus Studio User Guide

997

Working with WSDL Documents

To save a WSDL diagram as an image:

Select Diagram > Export Image from the menu, or select Export Image from the
shortcut menu on the diagram pane (right-click).
Stylus Studio displays the Save As dialog box.

998

Select the file format (.jpg or .emf) from the Files of type drop-down list.

Specify a name and location for the file and click the Save button. The default name
is the name of the WSDL document; the default location is the folder in which the
WSDL document has been saved.

Stylus Studio User Guide

Chapter 14

Building XML Pipelines

This chapter describes XML pipelines, and how to use the Stylus Studio XML Pipeline
Editor to create, debug, and maintain XML pipelines. It also describes how to generate
Java code you can use to embed XML pipelines in Java applications.
Support for XML pipelines is available only in Stylus Studio XML Enterprise Suite.

Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XML Pipeline
Editor video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This chapter covers the following topics:

What is an XML Pipeline? on page 1000

The XML Pipeline Editor on page 1003

Steps for Building an XML Pipeline on page 1006

Planning an XML Pipeline on page 1007

Use Case: Building order.pipeline on page 1014

Working with Nodes on page 1040

Working with the XML Pipeline Diagram on page 1059

Debugging an XML Pipeline on page 1065

Generating Code for an XML Pipeline on page 1069

XML Pipeline Node Properties Reference on page 1076

Stylus Studio User Guide

999

Building XML Pipelines

What is an XML Pipeline?

In Stylus Studio, an XML pipeline is an application that performs a series of operations
based on the inputs, transformations, and outputs described in the XML Pipeline Editor.
In Stylus Studio, an XML pipeline has a

Graphical representation consisting of nodes that represent data sources, processing

operations, and pipes that represent the processing flow (shown in Figure 457)

A code representation (once you generate code for it) for these data sources, nodes,
and pipes

Example of an XML Pipeline in Stylus Studio

Figure 457 shows the diagram that represents getHoldings.pipeline, which is in the
pipelines\stocks folder in the examples project installed with Stylus Studio.

Figure 457. Diagram of getHoldings.pipeline

This particular XML pipeline:

Aggregates two XML input sources

Validates the output of the XQuery using XML Schema and then either
1000

Stylus Studio User Guide

What is an XML Pipeline?

Terminates if the validation fails or

Passes the output to an embedded pipeline for additional processing

Using XSLT, transforms the embedded pipelines output to HTML
Using XQuery, transforms the same output to PDF using XSL-FO processing

XML Pipeline Terminology

Understanding the following terms will help you work with XML pipelines in Stylus
Studio.
Table 124. XML Pipeline Terminology
Term

Description

Node

Generally, an XML pipeline operation. In an

XML pipeline diagram, the glyph that
represents an XML pipeline operation.
Examples include XSLT, XQuery, Pipeline, and
Validate.

Input
port

The circle on top of some nodes used to receive

a pipe from an output port. A node can have
more than one input port.

Stylus Studio User Guide

Example

1001

Building XML Pipelines

Table 124. XML Pipeline Terminology
Term

Description

Output
port

The triangle on the bottom of some nodes used

to connect to an input port using a pipe. A node
can have more than one output port.

Pipe

The conceptual name for the line that connects

two nodes, from the output port on one, to the
input port on the other.

Example

XML Pipeline Semantics

The following semantics govern the behavior of an XML pipeline:

A node is executed only when all its input ports are filled.

A nodes input port is filled either when it contains a default value that is a reference
to a URL or a literal value, or when it is connected to another nodes output port and
this node provides data that is available. Default values are used only if no pipe is
present for that port.

When data is available on a nodes output port, it is provided to the input ports of all
the nodes to which it is connected.

A nodes input port can be filled by 0 or 1 value. If more than one value becomes
available, this is an error and XML pipeline processing aborts.

1002

Stylus Studio User Guide

The XML Pipeline Editor

The XML Pipeline Editor is the visual editing tool you use to create, execute, and debug
XML pipelines in Stylus Studio.

Figure 458. Example of an XML Pipeline in the XML Pipeline Editor

You build an XML pipeline in the XML Pipeline Editor using simple drag-and-drop
actions to add an XQuery query to an XML pipeline, for example, you can drag an
XQuery file from the Project window and drop it on the XML Pipeline Editor canvas. You
can also use tools from the Toolbox pane to add nodes to your XML Pipeline. The
Properties window allows you to specify settings for the node (default input and output
values, for example).
You can also use the XML Pipeline Editor to

Execute the XML pipeline and preview its output

Generate Java code for an XML pipeline

Create an image of the XML pipeline diagram

Stylus Studio User Guide

1003

Building XML Pipelines

This section covers the following topics:

Parts of the XML Pipeline Editor on page 1004

XML Pipeline Editor Toolbar on page 1005

Menu Actions on page 1006

Parts of the XML Pipeline Editor

The XML Pipeline Editor has three main parts, shown in Figure 458:

The XML pipeline canvas, on which you compose the operations and the flow of your
XML pipeline and work with the resulting XML pipeline diagram. See Working
with the XML Pipeline Diagram on page 1059 for more information.

The Toolbox pane contains the tools you use to add transformation, flow control, and
data source operations to your XML pipeline. Operations you add using toolbox tools
are not yet tied to an implementation you need to specify them by setting values in
the Properties window. See Adding Nodes to an XML Pipeline on page 1040 for
more information.

The Properties window, which displays information about the operations in your
XML pipeline. Some default values are provided by Stylus Studio; if you create an
operation by dragging a document from the Project window and dropping it on the
canvas, however, some of that documents information is used to specify property
settings for the operation. For example, if you drag and drop an XQuery document in
the XML pipeline, the .xquery file property is based on the documents URL. See
XML Pipeline Node Properties Reference on page 1076 for more information on
properties for individual nodes.

1004

Stylus Studio User Guide

The XML Pipeline Editor

XML Pipeline Editor Toolbar

The XML Pipeline Editor toolbar provides easy access to operations you are likely to
perform while building XML pipelines and working with XML pipeline diagrams in
Stylus Studio. Figure 459 identifies the toolbars tools.

Figure 459. XML Pipeline Editor Toolbar Buttons

Many of these operations are also available from the XMLPipeline menu and canvas shortcut menu (right-click to display). See Menu Actions on page 1006 for more
information.
Table 125. Toolbar Button Descriptions
Toolbar Button

Description

Execute

Executes the current XML pipeline and displays the results in the
Preview window. Output (error and warning messages, for
example) appear in the Output window.

Generate Java Code

Generates Java code for the current XML pipeline.

Select Scenario

Allows you to choose the XML pipeline scenario for execution and
code generation.

Display Scenario
Properties

Displays the Scenario Properties dialog box, which allows you to

create and define properties for XML pipeline scenarios.

Show Grid

Shows (or hides) the grid that appears on the XML Pipeline Editor
canvas.

Stylus Studio User Guide

1005

Building XML Pipelines

Table 125. Toolbar Button Descriptions
Toolbar Button

Description

Snap to Grid

Allows you to choose whether you want objects to be placed

automatically on the closest grid line (snap), or whether you want to
be able to place them anywhere on the grid you choose. Snap to grid
is off by default.

Rotate Ports CounterClockwise

Allows you to rotate the ports on the selected node counterclockwise.

Rotate Ports Clockwise

Allows you to rotate the ports on the selected node clockwise.

Zoom

Zooms the XML Pipeline diagram on the canvas.

Save Image

Saves the entire XML Pipeline diagram (not just what is visible on
the canvas) to an image file.

Menu Actions
In addition to the actions you can perform using the toolbar (see XML Pipeline Editor
Toolbar on page 1005), the XMLPipeline menu and canvas short-cut menu provide the
following actions.
Table 126. Menu Action Descriptions
Menu Action

Description

Add Label/Remove
Label

Allows you to add (and remove) labels from the XML pipeline
diagram.

Edges Style

Lets you choose line, orthogonal, or spline styles for the pipes in the
XML pipeline diagram.

Remove Selection

Removes the selected node or pipe from the XML pipeline.

Steps for Building an XML Pipeline

The process for building an XML pipeline consists of these basic steps:
1.

1006

Gather the requirements for the XML pipeline and select a design approach. You need
to understand the XML pipelines desired output, and perhaps which XML

Stylus Studio User Guide

Planning an XML Pipeline

technologies (XQuery or XSLT, for example) need to be used. See Planning an XML
Pipeline on page 1007.
2.

Identify and/or define the source documents and resources required to execute your
XML pipeline.

Create an XML pipeline document. See Getting Started: Creating a New XML
Pipeline on page 1016.

Optionally, set deployment and processor properties. See XML Pipeline Scenarios
on page 1017.
You can do this step any time prior to previewing and debugging the XML pipeline.

Note
5.

Create and specify the XML pipeline nodes. You can create empty nodes and specify
them manually, or you can create them using XQuery, XSLT, XML Schema, and other
documents. See Working with Nodes on page 1040.

Use pipes to connect the nodes in your XML pipeline.

Test the XML pipeline. See Testing the XML Pipeline on page 1030.

Debug the XML pipeline as needed. See Debugging an XML Pipeline on

page 1065.

Once you are satisfied that the XML pipeline is running as it should, you can optionally
generate Java code. See Generating Code for an XML Pipeline on page 1069 for more
information.

Planning an XML Pipeline

This section describes some of the considerations you might want to make when planning
an XML pipeline which design approach to take, the components you can include in a
pipeline, and more.
This section covers the following topics:

Design Approaches on page 1008

XML Pipeline Components on page 1010

Identifying Resources on page 1013

Deployment Considerations on page 1014

Steps for Building an XML Pipeline on page 1006

Stylus Studio User Guide

1007

Building XML Pipelines

Design Approaches
Stylus Studio supports bottom-up and top-down approaches to designing XML pipelines.
The approach you take depends largely on personal preference, but it can also be
influenced by factors such as whether, for example, your XML pipeline will use existing
transformations (like XQuery or XSLT) or you will build them specifically for use in the
XML pipeline.
The following section is intended to give you some ideas for XML pipeline design.

Understand the Requirements

Regardless of which approach you choose, you should understand the goal of the XML
pipeline before you start building it. For example, you should know

What the desired output is. Is it HTML? XSL-FO? Both? Or will the XML pipeline
return data to a format other than XML?

If the XML pipeline is intended to stand alone, or whether it will be included in other
XML pipelines.
For the purposes of describing bottom-up and top-down design approaches in this section,
imagine that the requirement for our XML pipeline is to reder data in a text file as PDF.

Bottom-Up Design
In a bottom-up design approach, you already have the individual components, or most of
them, that you will link together to form your XML pipeline. If we were using a bottomup design approach to create an XML pipeline for the use case described in Understand
the Requirements on page 1008, we would:

Have a source .txt file (a comma-separated values file) identified.

Use a built-in Stylus Studio converter to convert this file to XML.

Have an XQuery file that transforms this XML to XSL-FO and performs FO postprocessing to create PDF.
Using a bottom-up design approach, we would then use these source files to build our
XML pipeline using the following steps:

1008

Create a new XML pipeline document.

Create a ConvertToXML node to handle the conversion of CSV to XML. We would

specify the source .txt file as the ConvertToXML nodes input, and choose the
Comma-Separated Values built-in converter to convert the text to XML.

Stylus Studio User Guide

Planning an XML Pipeline

Drag our XQuery document from the File Explorer or Project window and drop it on
the XML pipeline canvas. This would automatically create and specify the XML
pipelines XQuery node for our XML pipeline. Also, because the XQuery was
defined to perform XSL-FO post-processing, Stylus Studio automatically would
create an XSL-FO node in the XML pipeline.

Connect the output port from the ConvertToXML node to the input port of the
XQuery node. This instructs the XML pipeline to use the converted text file (now
XML) as input for the XQuery transformation.

Specify a URL for the XSL-FO nodes output port.

When you use a bottom-up approach, Stylus Studio leverages as much of the existing
information in the documents you use to build the XML pipeline as possible. Depending
on your design environment, you might need to alter the paths specified for input and
output nodes, source documents, and so on, and you will typically have to link the nodes
in your XML pipeline by creating pipes between appropriate output and input nodes.

Top-Down Design
When you use a top-down design approach, you do not have any pre-existing components
XSLT or XQuery documents, for example or they might not be completely specified.
In this situation, you use the XML Pipeline Editor to sketch a design, and then fill in the
details once you have them. Returning to the use case described in Understand the
Requirements on page 1008, we would sketch our XML pipeline by:
1.

Creating a new XML pipeline document.

Dragging a ConvertToXML icon from the Toolbox pane and dropping it on the
canvas.

Dragging an XQuery icon from the Toolbox pane and dropping it on the canvas.

Dragging an XSL-FO icon from the Toolbox pane and dropping it on the canvas.

Connecting the ConvertToXMLs output port to the input port of the XQuery node.

Connecting the XQuery nodes output port to the input port of the XSL-FO node.

The top-down approach results in a rough outline of placeholder nodes of the desired
XML pipeline an abstract or conceptual representation of the code we want to generate
to perform XML processing. The next steps would be to:
1.

Identify the source document for the ConvertToXML node, and selecting the built-in
Stylus Studio converter to be used to convert that source files data to XML.

Stylus Studio User Guide

1009

Building XML Pipelines

Creating an XQuery document that

Transforms the XML input from the ConvertToXML node to PostScript

Generates the XSL-FO grammar to convert the PostScript to PDF

Once these documents are created, they can be used to define nodes that represent them
in the XML pipeline. You can do this

Manually, by specifying node properties in the Properties window

Automatically, by dragging and dropping documents onto the placeholder nodes that
represent them

XML Pipeline Components

Every XML pipeline consists of a number of components that represent some aspect of
XML processing. Typically, an XML pipeline will contain components that represent

XML transformations (such as XQuery or XSLT)

Source documents and data (an XML, or XML data provided by a Web service, for
example)

A flow that identifies the processing stages performed in the XML pipeline (whether
XML output goes directly to an XSLT transformation for processing, or is first
validated using XML Schema, for example)
You also specify values for the input and output ports on these nodes, which determines
the flow of the processing defined in the XML pipeline.
This section reviews the components you can include in an XML pipeline.

Transformations
A transformation is an operation that takes an input, performs an action on it, and returns
an output. Examples of XML transformations include XQuery and XSLT. Transformation
output can be a finished product XSLT that creates an HTML report, for example or
it can be something that is passed along to another operation for additional processing
XQuery that specifies FO post-processing of the XML it generates, or output passed to an
XML Schema for validation, for example.
You can include the following transformations in an XML pipeline in Stylus Studio:

XQuery standard XQuery query, including scenario properties

XSLT standard XSLT transformation, including scenario properties

XSL-FO XSL-FO processing of XML using Apache FOP or RenderX XEP

1010

Stylus Studio User Guide

Planning an XML Pipeline

Pipeline include one pipeline in another

Stylus Studio User Guide

1011

Building XML Pipelines

XML Parser converts text input to XML

XML Serializer converts XML input to text

Flow Control
Flow control nodes control the flow of an XML pipeline. For example, you might choose
to use a Stop node to display a message when the XML pipeline encounters an error
condition such as when it requires an XML document fails validation against its XML
Schema.
You can use the following nodes to control the flow of an XML pipeline in Stylus Studio

Choose one or more IF conditions, and an ELSE condition

Stop stops XML pipeline processing, if, for example, generated XML does not
validate against a given XML Schema

Validate uses XML Schema to validate XML

Warning displays a warning message in output, but allows XML pipeline processing
to continue

Data Sources
Data source nodes are used to specify the XML data that is to be processed. For example,
your XML pipeline might begin by processing raw XML, or it might require that nonXML data (such as a text file or a relational table) first be converted to XML prior to
additional processing.
You can use the following nodes to specify data sources in an XML pipeline:

ConvertToXML specifies an operation that converts a flat file (CSV, binary, and so
on) or EDI message type to XML.

ConvertFromXML specifies an operation that converts XML to some other format

(CSV, binary, and so on).

Pipeline Input specifies an external input to an XML pipeline that includes the XML
pipeline in which this node is defined.

Pipeline Output specifies an external outout to an XML pipeline that includes the
XML pipeline in which this node is defined.
Tip You can also provide a data source by specifying the Default Value property on that

nodes input port. For example, you could specify the URL of an XML document in this
way.

1012

Stylus Studio User Guide

Planning an XML Pipeline

Input and Output Ports

XML pipeline nodes are connected to each other by one or more pipes. The pipes
represent the flow of XML data from one operation or transformation in the XML pipeline
to another. Pipes connect to a nodes input and output ports, which are found on most
nodes representing XML pipeline components. (Not all nodes have both input and output
ports.)

You use the input port to specify the expected source for the node. You can specify a
default value, or you can connect another nodes output port to it with a pipe. For
example, you might specify the input port for an XQuery node using the URL for an
XML document, or as the output from a ConvertToXML node. If a pipe is connected
to an input port, any default value is ignored.

You use the output port to specify what to do with result from the nodes processing.
You can also specify output ports explicitly or implicitly. For example, you might
specify the URL to which you want the output of a node be copied, you might link the
output to a Validate nodes input port, or you might do both.
You specify the flow of an XML pipelines processing by linking one nodes output port
to another nodes input port.

Identifying Resources
When planning your XML pipeline, you should consider the resources you will require in
order to build it. These include

Source documents for any XQuery and XSLT transformations the XML pipeline will
use, XML Schema used for validation, and so on

Data sources, whether an XML document, data converted from a relational database
or flat file to XML, or XML data returned by a Web service, for example
You should pay particular attention to where these resources will be relative to the
finished XML pipeline when it is being run in its production environment. For example,
if you are using a Web service or relational database that requires some type of
authentication, you need to ensure that the finished application that makes use of your
XML pipeline code includes some means of providing authentication. Similarly, you need
to ensure that the paths of source documents, data sources, and output URLs will be
accessible to the finished application, or that your application provides a way to enter this
information at run-time.

Stylus Studio User Guide

1013

Building XML Pipelines

Deployment Considerations
When you are finished building and testing your XML pipeline, you will want to generate
the code that executes the XML pipeline so that you can incorporate it in an application
that uses the XML processing it defines.
In order to do this, you need to understand the environment in which the XML pipelines
application will be run and model that environment in Stylus Studio. For example, your
XML pipeline might be required to use a given XML Schema validation engine, or a
specific XQuery or FO processor, so you should plan for these requirements when
designing your XML pipeline.
You choose the processors you want the components in your XML pipeline to use by
specifying the Execution Framework settings on the Deployment page of the Scenario
Properties dialog box.
Tip You can create multiple scenarios for the same XML pipeline and specify different

execution frameworks for each.

See Specifying an Execution Framework on page 1017 for more information.

Use Case: Building order.pipeline

This section describes the steps you might use to build the XML pipeline order.pipeline.
This XML pipeline is in the pipelines\order folder in the examples project installed with
Stylus Studio.
This section covers the following topics:

order.pipeline Requirements on page 1015

Getting Started: Creating a New XML Pipeline on page 1016

XML Pipeline Scenarios on page 1017

Specifying an Execution Framework on page 1017

Configuring Data Sources on page 1018

Using XQuery to Merge Source File Data on page 1023

Adding an XQuery Node on page 1028

Setting the XQuery Node Data Sources on page 1029

Testing the XML Pipeline on page 1030

Setting a Value for an Output Port on page 1030

Designing a Report from the XML Document on page 1032

1014

Stylus Studio User Guide

Use Case: Building order.pipeline

Adding XSLT and XQuery Transformations on page 1034

Finishing Up on page 1039

order.pipeline Requirements
An organization in our enterprise has requested a report listing book orders, like the one
shown in Figure 460. The report must be available in both HTML and PDF formats. The
source for the book order data is an EDIFACT message; inventory information is
contained in a text file.

Figure 460. Sample Report Output Required for order.pipeline

The report consists of a table that lists the ISBN, title, and quantity of books that have been
ordered from inventory.

Stylus Studio User Guide

1015

Building XML Pipelines

Getting Started: Creating a New XML Pipeline

This section describes how to create a new XML pipeline document and some of the
default behaviors for new XML pipelines.
To create an XML pipeline, select File > New > XML Pipeline from the Stylus Studio
menu.

When you create an XML pipeline, Stylus Studio displays a new .pipeline document in
the XML Pipeline Editor. The document has a name of untitledn.pipeline, where n is a
unique number.

Figure 461. New XML Pipeline Document

Save the XML Pipeline

Click the Save button (
example).

1016

) and save the new XML pipeline (as myOrders.pipeline, for

Stylus Studio User Guide

Use Case: Building order.pipeline

XML Pipeline Scenarios

The XML pipeline document is associated with a default scenario, Scenario1. A scenario
contains default deployment and processor settings that are used when

Executing the XML pipeline in Stylus Studio

Debugging the XML pipeline in Stylus Studio

Generating code for the XML pipeline

You can define multiple scenarios using different settings to see how each affects XML
pipeline processing.

Specifying an Execution Framework

To help you manage processor settings for the XQuery, XSLT, XML Schema validation,
and FO processing operations in your XML pipeline, Stylus Studio lets you specify an
execution framework in the Scenario Properties dialog box.

Figure 462. Execution Framework Settings for an XML Pipeline

Each execution framework is associated with a pre-set collection of compatible

processors. You can

Change the execution framework to use a different set of processors.

Change the settings for individual processors within an execution framework. Any
changes you make to settings within an execution framework affect the current
pipeline only, and not the execution frameworks default settings.
Tip Stylus Studio displays information about whether or not it can generate code based on the

current processor settings.

Stylus Studio User Guide

1017

Building XML Pipelines

When to Specify the Execution Framework

If the production or deployment environment anticipated for the XML pipeline uses
different processors than those specified in the default execution framework, you should
consider changing these settings early in the XML pipelines development phase. Doing
so will enable you to preview and debug the XML pipelines performance and output in
an environment that models the production environment as closely as possible. In any
event, you need to make sure that the Processor settings on the Deployment page of the
Scenario Properties dialog box are set appropriately prior to generating code for your
XML pipeline. See Generating Code for an XML Pipeline on page 1069 for more
information on this topic.

Configuring Data Sources

The source for the information required for the desired report comes from two files:

A flat file, booksXML.txt, that contains ISBN, title, manufacturer, and release date
information for every book in inventory.

An EDI file, order.edi, that contains title, ISBN, and quantity information for every
book currently on order.
Neither of these files provides data in XML format, so they will have to be converted to
XML. We will use built-in DataDirect XML Converters for this task.

Ways to Configure Non-XML Data Sources

You use ConvertToXML nodes to specify a non-XML data source in an XML pipeline.
There are two ways to do this:

Convert the source file using a built-in DataDirect XML Converter or a user-defined
custom XML conversion, and then drag the resulting document and drop it on the
XML pipeline canvas.

Create the ConvertToXML node in the XML pipeline using the Toolbox, and then
specify the source file and the DataDirect XML Converter or user-defined custom
XML conversion you want to use to convert it to XML.
While both require a similar number of steps, converting a source file can be more
economical as it creates a resource that you can reuse in the XML pipeline, and elswhere
in Stylus Studio. Both procedures are described in the following sections.

1018

Stylus Studio User Guide

Use Case: Building order.pipeline

Convert booksXML.txt Using a Built-in XML Converter

To convert booksXML.txt using a built-in XML Converter:
1.

Select File > Open from the menu.

The Open dialog box appears.

Navigate to the examples\pipeline\order folder where you installed Stylus Studio.

Change the Files of type field to All

Select booksXML.txt.

Select the Open using XML Converter check box at the bottom of the Open dialog
box.

Click Open.
Stylus Studio displays the Select XML Converter dialog box.

Select the Comma-Separated Values converter.

The booksXML.txt source file happens to use a vertical bar (|) as its separator character.

Files.

To view the source .txt and .edi files, double-click them in the Project window to
display them in a Stylus Studio editor.

Tip

Figure 463. Select XML Converter Dialog Box

Change the value in the Separator property to a vertical bar (|).

Change the value in the First row contains field names to Yes.

Stylus Studio User Guide

1019

Building XML Pipelines

10.

Click OK.
The booksXML.txt file appears in the Other Documents folder in the Project window.
If you hover the mouse pointer over the file name, you will see the full specification
of the XML Converter URL used to convert it.

11.

Drag booksXML.txt and drop it on the XML pipeline canvas.

Stylus Studio creates a ConvertToXML node with its input port already specified.

12.

Go to Create a ConvertToXML Node for order.edi on page 1022.

Create a ConvertToXML Node for booksXML.txt

To create XML data from a non-XML Source in the XML Pipeline Editor:
1.

Drag the ConvertToXML icon from the Toolbox pane and drop it on the XML
pipeline canvas.
Stylus Studio creates a ConvertToXML node and displays it in the XML pipeline
diagram.

Display the Properties window (View > Properties) if it is not already open.

Display the Project window (View > Project) if it is not already open.

Click the input port on the ConvertToXML node.

The properties for the input port are displayed in the Properties window.

Click the Default Value field; click the more button (

Stylus Studio displays the Default Value dialog box.

) when it appears.

Figure 464. Default Value Dialog Box

1020

Click the Read default value from this URL radio button, and then navigate to
examples\pipelines\order\ folder where you installed Stylus Studio and select
booksXML.txt.

Stylus Studio User Guide

Use Case: Building order.pipeline

Click OK.
The input port on the ConvertToXML Node turns green, indicating that a source
document has been specified as the input.
Next, we need to specify which built-in converter to use to convert booksXML.txt to
XML.

Click the ConvertToXML node in the XML pipeline diagram.

Click the XML Converter URL field in the Properties window; click the more button
( ) when it appears.
Stylus Studio displays the Select XML Converter dialog box.

10.

Select the Comma-Separated Values converter.

The booksXML.txt source file happens to use a vertical bar (|) as its separator character.
To view the source .txt and .edi files, double-click them in the Project window to
display them in a Stylus Studio editor.

Tip

Figure 465. Select XML Converter Dialog Box

11.

Change the value in the Separator property to a vertical bar (|).

12.

Change the value in the First row contains field names to Yes.

13.

Click OK.
The ConvertToXML node representing the conversion of the booksXML.txt file to
XML is now completely specified, except for the output. We will address that in the
section Setting the XQuery Node Data Sources on page 1029.

Stylus Studio User Guide

1021

Building XML Pipelines

Create a ConvertToXML Node for order.edi

Next, using the procedure described in either Convert booksXML.txt Using a Built-in
XML Converter on page 1019 or Create a ConvertToXML Node for booksXML.txt on
page 1020, create a ConvertToXML node for the order.edi file. Note the following
changes:

Use select order.edi as the source document.

Select Electronic Data Interchange (EDI) from the Select XML Converter dialog box.
Accept all default values.

Renaming Nodes
When you add a second node of the same type using the Toolbox, Stylus Studio gives the
second node the same name as the first, with a number to make it unique. If you create a
node by dragging a document and dropping it on the canvas, Stylus Studio gives the node
the same name as the file.
Depending on how you created the ConvertToXML nodes in the XML pipeline, they are
named either:

Convert to XML and Convert to XML #2, or

booksXML.txt and order.edi

You can reame nodes using the following procedure:
To rename a node:
1.

Select the node you want to rename in the XML pipeline diagram.

Click the value in the Name field in the Properties window.

Type the new name and press Enter.

Tip Node names are displayed as tooltips in the XML pipeline diagram when you hover the

pointer over the node. You can also create labels for the diagram and for nodes within the
diagram. See Labeling on page 1059 for more information.

1022

Stylus Studio User Guide

Use Case: Building order.pipeline

The XML Pipeline So Far

At this point, we have defined the converters to be used to convert our non-XML data
sources to XML. The resulting XML pipeline, myOrders.pipeline, looks something like
this:

Figure 466. myOrders.pipeline After Defining Non-XML Data Sources

In the next stage of the process, we will specify the XQuery file that we will use to join
the data from these two files.

Using XQuery to Merge Source File Data

As described in order.pipeline Requirements on page 1015, the data required for our
report comes from two files a text file, booksXML.txt, and an EDI file, order.edi. Both
files have the books ISBN, and we will use that number to select matching data. This will
provide us with the following information required by our report:

Book title (from booksXML.txt)

ISBN and quantity (from order.edi)

To join data from these different documents we will use an XQuery document created
using the XQuery Mapper. Once we have defined that XQuery document, we can add the
XQuery node to our XML pipeline.

Using Variables to Reference Data Sources

Because we want our XQuery to be easy to parameterize, we will create it using external
variables to reference our two data sources, booksXML.txt and order.edi. Once the data
sources for the XQuery are defined, we can use the XQuery Mapper to map desired nodes
Stylus Studio User Guide

1023

Building XML Pipelines

from these source documents to nodes in the XML Schema that represents the structure
to which the resulting XML must conform.
If you open createFullOrder.xquery, which is in the pipelines\order folder of the
examples project where you installed Stylus Studio, you can see how this was done. As
shown in Figure 467, createFullOrder.xquery uses variable declarations, $ediOrder and
$allBooks, for the non-XML data sources. DataDirect XML Converters, which are built
in to Stylus Studio X14 XML Enterprise Suite, convert these data sources to XML on-thefly, any time the XQuery (or an XML pipeline that uses the XQuery) is executed. Thus, if
the data in either booksXML.txt and order.edi changes, the report resulting from the XML
pipeline will change, too.

Figure 467. Variables Created for Non-XML Data Sources

To use non-XML as a source document for XQuery Mapper:

To specify a non-XML data source as an XML source for the XQuery Mapper, you
1.

1024

Click the Add Source Document button at the top of the XQuery Mapper tab.
This displays the Open dialog box.

Stylus Studio User Guide

Use Case: Building order.pipeline

You select the file you want to open, and then select the Open using XML Converter
check box.

Figure 468. Using Non-XML Data as an XQuery Data Source

When you click Open, Stylus Studio displays the Select XML Converter dialog box
(see Figure 465), which you use to select the built-in DataDirect XML Converter you
want to use to convert your non-XML file to XML. Note that this is the same
procedure we used to identify the data sources for the XML pipelines two
ConvertToXML nodes.

When you click OK on the Select XML Converter dialog box, Stylus Studio adds it as
a data source in the Add Source Document pane of the XQuery Mapper.

Next, we need to create global variables for the two source documents. This way, the
XQuery code that Stylus Studio generates will use variable declarations instead of
document functions to reference our data sources.

Stylus Studio User Guide

1025

Building XML Pipelines

To associate the source schema with a global variable:
1.

Right click the source document name and select Associate With > Global Variable.
Stylus Studio displays the Associate Schema with Variable dialog box.

Figure 469. Associate Schema with Variable Dialog Box

Enter the value you want to use for the variable, and click OK.
When a variable is created (allBooks, for example), Stylus Studio creates a
declaration like the following in the XQuery source code:
declare variable $allBooks as document-node() external;

Looking at the XQuery Code

Before moving on with the XML pipeline creation, lets a quick look at the XQuery code
in createFullOrder.xquery:
declare variable $ediOrder as document-node() external;
declare variable $allBooks as document-node() external;
<root>
{
for $GROUP_28 in $ediOrder/EDIFACT/ORDERS/GROUP_28,
$row in $allBooks/table/row
where $GROUP_28/LIN/LIN03/LIN0301/text() = $row/isbn/text()
return
<book>
<title>
{$row/title/text()}
</title>
<quantity>
{$GROUP_28/QTY/QTY01/QTY0102/text()}
</quantity>
<ISBN>
{$GROUP_28/LIN/LIN03/LIN0301/text()}
</ISBN>
</book>
}
</root>

1026

Stylus Studio User Guide

Use Case: Building order.pipeline

The first two lines contain the variable declarations for booksXML.txt and order.edi, our
two source files. A FLWOR block (For, Let, Where, Order by, Return) matches ISBN
numbers from order.edi with those in books.xml, and when it finds a match, it returns

The title (from booksXML.txt)

The quantity (from order.edi)

The ISBN (from order.edi)

All of this code was created automatically as a result of mapping nodes from our source
documents to nodes in an XML Schema, fullOrder.xsd, which was provided by the
organization in our enterprise that requested the inventory report all XML resulting from
the createFullOrder.xquery must conform to this XML Schema.

Figure 470. XQuery Mapper Used to Generate createFullOrder.xquery

See Building an XQuery Using the Mapper on page 813 for more information on using
the XQuery Mapper.

Stylus Studio User Guide

1027

Building XML Pipelines

Adding an XQuery Node

Now that we understand how the XQuery code in createFullOrder.xquery uses a FLWOR
expression to join data from our data sources, we can add it to our XML pipeline.
To add an XQuery node to an XML pipeline:
1.

Drag the XQuery icon from the Toolbox pane and drop it on the XML pipeline canvas.
Stylus Studio creates an XQuery node and displays it in the XML pipeline diagram.

Display the Properties window (View > Properties) if it is not already open.

Display the Project window (View > Project) if it is not already open.

Drag createFullOrder.xquery and drop it on either

The XQuery node on the XML pipeline diagram

The Value field for the .xquery file property

The XQuery node now has two additional input ports, one named allBooks, and the
other named ediOrder.

Figure 471. XQuery Node for createFullOrder.xquery

These input ports are colored green, indicating that each has a default value specified
for it. These default values correspond to the two data sources we specified as source
documents in the XQuery Mapper.
If you drop createFullOrder.xquery directly on the XML pipeline canvas, Stylus
Studio automatically creates the ConvertToXML nodes that represent the data
sources it uses. See An Alternate Way to Create ConvertToXML Nodes on
page 1030.

Tip

1028

Change the XQuery nodes default name, XQuery operator, to Extract full order
information. (See Renaming Nodes on page 1022 if you need help with this step.)

Stylus Studio User Guide

Use Case: Building order.pipeline

Changes to Source Documents

XML pipelines reference external documents, like the createFullOrder.xquery document
we just added. They do not create copies of these documents. Therefore, when changes to
a source document are saved, the XML pipeline picks up these changes the next time it is
executed.

Setting the XQuery Node Data Sources

Although the XQuery code was specified with default data sources, we want the XQuery
to use the data sources we defined in the two ConvertToXML nodes we created in
Configuring Data Sources on page 1018. We do this by connecting the output ports on
the ConvertToXML nodes to the input ports on the XQuery node.
To set an XQuery nodes data sources:
1.

With the pointer over the Get books catalog from txt file ConvertToXML node,
drag and drop the output port on the allBooks input port on the Extract full order
information XQuery node.
Stylus Studio creates a pipe connecting the two nodes, shown in Figure 472.

Figure 472. The XML Pipelines First Pipe

Repeat this procedure, connecting the output port from the Get order from EDIFACT
node to the ediOrder input port on the Extract full order
information XQuery node.

request ConvertToXML

Stylus Studio User Guide

1029

Building XML Pipelines

Default and Specified Port Values

As you can see in Figure 472, an input port can have both a default value, and a value
provided by another nodes output port. Note, however, that an output ports default value
is never used if a pipe is connected to the port the pipe either supplies a value or it does
not, but the default value is ignored.

An Alternate Way to Create ConvertToXML Nodes

It should be noted that when you add an XQuery or an XSLT document to an XML
pipeline, Stylus Studio creates other nodes required to support the resulting XQuery or
XSLT node, based on the XQuery or XSLT definition. For example, since
createFullOrder.xquery was defined to use Stylus Studios built-in converters to create
XML data source documents, simply dragging and dropping the createFullOrder.xquery
on the XML pipeline canvas would have automatically created the XQuery node and both
ConvertToXML nodes, one for each data source specified in the XQuery code.
We will see this functionality in action later, when we add another XQuery document to
the XML pipeline. (See Add createReport.xquery on page 1036 for more information.)

Testing the XML Pipeline

The XML pipeline as it is defined now creates an XML document containing a book parent
node, with title, quantity, and ISBN child nodes. Lets test it before continuing.
To test an XML pipeline, click the Execute button (

In this case, Stylus Studio displays a message indicating that the XML pipeline, as it is
currently defined, does not have an output. And if we examine our XML pipeline, we see
that this is true processing terminates with the XQuery node, but its output port is empty.

Setting a Value for an Output Port

To quickly verify that our XML pipeline works as expected, we can create an output for
the XQuery nodes output port.
To set a value for an output port:

1030

Click the output port.

Specify a value for the Copy To URL property (myFullOrderSample.xml, for example).
The output port changes color, indicating that it has a value specified for it.
Stylus Studio User Guide

Use Case: Building order.pipeline

If we test the XML pipeline again, we can see that the XML pipeline runs to completion.
Stylus Studio displays the Preview window, the Main tab of which displays an execution
log that describes the processing steps executed in the XML pipeline.

Figure 473. XML Pipeline Execution Messages in Preview Window

Tip If you click an entry in the execution log, Stylus Studios back-mapping feature

highlights node responsible for that processing step.

Stylus Studio User Guide

1031

Building XML Pipelines

If we click the next tab in the Preview window, we can see the XML output by our XML
pipeline in text view. If we click the Preview in Tree button ( ), we can verify that the
XML document is of the structure we expect.

Figure 474. Tree View of XML Pipeline Output

Tip You could also click the XQuery nodes output port to display this tab.

Designing a Report from the XML Document

Now that we have an XML document that represents our joined data sources, we need to
develop finished reports in HTML and PDF. The Stylus Studio XML Publisher helps you
design reports based on XML documents or XML Schema, and then generate XQuery or
XSLT code to create that report in HTML+CSS or XSL-FO document formats.

1032

Stylus Studio User Guide

Use Case: Building order.pipeline

As shown in Figure 475, the XML Publisher createReport.report uses the XML
document resulting from our XML pipeline, myFullOrderSample.xml, as the data source to
design a simple book order report.

Figure 475. XML Publisher Report Designer

The table, and the values in its columns, was created by simply dragging nodes from the
source document tree and dropping them on the XML Publisher canvas. Additional
formatting was specified using XPath expressions (to control row color and quantity
color, for example).
When the report design was complete, we used XML Publisher to generate XQuery and
XSLT code using the Generate Transformation dialog box.

Figure 476. XML Publisher Generate Transformation Dialog Box

Stylus Studio User Guide

1033

Building XML Pipelines

We created createReport.xquery in one generate pass, and createReport.xsl in another.

We will add these transformations to our XML pipeline next.
See Chapter 15, Publishing XML Data, to learn more about designing reports using the
XML Publisher.

Adding XSLT and XQuery Transformations

The next step in building our XML pipeline is to add the XSLT and XQuery
transformations generated using XML Publisher. These transformations will render the
XML document resulting from the Extract full order information XQuery,
myFullOrderSample.xml, as HTML and PDF, respectively.
Of course, if we wanted to, we could have used XQuery to generate the HTML and XSLT
to generate the XSL-FO; or we could have used just XQuery or XSLT to generate both
document formats. The technology you choose is largely a matter of personal preference,
though some are better suited to certain tasks (like data aggregation, HTML formatting,
and so on) than others.

Add createReport.xsl
To add createReport.xsl to the XML pipeline:

1034

Display the Project window (View > Project) if it is not already open.

Drag createReport.xsl from the pipelines/order folder and drop it on the XML
pipeline canvas.

Stylus Studio User Guide

Use Case: Building order.pipeline

Stylus Studio add an XSLT node to the XML pipeline.

Figure 477. New XSLT Node

The colored input port indicates that this XSLT node already has a default input and
value defined for it. We will specify our own input value (the XML document created
by the Extract full order information XQuery node).
Stylus Studio uses the file name for the node name when you create the node by
dragging and dropping a document on the XML pipeline canvas.

Tip

Drag a pipe from the output port on the Extract

node to the input port on the new XSLT node.

full order information XQuery

Next, specify a value for the output port (order.html, for example). See Setting a
Value for an Output Port on page 1030 if you need help with this step.
Since we know the XQuery node generates the XML document we require, we can
delete the Copy to URL for its output port. Otherwise, output will continue to be
written to that URL.

Stylus Studio User Guide

1035

Building XML Pipelines

Test the XML pipeline by clicking the Execute button ( ).

As currently defined, our XML pipeline should create an HTML report based on the
myFullOrderSample.xml document, and this is what appears in the Preview window.

Figure 478. Preview of the XML Pipelines HTML Output

Click the Preview in Browser button to see the XML pipeline output rendered in
HTML.

Tip

Add createReport.xquery
All that remains for our XML pipeline definition is to specify the XQuery node that will
transform myFullOrderSample.xml into PDF. For this purpose, we will use the
createReport.xquery generated by the XML Publisher.
To add createReport.xquery to the XML pipeline:

1036

Display the Project window (View > Project) if it is not already open.

Drag createReport.xquery from the pipelines/order folder and drop it on the XML
pipeline canvas.
Stylus Studio may display a warning message, indicating that the processor specified
for the createReport.xquery document differs from that specified for the XML
pipeline.
Stylus Studio User Guide

Use Case: Building order.pipeline

Click OK to accept the default recommendation. (See Managing Processor

Conflicts on page 1045 for more information on this topic.)
Stylus Studio adds a new XQuery and associated XSL-FO node to the XML pipeline.
The XSL-FO node is the result of the post-processing specified for the XQuery
when we generated the XQuery code from XML Publisher, we chose XSL-FO for the
Document Type (see Figure 476). Stylus Studio automatically selected the default FO
processor, RenderX XEP, to process the FO generated by createReport.xquery.

Drag a pipe from the output port on the Extract

node to the input port on the new XQuery node.

full order information XQuery

Figure 479. New XQuery Node with Automatically Created XSL-FO Node
5.

Next, specify a value for the output port (order.pdf, for example) of the XSL-FO
node. See Setting a Value for an Output Port on page 1030 if you need help with
this step.

Stylus Studio User Guide

1037

Building XML Pipelines

Test the XML pipeline one last time by clicking the Execute button ( ).
Stylus Studio reopens the Preview, which displays an execution log for the XML
pipelines operations. New statements appear for the new XQuery and XSL-FO
nodes.

Figure 480. Pipeline Execution Log and FO Processor Output

It also reopens the Output window, which shows output from the XSLT processor and
the RenderX FO post-processor.

1038

Stylus Studio User Guide

Use Case: Building order.pipeline

Click the second tab in the Preview window to display the PDF document created by
the nodes we just added to the XML pipeline.

Figure 481. PDF Created by the XQuery and XSL-FO Nodes

Note If you receive an error during this step, it might mean that Adobe Acrobat Reader was not

properly installed on your system. Go to http://www.adobe.com and resinstall Acrobat

Reader.

Finishing Up
Now that the XML pipeline has been tested and we have seen that it successfully
generates the order report in both HTML and PDF document formats. we can generate
Java code for the entire XML pipeline. This code could then be incorporated in, say, a Java
application.
See Generating Code for an XML Pipeline on page 1069 for more information on this
topic.

Stylus Studio User Guide

1039

Building XML Pipelines

Working with Nodes

This section describes how to work with the different nodes you might use in an XML
pipeline. It references XML pipelines in the pipelines folder in the examples project.
This section covers the following topics:

Types of Nodes on page 1040

Adding Nodes to an XML Pipeline on page 1040

XQuery and XSLT Nodes on page 1043

XSL-FO Nodes on page 1046

ConvertToXML and ConvertFromXML Nodes on page 1053

Validate Nodes on page 1049

Stop and Warning Nodes on page 1055

Pipeline and Related Nodes on page 1047

Choose Nodes on page 1051

XML Parser Nodes on page 1057

XML Serializer Nodes on page 1058

For information about node properties, see XML Pipeline Node Properties Reference
on page 1076.

Types of Nodes
Nodes can be grouped into three broad categories:

Transformation

Flow control

Data sources
These categories are described in XML Pipeline Components on page 1010.

Adding Nodes to an XML Pipeline

There are two ways to add nodes to an XML pipeline. You can

Use existing documents

Use the icons in the Toolbox pane

1040

Stylus Studio User Guide

Working with Nodes

Using Existing Documents

To create a node in an XML pipeline using an existing document, just drag and drop the
document (from the Project window or the File Explorer, for example) on the XML
pipeline canvas. This creates a node that represents the document you dropped on the
canvas. For example, if you drag and drop an XQuery document, Stylus Studio creates an
XQuery node based on that XQuery document. It also incorporates that XQuery
documents default scenario properties settings, including its input and output URLs,
processor, and post-process instructions, validation instructions, and so on.
In addition to dropping a file on the XML pipeline canvas, you can also drop it on an
existing node or on the appropriate Value field for that node displayed in the Properties
window. A nodes input and output ports cannot be used as drop targets.

Using the Toolbox

To create a node in an XML pipeline using the Toolbox, just drag an icon from the Toolbox
pane and drop it on the XML pipeline canvas.

Figure 482. XML Pipeline Toolbox

This creates a node that is not yet implemented, whose properties you then need to specify
either by typing, or by dragging an external document and dropping it on the node or
one of its Value fields in the Properties window. For example, if you drag the XSLT icon
and drop it on the canvas, you would need to specify values for the input and output nodes,
as well as the URL of the XSLT document you want that node to represent in your XML
pipeline.
Stylus Studio User Guide

1041

Building XML Pipelines

Available tools are described in the following table.

Table 127. XML Pipeline Tools
Tool

Description

Code Generation

Choose

Used to direct the flow of XML pipeline

processing using one or more XPath
expressions.

Java only

ConvertFromXML

Used to convert XML to some other format

(CSV, binary, and so on).

Java

Used to converts a flat file (CSV, binary, and so

on) or EDI message type to XML.

Java

Pipeline

Represents an XML pipeline file you want to

include in the another pipeline.

Used to display a warning message during

XML pipeline processing.

Java only

XSLT

Used to transform XML input using XSLT.

Java
C#

Node and Port Names

The default node name is a variation of the name as it appears in the Toolbox pane the
default name for the XSL-FO operation is FO Operator, for example. If you use an
existing document to create a node, Stylus Studio uses the file name as the default node
name.
Node names are used for documentation purposes only; they do not affect XML pipeline
execution, though they do appear as strings in the generated code and in messages in the
XML pipeline execution log displayed in the Preview window. Node names appear in the
XML pipeline as tooltips when you place the pointer on the node.
Tip You can create a label for a node that is always visible in the XML pipeline diagram. See

Labeling on page 1059 for more information.

XQuery and XSLT Nodes

Note You cannot use an XQuery node in an XML Pipeline for which you plan to generate C#

code.
XQuery and XSLT nodes represent XQuery and XSLT documents. XQuery and XSLT
code is executed using the processors specified in the XML pipelines execution

Stylus Studio User Guide

1043

Building XML Pipelines

framework. See Specifying an Execution Framework on page 1017 for more

information on this topic.

Figure 483. XQuery and XSLT Nodes in getHoldings.pipeline

Input Ports
XQuery and XSLT nodes have a single input port by default which you use to specify the
XML input to be transformed. You can specify a default value, or the value can be
dynamic (the output from another node in the XML pipeline, for example).
Additional input ports, like the one on the XQuery node in Figure 483, appear if

One or more external variables are defined for it (XQuery)

One or more global parameters are defined for it (XSLT)

Output Ports
XQuery and XSLT nodes have a single output port, used to specify what to do with the
result of the transformation. You can

Use the Copy to URL property to write the output to a file system

Pipe the output to one or more other nodes

Or both

Scenario Properties
An XQuery or XSLT documents default scenario properties are reflected in the XML
pipeline only if you drop the document directly on the canvas. For example, if the default

1044

Stylus Studio User Guide

Working with Nodes

scenario for your XQuery document specifies RenderX post-processing, Stylus Studio
automatically adds an XSL-FO node to the XML pipeline, connected to the XQuery
nodes output port when you drop it on the canvas to represent the post-processing. If you
drop the document on an existing XQuery node, however, the XSL-FO post-processing
node is not added to the XML pipeline.
Scenario properties treated in this way include

Input and output URLs

Values for existing parameters and variables

Processors

Post-processing

Validation
Similarly, changes made to default scenario properties are not reflected in the XML
pipeline unless you re-add the document to the XML pipeline by dropping it on the
canvas.

Changes to Source Code

When you save changes to the source XQuery or XSLT documents used in an XML
pipeline, those changes are reflected the next time the XML pipeline is executed. If you
added external variables or parameters, new input ports are added to the XQuery and
XSLT nodes.

Managing Processor Conflicts

Each XQuery and XSLT document is associated with its own set of processors, which are
specified on the Processor, Post-Process, and Validation tabs of XQuery and XSLT
Scenario Properties dialog boxes. When you add an XQuery or XSLT node to an XML
pipeline by dragging and dropping the document onto the XML pipeline canvas, Stylus

Stylus Studio User Guide

1045

Building XML Pipelines

Studio displays the Processor Mismatch dialog box if the documents processor settings
differ from those specified for the XML pipeline.

Figure 484. Processor Mismatch Dialog Box

You can

Use the processor settings specified for the XML pipeline on the Execution
Framework tab of the Scenario Properties dialog box

Change the XQuery or XSLT processor setting for the XML pipeline
Note Stylus Studio checks XQuery and XSLT processor compatibility only. Validation and FO

processing engines are not checked, and are not altered by any actions you take on the
Processor Mismatch dialog box.

XSL-FO Nodes
Note You cannot use an XSL-FO node in an XML Pipeline for which you plan to generate C#

code.

1046

Stylus Studio User Guide

Working with Nodes

XSL-FO nodes convert their input to PDF using the FO processor specified in the XML
pipelines execution framework. See Specifying an Execution Framework on
page 1017 for more information on this topic.

Figure 485. XSL-FO Node in getHoldings.pipeline

They are created automatically when an XQuery or XSLT document that specifies postprocessing is dropped directly onto the XML pipeline canvas. You can also create one by
dragging the XSL-FO icon from the s. The only property you can specify for an XSL-FO
node is its name.

Input Port
XSL-FO nodes have a single input port that you use to specify the XML to be converted
to PDF. This node expects XML defined using the FO grammar. You can specify a default
value, or the value can be dynamic (the output from another node in the XML pipeline,
for example). XSL-FO nodes are typically piped to XQuery and XSLT nodes, but they can
be piped to any node that outputs XML using the FO grammar.

Output Ports
XSL-FO nodes have a single output port, used to specify what to do with the result of the
transformation. Typically you use the Copy to URL property to write the output PDF to a
file system, but you could also pipe it to a converter that does something with the PDF, or
to a Pipeline Output node.

Pipeline and Related Nodes

Note You cannot use a Pipeline node in an XML Pipeline for which you plan to generate C#

code.

Stylus Studio User Guide

1047

Building XML Pipelines

Including an XML pipeline refers to the process of inserting one XML pipeline inside
another instead of piping a nodes output to an XQuery or XSLT transformation for
processing, for example, output is piped to the included XML pipeline. That XML
pipeline performs the processes defined by its nodes, and then returns one or more outputs
to a node in the including XML pipeline for subsequent processing.

Example
The getHoldings.pipeline in the pipelines\stocks folder in the examples project
installed with Stylus Studio uses an included XML pipeline, retrieveData.pipeline.
Figure 486 illustrates how an included XML pipeline is represented in the including XML
pipeline.

Figure 486. Illustration of an Included Pipeline (retrieveData.pipeline)

Included XML pipelines, as any other documents (XQuery and XSLT, for example),
cannot be edited from the including XML pipeline. You must open these documents
separately.
Tip To open and edit an included XML pipeline or any other document, double-click its node.

1048

Stylus Studio User Guide

Working with Nodes

Pipeline Node Input and Output Ports

A Pipeline node displays input and output ports only if the XML pipeline it represents has
been defined with Pipeline Input and Pipeline Output nodes, as shown in Figure 496.
These nodes allow the included XML pipeline to be connected to the including XML
pipeline.

How to Include an XML Pipeline

To include an XML pipeline:
1.

Define the XML pipeline (XML pipeline A) you want to include in another XML
pipeline (XML pipeline B).

Ensure that you have defined Pipeline Input and Pipeline Output nodes for XML
pipeline A (the XML pipeline to be included in XML pipeline B).

Drag and drop XML pipeline A into XML pipeline B.

Alternative: Create an empty Pipeline node in XML pipeline B and manually specify
the URL for XML pipeline A in its .pipeline file property.

Connect the input and output ports of the Pipeline node representing XML pipeline
A to node ports in XML pipeline B as required.

Validate Nodes
Validate nodes represent an XML Schema document used to validate XML piped to it
from another node.

Figure 487. Validate Node in retrieveData.pipeline

Stylus Studio User Guide

1049

Building XML Pipelines

You can create a Validate node by dragging an XML Schema document (.xsd) and
dropping it directly on the XML pipeline canvas, or you can drop an XML Schema
document on an existing Validate node.

Using Multiple XML Schemas

A Validate node can represent multiple XML Schemas. You can add additional XML
Schemas by simply dragging and dropping the XML Schema document (.xsd) on the
Validate node, or you can use the following procedure.
To add additional XML Schemas to a Validate node:
1.

Display the Properties window if it is not already open (View > Properties).

Click the Validate node in the XML pipeline diagram.

The properties for the validate node are displayed in the Properties window.

Click the XML Schemas field; click the more button (

The Select Multiple URLs dialog box appears.

) when it appears.

Figure 488. Select Multiple URLs Dialog Box

Use the add button ( ) to display the Open dialog box, which you can then use to
navigate to the XML Schema you want to add to the Validate node.

Click the OK button.

Input Port
The Validate node has a single input port that you use to specify the XML you want to be
validated by the XML Schemas specified by the Validate nodes XML Schemas property.
You can specify a default value, or the value can be dynamic (the output from another
node in the XML pipeline, for example).

1050

Stylus Studio User Guide

Working with Nodes

Output Ports
Validate nodes have two output ports, named Output valid and Output invalid, which you
use to direct the flow of the XML pipeline. Typically, the Output valid port is piped to
another transformation in the XML pipeline, while the Output invalid port is piped to a
node like Stop or Warning.

Choose Nodes
Note You cannot use a Choose node in an XML Pipeline for which you plan to generate C#

code.
A Choose node uses XPath expressions to evaluate one or more conditions based on its
input to direct the flow of XML pipeline processing. The Choose node uses XPath 2.0 to
evaulate the XPath expressions defined for it.

Figure 489. Choose Node in retrieveData.pipeline

Input Ports
The Choose node can have one or more input ports; by default, it has a single input port,
named Input #0. You use the XPath # property to express a true condition that is, a
condition that must be met in order for processing to continue. The Choose node in
retrieveData.pipeline, for example, uses the XPath expression . castable as
xs:double to check whether or not the user ID it is given as its input is numeric.
The initial context node for each XPath # expression is the data input from Input #0. For
additional input ports (Input #1, Input #2, and so on), data is available to the XPath
expression as $var1, $var2, and so on.

Stylus Studio User Guide

1051

Building XML Pipelines

The Choose node evaulates XPath#0. If XPath#0 is true, it sends data from Input #0 to
Output #0. If XPath#0 is false, it evaluates XPath#1. If XPath#1 is true, it sends data from
Input #0 to Output #1, and so on. If none of the XPath # expressions is true, the data from
Input #0 is sent to Output no match port.

Adding Input Ports

To add an input port to a Choose node:
1.

Display the Properties window if it is not already open (View > Properties).

Click the Choose node in the XML pipeline diagram.

Change the value for the Number of inputs property.

A new input port is added, named Input #1.

Optionally, add an output port for the new input port.

Output Ports
By default, a Choose node has two output ports:

Output#0, which is enabled when the condition defined by the corresponding

property, XPath #0, is met (the true condition)

Output no match, the default else condition, which is enabled if an input evaluates
to false
You can add additional output ports, which you might want to do if you have added an
input port. The output port that corresponds to the true condition always makes the first
input available to its connecting pipe.
Each output port must have a value specified for it. You can

Use the Copy to URL property to write the output to a file system

Pipe the output to another node (for more processing if the condition evaluates to
true, or to a Stop node if the condition evaluates to false, for example)

Or both

1052

Stylus Studio User Guide

Working with Nodes

Adding Output Ports

To add an output port to a Choose node:
1.

Display the Properties window if it is not already open (View > Properties).

Click the Choose node in the XML pipeline diagram.

Change the value for the Number of choices property.

A new output port is added, named Output #1.

ConvertToXML and ConvertFromXML Nodes

ConvertToXML nodes convert non-XML input (like a CSV file or an EDI message type)
to XML; ConvertFromXML nodes convert XML input to a non-XML format. Both nodes
use built-in DataDirect XML Converters or user-defined custom XML conversions to
convert input.

Figure 490. ConvertToXML Node in retrieveData.pipeline

Specifying an XML Converter URL

Both ConvertToXML and ConvertFromXML nodes are defined by specifying an XML
Converter URL that evaluates to either a

Built-in DataDirect XML Converter (converter:CSV or converter:EDI, for example)

or a

User-defined converter (converter:file:///c:/XMLconverters/myConverter.conv,

for example)
You can manually type a URL in the nodes XML Converter URL property, but the XML
converter URL syntax can be complex, and it is easy to make errors or to leave settings
that you might wish to use unspecified. For example, a completely specified XML
Converter URL for the CSV XML Converter might look like this:
Stylus Studio User Guide

1053

Building XML Pipelines

converter:CSV:newline=cr:sep=|:first=yes:number=yes:collapse=yes

The recommended way to specify an XML Converter URL is to select the built-in XML
Converter or user-defined custom XML conversion from the Select XML Converter dialog
box, which you display by clicking the XML Converter URL field, and then clicking the
more button ( ) when it appears.:

Figure 491. Select XML Converter Dialog Box

The value in the URL field changes when you select an XML Converter. Properties and
their settings (like decode=no in Figure 491) are displayed only if you change a default
value.

Creating a ConvertToXML Node

You can create a ConvertToXML node manually, by dragging the ConvertToXML icon
from the Toolbox pane and dropping it on the XML pipeline canvas. See Create a
ConvertToXML Node for order.edi on page 1022 for a description of this procedure.
ConvertToXML nodes are created automatically if an XML Converter URL has been used
as a data source for another document represented in the XML pipeline, or if you drag a
converted document from the Project window and drop it on the canvas. The Extract full
order information XQuery node in the order.pipeline uses two non-XML data sources
that convert text and EDI message types to XML for processing. When this XQuery is
added to an XML pipeline, its data sources, represented as ConvertToXML nodes, also
appear in the XML pipeline.

1054

Stylus Studio User Guide

Working with Nodes

Input Port
ConvertToXML and ConvertFromXML nodes have a single input port that you use to
specify the file to be converted to XML (or vice versa). You can specify a default value,
or the value can be dynamic (the output from another node in the XML pipeline, for
example).

Output Ports
ConvertToXML and ConvertFromXML nodes have a single output port, used to specify
what to do with the result of the transformation. You can

Use the Copy to URL property to write the output to a file system

Pipe the output to another node (like an XQuery transformation, for example)

Or both

For More Information

To learn more about built-in DataDirect XML Converters and converter technology, see
Converting Non-XML Files to XML on page 213.

Stop and Warning Nodes

Stop and Warning nodes are used to indicate exceptions to or special conditions
encountered in an XML pipelines execution. They serve a similar purpose, but behave in
different ways.

Stop Nodes
Figure 492, for example, shows a Stop node piped to the Output invalid output port of the
Validate node if the validation using the XML Schema specified in the Validate node
fails, the Stop node aborts XML pipeline processing, and a user-defined error message is

Stylus Studio User Guide

1055

Building XML Pipelines

generated. Stop nodes do not have an output port XML pipeline processing ends if it
encounters a Stop node.

Figure 492. Stop Node in retrieveData.pipeline

Warning Nodes
Note You cannot use a Warning node in an XML Pipeline for which you plan to generate C#

code.
Warning nodes, like the one shown in Figure 493, do have an output port. When
encountered in XML pipeline processing, a Warning node generates the user-defined
error message you give to it and pipes the input it is given through to the next node in the
XML pipeline.

Figure 493. Example Warning Node Implementation

1056

Stylus Studio User Guide

Working with Nodes

XML Parser Nodes

Note You cannot use an XML Parser node in an XML Pipeline for which you plan to generate

C# code.
XML Parser nodes convert text input to an XML document.

Figure 494. Example XML Parser Node Implementation

Input Port
XML Parser nodes have a single input port that you use to specify the text to be converted
to XML. You can specify a default value, or the value can be dynamic (the output from
another node in the XML pipeline, for example).

Output Ports
XML Parser nodes have a single output port, used to specify what to do with the result of
the transformation. You can

Use the Copy to URL property to write the output to a file system

Pipe the output to another node (like Validate, for example)

Or both
An output must be specified in order for the node to be processed.

Stylus Studio User Guide

1057

Building XML Pipelines

XML Serializer Nodes

Note You cannot use an XML Serializer node in an XML Pipeline for which you plan to

generate C# code.
XML Serializer nodes convert an XML document to text. You can use node properties to
specify characteristics of the resulting text file, such as whether or not you want it to
include an XML declaration, and whether or not to use pretty-print to format it.

Figure 495. Example XML Serializer Node Implementation

Input Port
XML Serializer nodes have a single input port that you use to specify the XML to be
converted to text. You can specify a default value, or the value can be dynamic (the output
from another node in the XML pipeline, for example).

Output Ports
XML Serializer nodes have a single output port, used to specify what to do with the result
of the transformation. You can

Use the Copy to URL property to write the output to a file system

Pipe the output to another node

Or both

1058

Stylus Studio User Guide

Working with the XML Pipeline Diagram

This section describes the features you can use when working with the XML pipeline
diagram. This section covers the following topics:

Displaying a Grid on page 1059

Labeling on page 1059

Zoom on page 1060

Edge Style on page 1061

Manipulating Nodes in the Diagram on page 1062

Saving the XML Pipeline Diagram as an Image on page 1063

Labeling XML Pipeline Diagrams on page 1064

Displaying a Grid
By default, Stylus Studio displays a grid on the canvas to help you place nodes in a
uniform fashion. You can hide the grid by clicking the Show Grid button, or by selecting
XMLPipeline > Show Grid from the menu or Show Grid from the canvas shortcut menu.
Figure 458 shows the XML pipeline canvas with the grid displayed.
Tip Use Snap to Grid to have Stylus Studio place nodes precisely along grid line coordinates.

This feature is available whether or not you display the grid. See Manipulating Nodes
in the Diagram on page 1062 for more information.

Labeling
You can label the XML pipeline diagram and individual nodes. Labeling is a useful way
to provide documentation for an XML pipeline, especially if you plan to print the
diagram.
Tip Open BookLookup.pipeline, in the \pipelines\servlet folder of the examples project

installed with Stylus Studio for an example of labels in an XML pipeline diagram.
For more information, see Labeling XML Pipeline Diagrams on page 1064.

Stylus Studio User Guide

1059

Building XML Pipelines

Zoom
You can zoom the XML pipeline diagram in and out using the zoom slider at the top of
the editor (
) drag the slider to the right to increase zoom, drag it to the left
to decrease zoom. Changing zoom affects both the diagram and the grid (if it is
displayed).
The zoom level you select in the XML Pipeline Editor does not affect the size of the nodes
if you save the XML pipeline diagram as an image the default zoom level is always used
for saved images.
For more information, see Saving the XML Pipeline Diagram as an Image on
page 1063.

1060

Stylus Studio User Guide

Working with the XML Pipeline Diagram

Edge Style
You can choose from one of three edge styles for the pipes that connect one node to
another:
Table 128. Edge Styles
Term

Example

Line

Orthogonal

Spline

When you change the style, either from the XMLPipeline menu or the toolbar, you change
the style
Stylus Studio User Guide

1061

Building XML Pipelines

Of any pipes that are currently selected; this includes the pipes associated with any
selected nodes
Of any pipe you create after selecting the new style

To change the edge style:

Select the pipe, or the node whose pipes, you want to change.

Select XML Pipeline > Edges Style from the menu.

Alternative: Right-click and select XML Pipeline > Edges Style from the shortcut
menu.

Select the edge style you want from the drop-down menu.

Manipulating Nodes in the Diagram

Once you have added a node to the XML pipeline diagram, there are several ways to
manipulate them, as summarized in Table 129. You might want to use these operations to

1062

Stylus Studio User Guide

Working with the XML Pipeline Diagram

simplify the XML pipelines layout, perhaps before saving an image of the diagram.
Changing the diagram layout has no effect on the XML pipelines definition.
Table 129. Ways to Manipulate Nodes
Action

Description

Methods

Rotate ports

You can rotate the ports on nodes clockwise

and counter-clockwise, 90 degrees at a
time.

Rotate (Clockwise or
Counter-clockwise) buttons

on tool bar

XML Pipeline > Rotate

(Clockwise or Counterclockwise) on main menu

Rotate (Clockwise or
Counter-clockwise) on

shortcut menu
Snap-to-grid

By default, Stylus Studio places nodes

where you drop them on the canvas. For a
more uniform layout, you can use Snap-toGrid. When this setting is on, dropped
nodes shift (snap) to the closest vertical and
horizontal grid axis. Snap-to-Grid is
available regardless of whether or not the
grid is displayed on the XML pipeline
canvas.

Snap to Grid button on tool

bar

XML Pipeline > Snap to Grid

on main menu
Snap to Grid on shortcut
menu

Saving the XML Pipeline Diagram as an Image

You can save a graphical image of your XML pipeline diagram as a JPEG (.jpg) file or
as an Extended Meta File (.emf). When you save an XML pipeline as an image, Stylus
Studio includes the entire XML pipeline, not just what is currently visible on the XML
pipeline canvas.
Stylus Studio uses a standard zoom level when saving an XML pipeline as an image;
application zoom level settings are ignored. The grid is captured if it is displayed.
To save an XML pipeline as an image:
1.

Click the Save as Image button on the toolbar.

Stylus Studio User Guide

1063

Building XML Pipelines

Alternatives: Select XMLPipeline > Save as Image from the menu, or select Save as
Image from the shortcut menu (right-click).
Stylus Studio displays the Save As dialog box.
2.

Select the file format (.jpg or .emf) from the Files of type drop-down list.

Specify a name and location for the file and click the Save button. The default name
is the name of the XML pipeline; the default location is the project folder in which
the XML pipeline has been saved.

Labeling XML Pipeline Diagrams

A label is a block of text that you can associate with a node, or with the XML pipeline
diagram itself. Labeling can be useful for printed XML pipelines, or any time you need to
provide additional documentation about the XML pipeline. Label text is not available in
the generated code.
Labels appear as plain text on the canvas until you select one. When you select a label or
the node with which it is associated, Stylus Studio displays a line that shows you the node
with which the label is associated.

Figure 496. Pipeline Labels

You can create as many labels for a pipeline as you like. Each node, however, can be
associated with only one label. You cannot format label text.
Tip For XQuery, XSLT, and other nodes that represent files, use the label to describe the
nodes action or role in the XML pipeline, and enter the file name in the Name property.

To create a label:
1.

1064

Select the operation you want to label. If you want to label the entire XML pipeline,
click the canvas.

Stylus Studio User Guide

Debugging an XML Pipeline

Select XML Pipeline > Add Label from the menu.

Alternative: Right-click and select Add Label from the shortcut menu.
A label block appears in the XML pipeline diagram.

Type the text for your label.

Press Enter.

Debugging an XML Pipeline

You can debug an XML pipeline in Stylus Studio as you would an XQuery or XSLT
document by setting breakpoints, stepping through the diagram, and using features like
the Watch, Variables, and Call Stack windows to help troubleshoot your XML pipeline.
Debugging tools are available in the toolbar, and in the Debug menu.
This section covers the following topics:

Cross-Language Debugging on page 1065

Execution Framework Determines Debugging Support on page 1066

Setting and Removing Breakpoints on page 1066

Running the Debugger on page 1067

Stepping Into a Node on page 1068

Stopping Debug Processing on page 1069

Cross-Language Debugging
An important feature of XML pipeline debugging is Stylus Studios support for crosslanguage debugging. Cross-language debugging allows you to set a breakpoint on, say, an
XQuery node, and then step into the source XQuery document on which the node is based,
debug it, and then step back into the XML pipeline. Cross-language debugging is
supported for

XQuery nodes

XSLT nodes

Included pipelines

Java functions within your XQuery or XSLT code

Stylus Studio User Guide

1065

Building XML Pipelines

Execution Framework Determines Debugging Support

The XML pipelines execution framework determines whether or not you can perform
cross-language debugging in your XML pipeline. Processor settings defined in the
scenarios for XML pipeline components like XQuery and XSLT have no effect XML
pipeline processor settings are always used.
The following execution framework settings support cross-language debugging:

Java built-in

Saxonica Saxon and Saxonica Saxon-SA

Microsoft .NET

Setting and Removing Breakpoints

You can set breakpoints on any node in an XML pipeline. You cannot set breakpoints on
a nodes input and output ports.
To set a breakpoint:
1.

Select the XML pipeline node on which you wish to set the breakpoint.

Click the Toggle Breakpoint button ( ) or press F9.

Stylus Studio displays a breakpoint symbol (a large red circle) next to the node.

Figure 497. Breakpoint Set on a Node

To remove a breakpoint:

1066

Select the XML pipeline node whose breakpoint you wish to remove.

Click the Toggle Breakpoint button (

) or press F9.

Stylus Studio User Guide

Debugging an XML Pipeline

Running the Debugger

To run the debugger, click the Start Debugging button (

) or click F5:

When the debugger hits a breakpoint you have set, it displays a pause symbol, like the one
shown in Figure 498.

Figure 498. Pause Symbol for a Debugging Breakpoint

When debugging is paused, debugging tools (like those that let you step into and over
breakpoints, and toggles for the Watch, Variables, and Call Stack windows) become
active. You cannot edit the XML pipeline or alter its scenario properties during
debugging, or when the debugger is paused.

Figure 499. Debugging an XQuery Node in order.pipeline

Figure 499 shows a breakpoint set on the createFullOrder.xquery node in

The Preview window shows the XML pipelines execution log, and we
can see in it that the two ConvertToXML nodes have just been processed; this is confirmed

order.pipeline.

Stylus Studio User Guide

1067

Building XML Pipelines

by the presence of the pause symbol on the following XQuery node it has not yet been
processed. The Variables window shows the data retrieved from booksXML.txt.

Stepping Into a Node

If we want to take a closer look at the XQuery node as it processes the input, we can step
into it, directly from the XML Pipeline Editor by pressing the Step Into button ( ), or
by pressing F11. When we step into a node, Stylus Studio opens the document the node
represents (in this case, createFullOrder.xquery) in its own editor.

Figure 500. Stepping Into XQuery While Debugging XML Pipeline

When you step into another document from the XML Pipeline Editor, Stylus Studio
pauses the debugger on the first instruction in that document. (In XQuery and XSLT, the
pause symbol is a yellow triangle. You can step over the instructions, one-by-one, by
clicking the Step Over button ( ) or pressing F10. You can set breakpoints within this
document, as well.
You need to stop debugging before you can make changes to a document.
When the document you have stepped into has completed processing, you are returned to
the XML pipeline, and you can continue debugging it.

1068

Stylus Studio User Guide

Generating Code for an XML Pipeline

Stopping Debug Processing

You can stop debug processing of an XML pipeline at any time by clicking the Stop
), or by pressing F8. Similarly, you can pause debugging (when
you choose, as opposed to waiting for the debugger to hit a breakpoint) by clicking the
Pause button (
) or by selecting Debug > Pause from the menu.

Debugging button (

Generating Code for an XML Pipeline

Once you have built and tested your XML pipeline in the XML Pipeline Editor and are
satisfied that it performs as required, you can generate either Java or C# code for it. The
generated code can be compiled and run as-is. (Java code can be compiled and run inside
Stylus Studio; C# code must be compiled and run using a third-party tool such as
Microsoft Visual Studio.
This section covers the following topics:

Execution Framework and Code Generation

Code Generation Settings

How to Generate Code for an XML Pipeline

Compiling Generated Java Code

Deploying Generated Code

Execution Framework and Code Generation

Settings for the Processor properties on the Execution Framework tab of the Scenario
Properties dialog box influence how Stylus Studio generates code for your XML
pipeline. These properties are typically set when you first begin building an XML
pipeline, as they also influence how Stylus Studio processes any XQuery, XSLT, XML
Schema validation, or FO processing you have specified in your XML Pipeline.
See Specifying an Execution Framework for more information.

Stylus Studio User Guide

Warning

XML Parser

XML Serializer

XQuery

XSL-FO
See XML Pipeline Node Properties Reference for more information on these and other
node types.

1070

Stylus Studio User Guide

Generating Code for an XML Pipeline

Code Generation Settings

When you generate code for an XML pipeline, Stylus Studio displays a dialog box that
allows you to specify settings that affect the generated code. There are separate dialog
boxes for Java and C# code. The dialog box that appears is based on the execution
framework you selected for the XML pipeline.

Java Code Generation Settings

Figure 501. Generate Java Code for XML Pipeline Dialog Box

You use Generate Java Code for XML Pipeline dialog box to specify

The target directory in which you want the Java code created.
c:\temp\myPipelineJavaCode, for example. If the directory you name does not exist,
Stylus Studio creates it when you run the Java Code Generation wizard. The default
is . , which places the generated code in the same directory as the .pipeline file.

Optionally, a package name. If you specify a package name, Stylus Studio uses this
name to create a subfolder in the target directory you specify. If you specify
mypackage as the package name, for example, the generated code is written to
c:\temp\myPipelineJavaCode\mypackage. (Though optional, it is considered good
practice to create a package name.)

The class name. Stylus Studio also uses the class name for the .java file created by
the Java Code Generation wizard. For example, if you provide the name MyClass,
Stylus Studio creates c:\temp\myPipelineJavaCode\mypackage\MyClass.java.

Whether or not you want to add the generated code to the current project.

Whether or not you want to write an execution log file when the Java class runs.

Stylus Studio User Guide

1071

Building XML Pipelines

Whether or not you want to generate inline code. Inline code can be run anywhere,
as-is. If you choose not to generate inline code, you must ensure that the XML
Pipeline Java libraries, xmlpipeline. jar, is in your systems classpath.
Whether or not you want to embed the XQuery source in the generated Java code.
This option is available when using either the Saxon XQuery or DataDirect XQuery
processors. This option is available only if the Generate inline code check box is
selected.

All of these options are selected by default.

C# Code Generation Settings

Figure 502. Generate C# .NET Code for XML Pipeline Dialog Box

You use Generate C# .NET Code for XML Pipeline dialog box to specify

The target directory in which you want the C# code created.

c:\temp\myPipelineC#Code, for example. If the directory you name does not exist,
Stylus Studio creates it when you run the Code Generation wizard. The default is the
same directory as the .pipeline file.

Optionally, a namespace name. Stylus Studio uses the namespace name to create a
subfolder in the target directory you specify. If you use myNamespace, for example,
the generated code is written to c:\temp\myPipelineC#Code\myNamespace. (Though
optional, it is considered good practice to create a namespace.)

1072

Stylus Studio User Guide

Generating Code for an XML Pipeline

The class name. Stylus Studio uses the class name for the .cs file created by the Code
Generation wizard. For example, if you provide the name myClass, Stylus Studio
creates c:\temp\myPipelineC#Code\myClass.cs. Stylus Studio uses the XML pipeline
name as the default class name.
The location of Saxon .NET on your system. Stylus Studio adds this URL to the
Microsoft Visual Studio 2005 project, allowing the generated C# code for .NET to
compile.
Whether or not you want the resulting .cs file to contain a static void Main(String
[ ] args) method.
The argument for the setExecutionLog method in the generated application. Choices
are Console.out (the default), Console.err, and Quiet. Set to Quiet to turn off the log.
Whether or not you want to open the generated code file.
Whether or not you want to embed the XQuery source in the generated C# code. This
option is available when using either the Saxon XQuery or DataDirect XQuery
processors. This option is available only if the Generate inline code check box is
selected.
Whether or not you want to either create a new Visual Studio 2005 project or update
an existing one. If a new project is created, it is automatically opened with whatever
application is registered to open .csproj files. The .csproj file contains all the
necessary references to the generated .cs file, as well as all the .dll files that the .cs
file requires.
To run the .cs file, simply press Ctrl+F5 in Visual Studio.

How to Generate Code for an XML Pipeline

To generate code for an XML Pipeline:
1.

Open the XML Pipeline for which you want to generate code.

Display the Scenario Properties dialog box and

Select the desired scenario Stylus Studio generates code only for the active
scenario.

Make sure properties on the Execution framework tab are set appropriately. See
Execution Framework and Code Generation for more information.

Close the Scenario Properties dialog box.

Click the Generate Code button (

Stylus Studio User Guide

) on the XML Pipeline Editor toolbar.

1073

Building XML Pipelines

Alternative: Select XML Pipeline > Generate Code from the Stylus Studio menu.
Stylus Studio displays a dialog box that allows you to specify code generation
settings. There are separate dialog boxes for Java and C# code. The dialog box that
appears is based on the execution framework you selected for the XML pipeline.
See Code Generation Settings if you need help with this step.
5.

Click OK.
Stylus Studio generates code for the XML pipeline. If you generated Java code, the
resulting file (myPipeline.java, for example) is opened in the Stylus Studio Java
Editor.

Compiling Generated Java Code

The deployer automatically puts the JAR files required to compile the generated Java code
in the Stylus Studio project classpath. JAR files are in the \bin directory where you
installed Stylus Studio.

How to Compile and Run Java Code in Stylus Studio

In order to compile Java code, the JDK must be installed on your machine and configured
in Stylus Studio. Click Tools > Options > Java Virtual Machine to configure the JDK.

Figure 503. Configuring the JDK in Stylus Studio

1074

Stylus Studio User Guide

Generating Code for an XML Pipeline

To compile Java code in Stylus Studio:
1.

Make sure the Java Editor is the active window.

Click the Compile button (

).
Alternatives: Press Ctrl + F7, or select Java > Compile from the Stylus Studio menu.
Stylus Studio compiles the Java code. Results are displayed in the Output window.

Troubleshooting Compiling Inside Stylus Studio

If you have trouble compiling Java code in Stylus Studio
1.

Remove the existing Stylus Studio project classpaths from the Project Classpath
dialog box (select Project > Set Classpath from the menu).

Generate code again, which causes Stylus Studio to respecify the project classpaths.

Compiling Java Code Outside Stylus Studio

If you want to compile the Java code generated for your XML pipeline outside Stylus
Studio, you will need to manually set your classpath to include the JAR files listed at the
top of the generated .java file.

Running Java Code in Stylus Studio

To run Java code in Stylus Studio:
1.

Make sure the Java Editor is the active window.

Click the Run button ( ).

Deploying Generated Code

If your XML Pipeline uses built-in DataDirect XML Converters to convert CSV or
EDI to XML, for example you need to purchase licenses for the DataDirect XML
Converters you wish to use if you wish to deploy your code in any environment on a
machine (such as a test or application server) that does not have a license for the

Stylus Studio User Guide

1075

Building XML Pipelines

DataDirect XML Converters. Licenses for DataDirect XML Converters are purchased
separately from Stylus Studio X14 XML Enterprise Suite.
Similarly, if you use DataDirect XQuery in your XML pipeline, you must acquire
additional licences if you wish to deploy the XML pipeline application.
Write Stylus Studio at [email protected], or call 781.280.4488 for more
information.

XML Pipeline Node Properties Reference

This section contains reference information for XML pipeline node properties, including
their input and output ports. This section is organized as follows:

Choose Node Properties on page 1077

ConvertFromXML Node Properties on page 1078

ConvertToXML Node Properties on page 1079

Pipeline Node Properties on page 1080

Pipeline Input Node Properties on page 1081

Pipeline Output Node Properties on page 1082

Stop Node Properties on page 1082

Validate Node Properties on page 1083

Warning Node Properties on page 1084

XML Parser Node Properties on page 1085

XML Serializer Node Properties on page 1086

XQuery Node Properties on page 1087

XSL-FO Node Properties on page 1088

XSLT Node Properties on page 1089

1076

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Choose Node Properties

Input Port
Choose nodes can have as many input ports as you specify.
Table 131. Choose Input Port Properties
Property

Description

Name

The name displayed in the ports tooltip. Default value is Input#0.

This number is incremented by one for each additional input port
(Input#1, Input#2, and so on). Not editable.

DataType

The ports datatype. Default value is node(). Other values are

available in a drop-down list.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 132. Choose Node Properties
Property

Description

Name

The name you want to appear in the Choose nodes tooltip. Default
value is Choose.

Number of Inputs

The number of input ports you want the Choose node to have.

Number of Choices

By default, a Choose node has two choices one, which you

specify, and the else, which is implicit. You can use this property
to specify additional choices.

XPath #0

The XPath expression used to define the choices in the Choose

node. There is one XPath# property for each choice.

Stylus Studio User Guide

1077

Building XML Pipelines

Output Port
Each Choose node has at least two output ports Output#0, and Output no match. It will
have other output ports (Output#1, Output#2, and so on) if other choices have been defined
for the Choose node.
Table 133. Choose Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is node().

Copy to URL

The URL to which you want the output passed. Can be left blank.

ConvertFromXML Node Properties

Input Port
Table 134. ConvertFromXML Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is node.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 135. ConvertFromXML Node Properties

1078

Property

Description

Name

The name you want to appear in the ConvertFromXML nodes

tooltip. Default value is ConvertFromXML.

XML Converter URL

The URL of the DataDirect XML Converter (converter:CSV?, for

example) or of the user-defined custom XML conversion
(converter:file://c:\myFiles\myConverter.conv?, for example)
you want to use to convert XML input to some other format.

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Output Port
Table 136. ConvertFromXML Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is text.

Copy to URL

The URL to which you want the output passed. Can be left blank.

ConvertToXML Node Properties

Input Port
Table 137. ConvertToXML Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is node.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 138. ConvertToXML Node Properties
Property

Description

Name

The name you want to appear in the ConvertToXML nodes tooltip.

Default value is ConvertToXML.

XML Converter URL

The URL of the DataDirect XML Converter (converter:CSV?, for

example) or of the user-defined custom XML conversion
(converter:file://c:\myFiles\myConverter.conv?, for example)
you want to use to convert input to XML.

Stylus Studio User Guide

1079

Building XML Pipelines

Output Port
Table 139. ConvertToXML Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is node.

Copy to URL

The URL to which you want the output passed. Can be left blank.

Pipeline Node Properties

A Pipeline node does not display input and output ports unless the included pipeline it
represents (specified in the .pipeline File property) has Pipeline Input and Pipeline
Output nodes defined for it.

Input Port
Table 140. Pipeline Input Port Properties
Property

Description

Name

The name of the Pipeline Input node that is defined in the included
pipeline; not editable.

DataType

The ports datatype. Default value is text.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 141. Pipeline Node Properties

1080

Property

Description

Name

The name you want to appear in the Pipeline nodes tooltip. Default
value is Include Sub-Pipeline.

.pipeline File

The URL of the .pipeline file represented by the Pipeline node.

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Output Port
Table 142. Pipeline Node Output Port Properties
Property

Description

Name

The name of the Pipeline Output node that is defined in the included
pipeline; not editable.

DataType

The ports datatype. Default value is text.

Copy to URL

The URL to which you want the output passed. Can be left blank.

Pipeline Input Node Properties

Pipeline Input nodes have no input port.

Node
Table 143. Pipeline Input Node Properties
Property

Description

Name

The name you want to appear in the Pipeline Input nodes tooltip.
Default value is Pipeline Input.

DataType

The nodes datatype. Default value is any.

Default Value

The literal value or URL for the document or file you want to use as
the included pipelines main input.

Output Port
Table 144. Pipeline Input Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is any.

Stylus Studio User Guide

1081

Building XML Pipelines

The ports datatype. Default value is any.

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Node
Table 148. Stop Node Properties
Property

Description

Name

The name you want to appear in the Stop nodes tooltip. Default
value is Stop.

Message

The message you want written to output with the Stop node is
processed. The default is Error.

Validate Node Properties

Input Port
Table 149. Validate Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is node.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 150. Validate Node Properties
Property

Description

Name

The name you want to appear in the Validate nodes tooltip. Default
value is Validate operator.

XML Schemas

The URL of the XML Schema you want to use to validate the input.
You can specify more than one XML Schema.

Stylus Studio User Guide

1083

Building XML Pipelines

Output Port
The Validate node has two output ports one (named Output valid) used to direct input
if the XML Schema validation passes, the other (named Output invalid) used if the input
is invalid.
Table 151. Validate Node Output Port Properties
Property

Description

Name

The name displayed for the Output valid and Output invalid
ports; not editable.

DataType

The ports datatype. Default value is node.

Copy to URL

The URL to which you want to copy the output.

Warning Node Properties

Input Port
Table 152. Warning Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is any.

Node
Table 153. Warning Node Properties

1084

Property

Description

Name

The name you want to appear in the Warning nodes tooltip. Default
value is Warning.

Message

The message you want written to output with the Warning node is
processed. The default is Warning.

Stylus Studio User Guide

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is any.

Copy to URL

The URL to which you want to copy the output XML parser output.

XML Serializer Node Properties

Input Port
Table 158. XML Serializer Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is node.

Default Value

The default value for the input. Can be blank (this is the default).

Node
Table 159. XML Serializer Node Properties

1086

Property

Description

Name

The name you want to appear in the XML Serializer nodes tooltip.
Default value is XML Serializer.

format-pretty-print

Whether or not you want to format the output using pretty-print

(indenting nodes). The default is False.

xml-declaration

Whether or not you want the output to include an XML declaration.

The default is true.

encoding

The type of encoding you want to specify for the output. The default
is utf-8.

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Output Port
Table 160. XML Serializer Node Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is text.

Copy to URL

The URL to which you want to copy the output XML parser output.
Can be left blank.

XQuery Node Properties

Input Port
An XQuery node has one input port by default. Additional input ports are based on
external variables defined in the XQuery.
Table 161. XQuery Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

Data Type

Present for input ports corresponding to external variables.

Initialized with variables data type.

Default Value

The default value for the input. Can be blank.

Node
Table 162. XQuery Node Properties
Property

Description

Name

The name you want to appear in the XQuery nodes tooltip. Default
value is XQuery operator.

.xquery file

The URL of the XQuery file you want this node to represent.

DB Connections

Reserved for future use.

Stylus Studio User Guide

1087

Building XML Pipelines

Output Port
Table 163. XQuery Node Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is any.

Copy to URL

The URL to which you want to copy the XQuery output. Can be left
blank.

XSL-FO Node Properties

Input Port
Table 164. XSL-FO Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

DataType

The ports datatype. Default value is node.

Default Value

The default value for the input. Can be blank.

Node
Table 165. XSL-FO Node Properties

1088

Property

Description

Name

The name you want to appear in the XSL-FO nodes tooltip. Default
value is FO operator.

Stylus Studio User Guide

XML Pipeline Node Properties Reference

Output Port
Table 166. XSL-FO Node Output Port Properties
Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is binary.

Copy to URL

The URL to which you want to copy the XSL-FO output.

XSLT Node Properties

Input Port
An XSLT node has one input port by default. Additional input ports are based on
parameters defined in the XSLT.
Table 167. XSLT Node Input Port Properties
Property

Description

Name

The name displayed for the input port; not editable.

Default Value

The default value for the input. Can be blank.

Node
Table 168. XSLT Node Properties
Property

Description

Name

The name you want to appear in the XSLT nodes tooltip. Default
value is XSLT operator.

.xsl file

The URL of the XSLT file you want this node to represent.

Base URL

The URL you want to use to resolve hyperlinks and images in the
output. This value defaults from the XSLT scenario properties if it
was specified.

Stylus Studio User Guide

1089

Building XML Pipelines

Output Port
Table 169. XSLT Node Output Port Properties

1090

Property

Description

Name

The name displayed for the output port; not editable.

DataType

The ports datatype. Default value is any.

Copy to URL

The URL to which you want to copy the XSLT output. Can be left
blank.

Stylus Studio User Guide

Chapter 15

Publishing XML Data

This chapter describes how to use the Stylus Studio XML Publisher to create XSLT or
XQuery code that generates HTML+CSS or XSL-FO reports based on XML data.
Support for XML Publisher is available only in Stylus Studio XML Enterprise
Suite.
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the Introduction to the XML Publisher
video.
A complete list of the videos demonstrating Stylus Studios features is here:
http://www.stylusstudio.com/xml_videos.html.
This chapter covers the following topics:

The XML Publisher on page 1092

Building an XML Publisher Report on page 1093

Choosing a Report Format on page 1096

Working with Data Sources on page 1097

Adding Data to a Report on page 1111

Working with Report Components on page 1118

Generating Code for an XML Publisher Report on page 1144

Example: Building an XML Publisher Report on page 1148

Stylus Studio User Guide

1091

Publishing XML Data

Properties Reference on page 1154

Note The examples in this chapter rely on the books.xml and videos.xml documents that are

part of the examples project installed with Stylus Studio. These documents are in the
folders, respectively.

query and VideoCenter project

The XML Publisher

The Stylus Studio XML Publisher is a visual editor and code generator that helps you
create XSLT or XQuery that transforms XML into HTML+CSS or XSL-FO reports.

Figure 504. XML Publisher and Report Preview

You use the XML Publisher to select the data sources for your report, to build and format
the report using the desired data, and to preview a sample report before you generate the
XSLT or XQuery code.

1092

Stylus Studio User Guide

Building an XML Publisher Report

Parts of the XML Publisher Editor

The XML Publisher Editor has three main parts:

The XML Publisher canvas. You use the canvas to format your report and identify its
contents.

The data sources panel. You use the data sources panel to identify the XML sources
(relational tables and XML documents, for example) you want to include in your
finished report. You select the data you want in your report by dragging the nodes that
represent the data from the data sources panel and dropping them on the XML
Publisher canvas.

The Properties window. You use the Properties window to fine-tune settings that
affect the finished reports format and contents. For example, you can use XPath
expressions to specify formatting based on results returned by the XPath expression
against a given document node.
In addition, Stylus Studio displays the Preview window when you preview a report.

Building an XML Publisher Report

This section describes how to build an XML Publisher report. It contains the following
sections:

Process Summary on page 1093

How to Create an XML Publisher Report on page 1094

The XML Publisher Canvas on page 1095

Process Summary
The process of building an XML Publisher report involves the following basic steps:
1.

Create a new XML Publisher report document (File > New > XML Report).

Choose the report format (HTML or PDF). See Choosing a Report Format on
page 1096.

Add the source documents you want to use for the reports content. See Working
with Data Sources on page 1097.

Add the components you want in your report data, as well as formatting constructs
like lists and tables to the XML Publisher canvas. See Adding Data to a Report on
page 1111.

Stylus Studio User Guide

1093

Publishing XML Data

Optionally, format the data you have added to the XML Publisher canvas. See
Formatting Components on page 1136.

Preview the report; adjust data and formatting as required.

Once you are satisfied with the XML Publisher report, you can generate XQuery or XSLT
code for the report, choosing your desired report format (HTML or XSL-FO).
Each of these steps is described in greater detail in the following sections.

How to Create an XML Publisher Report

To create an XML Publisher report:
1.

Select File > New > XML Report from the Stylus Studio menu.
The XML Report Format dialog box appears.

Figure 505. XML Report Format Dialog Box

1094

Select the desired report format (HTML or PDF) and click OK.
An untitled .report document is opened in the XML Publisher.

Stylus Studio User Guide

Building an XML Publisher Report

The XML Publisher Canvas

When you create an XML Publisher report, Stylus Studio starts the XML Publisher and
displays a new report (untitled.report). The canvas representing the report is empty, as
shown here.

Figure 506. Empty Canvas in a New XML Publisher Report

The canvas represents the reports body, and all of the work you do when building a report
inserting XML data, tables, text and text blocks, and conditional expressions takes
place within the context of the body.
A useful way to think of the body is as the <body> tag in an HTML document everything
that you do on the report canvas would be described between the <body> and </body> tags
) in the
in an HTML document. This metaphor is represented by the Body glyph (
canvas navigation bar at the top of the canvas everything you subsequently add to the
report canvas will be represented as a child of the reports body.
See How Data is Represented on the Canvas on page 1113 and More About the
Navigation Bar on page 1115 for more information.

Stylus Studio User Guide

1095

Publishing XML Data

Choosing a Report Format

When you create an XML Report in Stylus Studio, you need to specify the format you
want for the finished report HTML (XHTML+CSS) or PDF (XSL-FO). Stylus Studio
can generate XQuery or XSLT code for either format. You specify report format using the
XML Report Format dialog box, which appears when you create a new XML Report in
Stylus Studio:

Figure 507. XML Report Format Dialog Box

Specifying a format up front allows Stylus Studio to use format information to expose
format-specific properties like headers and footers for reports in PDF, for example to
help speed and simplify report creation.

1096

Stylus Studio User Guide

Working with Data Sources

You can use any of the following as data sources for building XML Publisher reports:

XML documents

XML Schema or DTD

Relational database tables

EDI and flat files like CSV converted to XML using one of the DataDirect XML
Converters

Web services
This section covers the following topics:

How Data Sources are Represented in XML Publisher on page 1097

Adding a Data Source on page 1098

Specifying a Default Data Source on page 1099

Data Source Required for XSLT on page 1100

Using XML Schema or DTD as a Data Source on page 1100

Grouping Data on page 1102

How Data Sources are Represented in XML Publisher

When you add a data source to the data sources panel, Stylus Studio displays the schema
representation, or the data model, for that source. The following illustration shows how
the videos.xml document from the VideoCenter folder in the examples project appears
after it has been added as a data source:

Figure 508. XML Document in the Data Sources Panel

Stylus Studio User Guide

1097

Publishing XML Data

Working with Namespaces

If the document you have selected as a source uses a namespace prefix, Stylus Studio
displays the prefix and the URI at the bottom of the data sources panel, as shown in
Figure 509.

Figure 509. Namespace Prefix and URI

You can edit the value in the Namespace field, which can simplify the process of typing
XPath expressions you might use when defining a property. For example, you could
change books to simply b to shorten and simplify XPath expressions. See Example:
Using Context and XPath Sub-Properties to Format Text on page 1133 to learn more
about using XPath expressions when building XML Publisher reports.

Adding a Data Source

To add a data source you can

Drag a document or file from the Project or File Explorer windows and drop it on the
data sources panel.
Drag a relational database table from the File Explorer window and drop it on the data
sources panel.
Click the Add Data Source button ( )on the data sources panel and use the Open
dialog box to navigate to the desired data source.

You can use multiple data sources for an XML Publisher report.

1098

Stylus Studio User Guide

Working with Data Sources

Specifying a Default Data Source

Stylus Studio uses the first data source you add as the default data source. The default data
source is specified as the Main input for XQuery scenarios, and as the Source XML URL
for XSLT scenarios. In other words, when you generate XQuery or XSLT for your XML
Publisher report, the default data source is automatically specified in the scenario
properties, as shown in Figure 510.

Figure 510. Default Data Source Used in Generated XSLT

The red check on the document icon (see Figure 508) indicates a data sources default
status. You can specify any data source you add as the default data source.
To specify the default data source:
1.

In the data sources panel, select the data source you want to specify as the default
(books.xml, in Figure 511, for example).

Stylus Studio User Guide

1099

Publishing XML Data

Click the Set As Default button ( ).

The data source is set as the new default, as indicated by the red check.

Figure 511. Setting a Different Default Data Source

Data Source Required for XSLT

While it is considered good practice to specify a data source regardless of whether you are
planning to generate XQuery or XSLT, a data source is required only for XSLT. In
addition, if your XML Publisher report has multiple data sources, one of them must be
designated as the default data source. See Specifying a Default Data Source on
page 1099 for more information.
See Sources on page 1145 to learn more about how additional sources are treated by
Stylus Studio when generating XQuery and XSLT from XML Publisher.

Using XML Schema or DTD as a Data Source

If you use XML Schema or DTD documents as sources for XML Publisher reports, you
need to

Choose the element from the XML Schema or DTD you want to use as the root
element

Associate the XML Schema or DTD with an XML instance

This section describes how to perform these procedures.

1100

Stylus Studio User Guide

Working with Data Sources

Choosing a Root Element

When you add an XML Schema or a DTD to the data sources panel, Stylus Studio
displays the Choose Root Element dialog box, shown in Figure 512.

Figure 512. Choose Root Element Dialog Box

The Choose root element drop-down list displays all the child elements of the XML
Schema or DTD document you selected as a data souce. Select the element you want to
use as the document root and click OK.

Associating an XML Instance with the Schema

Before you can preview or generate code for an XML Publisher report, you need to
associate an XML document, referred to as an XML instance, with any XML Schema or
DTD documents you are using as source documents.
When you click the Preview or Generate buttons on the XML Publisher toolbar, if you
have not already associated an XML instance with the schema you are using as data
sources, Stylus Studio displays the Associate with XML Instance dialog box, shown in
Figure 512.

Figure 513. Schema Instance Dialog Box

Stylus Studio User Guide

1101

Publishing XML Data

Each entry in the Schema field represents an XML Schema or DTD document used as a
data source. To associate it with an XML instance:
1.

Click the XML Instance field.

Stylus Studio displays the Open dialog box.

Choose the XML document you want to use as the XML instance and click the Open
button.
The Open dialog box closes; the URL for the file you selected appears in the XML
Instance field.

Click OK.
Stylus Studio previews the XML Publisher report, or begins the code generation
process.

Grouping Data
Watch it! You can view a video demonstration of this feature by clicking the
television icon or by clicking this link: watch the XML Publisher data grouping
video.
The ability to group data from one or more data sources is a common requirement for
many reports. For example, given the videos.xml file, you might want to create a list of
actors that shows all the movies in which he or she has starred.
Stylus Studio facilitates grouping using a feature that allows you to create a relationship
between different data sources (between books.xml and catalog.xml, for example), or
between different data islands within the same source (between two nodes in videos.xml,
for example).
This section describes the relationship feature in XML Publisher and how to use it to
perform grouping.

What is a Relationship?
A relationship is a link between two nodes in one or more data sources that allows you to
compare the values of those nodes. For example, in videos.xml, you might want compare
the value of the id attribute of the actor element with the value of actorRef element, and
then perform some action when those values are equal.

1102

Stylus Studio User Guide

Working with Data Sources

Comparison operations you can define for a relationship are

Equal

Not equal

Less than

Greater than

Less than or equal to

Greater than or equal to

When you create a relationship in XML Publisher, you are defining the inner and outer
loops of the for-each statements in your XSLT or XQuery code that will be used to
perform the grouping (xsl:for-each in XSLT; FLWOR instructions in XQuery). The
order of the nodes you select determines the order in which the outer and inner loops are
created:

The first node you select is used to define the outer loop

The second node you select is used to define the inner loop

Creating a Relationship
Once you have added one or more data sources to the data sources panel, you can create
a relationship between nodes within the same data source, or across data sources.
To create a relationship:
1.

Add the data source(s) you require for your report. See Adding a Data Source on
page 1098 if you need help with this step.

Select the node you want to use to define the outer loop in the XQuery or XSLT that
will be used to create the report.
The Add Relationship button becomes active, as shown here:

Figure 514. Add Relationship Button for XML Publisher

Stylus Studio User Guide

1103

Publishing XML Data

Click the Add Relationship button.

The Create Relationship dialog box appears. The tree for the document appears in the
Link From field. The document that appears in the Link To field depends on how many
data sources you added in Step 1.

Figure 515. Create Relationship Dialog Box

By default, Stylus Studio sets the nodes context using the first repeating element in
the selected nodes hierarchy including the selected node itself. In this example, we
selected the id attribute of the actor element, so the actor repeating element is used
to set the context for this loop.

1104

Optionally, change the key node and context.

In the Link To field, select the node you want to use to define the inner loop in the
XQuery or XSLT that will be used to create the report. If you defined more than one
data source in Step 1, you can change the data source in the Data Source drop-down
list.

Stylus Studio User Guide

Working with Data Sources

In this example, we selected videos/video/actorRef repeating element.

Figure 516. Second Node in a Relationship

Optionally, change the context of the node you selected in Step 5.

Choose the comparison operator you want to use to define this relationship from the
Operator drop-down list.

Click OK.
The relationship you just defined appears in the data sources pane of the XML
Publisher Editor.

Figure 517. Relationship Defined as a Data Source

Stylus Studio User Guide

1105

Publishing XML Data

If you expand the relationship node, you see the graphic representation of the join
formed between the actors/actor/id node and the videos/video/actorRef node.

Figure 518. Join Displayed as a Data Source

You can now use this relationship as a data source in XML Publisher. See Example
Using a Relationship in a Report on page 1106 for more information.

Example Using a Relationship in a Report

This example describes how to build a simple report in XML Publisher, shown here, that
lists actors and the movies they have appeared in. The information for this report is based
on the data in videos.xml, in the VideoCenter folder in the Stylus Studio examples project.

1106

Stylus Studio User Guide

Working with Data Sources

Specifically, it matches the id attribute in the actors/actor element with the

videos/video/actorRef element.

Figure 519. Example Report

To create the example report:
1.

Click File > New > XML Report to open the XML Publisher Editor.

Drag videos.xml from the VideoCenter folder in the Stylus Studio examples project
and drop it on the data sources panel in the XML Publisher Editor.
Stylus Studio displays a tree representing the videos.xml document.

Expand the actors node by selecting it and pressing the * key on your number pad.

Select the id attribute.

Click the Add Relationship button.

Stylus Studio User Guide

1107

Publishing XML Data

The Create Relationship dialog box appears.

Figure 520. Create Relationship Dialog Box

In the Link To field, expand the videos node and select the actorRef repeating
element.

Since we want the loop on the video element (to locate all movies with a matching
actorRef and id), change the value in the Context field to video (also a repeating
element).

Figure 521. Changing the Context of the Target Node

1108

Stylus Studio User Guide

Working with Data Sources

Click OK.
The data source defined by the relationship we just created between the actors and
videos nodes appears in the data sources pane.

Drag the newly defined data source from the data sources pane and drop it on the
XML Publisher canvas.
Stylus Studio creates two loops.

Figure 522. Repeating Loops in the XML Publisher Canvas

If you place the mouse over the outer loop, the tool tip displays the XPath
/result/actors/actor; similarly the XPath for the inner loop is
/result/videos/video[$actor/@id./actorRef].
Now that the context for the loops has been defined, we next need to specify the data
we want to display.
10.

From the data sources panel, drag the videos/video/title element and drop it in the
inner loop.

11.

From the data sources panel, drag the actors/actor element and drop it in the outer
loop. Select Insert Value from the pop-up menu.
When you have finished, your XML Publisher canvas should look like this:

Figure 523. XML Publisher Before Formatting

Stylus Studio User Guide

1109

Publishing XML Data

12.

Click the Preview button ( ), and save the file when prompted.
Before formatting, the report looks like this:

Figure 524. Draft Report

All the information is there, but the report is hard to read.

13.

Select the .(actor) glyph in the XML Publisher canvas and click the Bold button on
the XML Publisher tool bar. Add a carriage return (press Enter) after the glyph.

14.

Use the space bar to indent the title glyph. Add a carriage return (press Enter) after
the glyph.

15.

Preview the report again.

We now have a report that resembles the one shown in Figure 519.

Figure 525. Final Report

1110

Stylus Studio User Guide

Adding Data to a Report

Deleting a Relationship
You can delete the relationships you have defined as data sources for XML Publisher
reports just as you would any other data source.
To delete a relationship:
1.

Select the relationship you want to deletein the data sources pane.

Click the Remove Relationship button.

The relationship is removed from the XML Publisher.

Adding Data to a Report

Once you have added one or more data sources to the data sources panel, you can specify
the data you want to include in your XML report. This section describes how to add data
to a report and how it is represented on the XML Publisher canvas.
This section covers the following topics:

How to Add Data to a Report on page 1111

Example: Dropping a Repeating Node on page 1112

How Data is Represented on the Canvas on page 1113

More About the Navigation Bar on page 1115

How to Add Data to a Report

There are essentially two ways to add data to a report:

Automatically. You can drag a node from the data sources panel and drop it on the
canvas. When you do, Stylus Studio displays a short-cut menu that displays the types
of components you can create based on the node you have selected. For example, if
you select a repeating element, you can create components that loop tables and lists,
for example.

Manually. You can add an empty component to the report using the main menu
(Report > Insert List, for example) or the canvas short-cut menu (right-click on the
canvas), and then populate the component by dragging and dropping nodes from the
data sources panel. Alternatively, you can specify Context and XPath properties in the
Properties window for the component you want to populate.
The benefit of using the automatic method is that Stylus Studio determines the context and
XPath settings required to return the data you have selected. In addition, when you drop
Stylus Studio User Guide

1111

Publishing XML Data

the node on the canvas, Stylus Studio displays on the short-cut menu only those choices
that are applicable to the node you selected from the data sources panel.

Example: Dropping a Repeating Node

As described earlier, the data source whether it is an XML document, a relational
database table, an EDI file converted to XML, or some other XML data source is
represented as a data model in the data sources panel. The glyphs used for the nodes are
based on the object they represent in the data source, as shown here.

Figure 526. Glyphs Used to Represent a Data Source

For this example, we use books.xml as the reports data source. When we drop the book
repeating element on the canvas, we select Insert Table > Populated Columns from the
short-cut menu. Stylus Studio creates a table with five columns, one for each of the child
nodes in the book repeating element, as shown in Figure 528.

Figure 527. Table Created Automatically Using Repeating Element Child Nodes

1112

Stylus Studio User Guide

Adding Data to a Report

The following table summarizes the types of components you can create and
automatically populate with data based on the node type.
Table 170. Components for Repeating and Non-Repeating Nodes
Repeating Nodes

Non-Repeating Nodes

Text

Image

Table (either a table with three empty

columns, or a table with one column for each
child node of the repeating element)

Repeater

List

Note You cannot drag document nodes.

See Working with Report Components on page 1118 for information about specific
components.

How Data is Represented on the Canvas

Data is represented by glyphs that contain an XPath expression. The composition of these
XPath expressions varies based on the context of the component in which the data is being
included. The glyph might contain just an element name, or it might display a longer
XPath expression if it represents data whose context is not established by the containing
component.

Example
The context for the table component shown in Figure 528 is the video repeating element
from the videos.xml document. You can see this if you select the table in the canvas and
look at either the

The Context and XPath sub-properties for the repeating row

Stylus Studio User Guide

1113

Publishing XML Data

The Video table glyph in the navigation bar

Figure 528. Value Glyphs on the XML Publisher Canvas

Tip You can see the context for any piece of data or component by hovering the mouse pointer

over it. When you do, Stylus Studio displays a tooltip that includes the URL and XPath.
The following table shows the different types of XPath expressions you might see in an
XML Publisher report.
Table 171. Explanation of XPath Expressions in Data Glyphs
Data Glyph

1114

Contains

Description

The current context

The XPath expression for context is a dot. To

make this easier to see in the glyph, Stylus
Studio adds the element name in parentheses
following the dot.

An element (or attribute)

name

If the context is established by the containing

component, the data glyph contains only the
element or attribute name.

A full XPath

If the context for the data is not established by

the containing component, Stylus Studio
displays the full XPath needed to resolve it.

Stylus Studio User Guide

Adding Data to a Report

More About the Navigation Bar

As you add components to your report, Stylus Studio adds glyphs that represent them to
the canvas navigation bar. You can click these glyphs to place the editors focus on a
specific component; similarly, when you select a component from the canvas, the glyphs
in the navigation bar change to reflect the editors current focus.
Consider the following report it contains two tables, each with a number of columns,
and some text headings.

Figure 529. Report Body Glyph Collapsed by Default

The Body glyph in the navigation bar represents the reports body. The dark blue means
that the report body the table headings and empty paragraph markers has the editors
focus. In other words, any editing performed now changing the text to italic, or making
the background a different color, for example would affect every object in the report
body.
The plus sign next to the Body glyph indicates that the report body has at least one child.
Our report has two children the table containing video data, and the table containing
book data. If we click the plus sign, Stylus Studio displays a drop-down menu that lists
the children of the report body, and we see the entries for the video and book tables.

Figure 530. Plus Sign Indicates Children

Stylus Studio User Guide

1115

Publishing XML Data

Click the Glyph to Navigate

You can use the glyphs in the navigation bar to quickly change the editors focus to the
component you select. If we select book from the Body glyph drop-down menu, for
example:

The editors focus moves to the book table. Notice the dashed line around the table in
Figure 531.

The navigation bar changes to reflect the editors focus.

Figure 531. Clicking Navigation Bar Glyphs Changes Editor Focus

Notice that the book glyph, which represents the table containing book data, has two
symbols to its right:

The plus sign, which indicates that the table has children. A tables children are its
cells.

The down arrow, which indicates that the table has siblings. In this example, the table
containing video data is the sibling of the current table.

1116

Stylus Studio User Guide

Adding Data to a Report

If we now click a cell directly, say, the cell containing author data, notice how the
navigation bar changes:

Figure 532. The Navigation Bar Operates as a Tree Based on Report Context

In this fashion, the navigation bar operates a tree, always showing you the report
component that currently has focus. Components are displayed from the most general to
the most specific. Look at the navigation bar in Figure 532. When the author glyph in the
table is selected, the glyphs in the navigation bar are interpreted this way (from left to
right):
Table 172. Explanation of Example Navigation Bar Tree
Navigation Bar Glyph

Represents
The entire report. Every other component is a child of the body
component.
The book table. The down arrow means that the table has
siblings.
The cells in the book table. The down arrow means that the cell
has siblings the other cells in the table.
The list component built on the author element.
An item in the list component.
The dynamic value of the author element. It is dark blue
because in our example (Figure 532), it is the report component
that currently has focus.

Stylus Studio User Guide

1117

Publishing XML Data

Notice the video table is not represented in the navigation bar. This is because the current
context in the report canvas is owned by the book table. You can quickly change context
in the canvas by either

Clicking a cell in the video table or the video table itself

Using the down arrow on the table glyph (which currently displays book) to select
video

Note Repeater and text block components have their own glyphs.

Working with Report Components

This section describes the types of components you can include in an XML Publisher
report and how to create and work with them.
This section covers the following topics:

Types of Components on page 1118

Tables on page 1119

Lists on page 1122

Text on page 1124

Images on page 1125

Repeaters on page 1128

Ifs on page 1129

Component Properties on page 1132

Formatting Components on page 1136

Formatting Decimal Numbers on page 1141

Types of Components
There are two types of components you can include in an XML Publisher report:

Visual components; these are components that have a visual representation in the
published HTML or XSL-FO report. Examples include tables and lists.

Non-visual components; these are components that do not have a visual representation
in a finished report. Examples include repeaters and ifs.
All components, regardless of type, are represented graphically on the XML Publisher
canvas.

Repeater

Non-visual

See Repeaters on page 1128

Non-visual

See Ifs on page 1129

Tables
A table is a visual component that usually iterates over the data it contains. You typically
create a table when you want your report to display multiple rows with two or more
columns of dynamic data one row for each movie in the videos.xml file, with each row
containing the movies title, its genre, and its rating, for example.

Figure 533. Example Table and Output

Stylus Studio User Guide

1119

Publishing XML Data

If your data can be displayed in a single column (only movie titles, for example), you
might want to consider using either the list or repeater components. See Lists on
page 1122 and Repeaters on page 1128 for more information.

Creating a Table
The easiest way to create a table in XML Publisher is to drag and drop a repeating
element. When you drop the repeating element on the canvas, Stylus Studio displays a
short-cut menu with an Insert Table choice. You can insert a table with either

Populated Columns Stylus Studio creates a table with one column for each of the
child nodes of the repeating element. The tables context and XPath are set based on
the repeating element used to create it. Each column contains a data value glyph
representing a child node.

Empty Stylus Studio creates table with three empty columns. As with the previous
option, the tables context and XPath are set based on the repeating element used to
create it, but it is up to you to select from the data sources pane the child nodes you
want to include in the table.
You can also create a table manually (Report > Insert > Table, or select Insert Table from
the canvas short-cut menu). When you create a table like this, however, the context and
XPath are not set for you, and it will only contain the number of rows you explicitly create
for it unless you also define the Loop property for a row.

Graphical Representation
Tables, like the one shown in Figure 534, are displayed as a single row with a loop symbol
( ); the loop symbol indicates a repeating row.
Figure 534 shows a table based on the book repeating element in books.xml that was
created using the Populated Columns short-cut menu choice.

Figure 534. Table Created with Populated Columns

Figure 535 shows a table based on the same repeating element, but it was created using
the Default Columns short-cut menu choice.

Figure 535. Table Created with Default Columns

1120

Stylus Studio User Guide

Working with Report Components

Finally, Figure 536 shows a table that was created manually using the Report menu.
Notice that it does not have the loop symbol associated with repeating rows.

Figure 536. Manually Created Table

Sorting
By default, data for dynamic rows is displayed in document order. You can use an XPath
expression in the Loop propertys Sort sub-property to specify a different sort order. The
Loop property appears on the Row tab of the Properties window.

Adding Rows and Columns

To add rows and columns to a table:
1.

Select the cell before or after which you wish to add a row or column.

Right-click.
Stylus Studio displays a short-cut menu.
Alternative: Click the Report > Table menu.

Select the appropriate choice from the menu.

Deleting Rows, Columns, and Tables

To delete a row, column, or table:
1.

Select a cell in the row or column you want to delete.

Click the Delete button in the toolbar (

).
Stylus Studio displays a drop-down menu.
Alternative: Right-click.
Alternative: Click the Report > Table menu.

Select the appropriate choice from the menu.

Stylus Studio User Guide

1121

Publishing XML Data

Lists
A list is visual component that iterates over the data it contains and contains one or more
items. You typically create a list when you want your report to display a list of dynamic
values all the books, by title, in the books.xml document, for example.

Figure 537. Example List and Output

Lists are formatted using bullets, but you can choose numeric, alphabetic, and other
symbols like squares and circles. Depending on your needs, you might prefer to use the
repeater or table components for dynamic data. See Repeaters on page 1128 and
Tables on page 1119 for more information.

Creating a List
The easiest way to create a list in XML Publisher is to drag and drop a repeating element.
When you drop the repeating element on the canvas, Stylus Studio displays a short-cut
menu with an Insert List choice. The lists context and XPath are set based on the
repeating element used to create it. You specify the data you want the list to contain by
dragging the appropriate node from the data sources panel and dropping it in the list as
Value.
You can also create a list manually (Report > Insert > List, or select Insert List from the
canvas short-cut menu). When you create a list like this, however, the context and XPath
are not set for you, and it will iterate over the data you specify only if you also define the
Loop context and Xpath properties for an item.

1122

Stylus Studio User Guide

Working with Report Components

Graphical Representation
As shown in Figure 537, a list is represented as a bounding box drawn with a dashed line
containing a bullet symbol and, usually, a loop symbol ( ). If you created the list
manually, the loop symbol appears only if you specify the Loop propertys Context and
XPath sub-properties for an item.

Sorting
By default, data for dynamic lists is displayed in document order. You can use an XPath
expression in the Loop propertys Sort sub-property to specify a different sort order.

Adding Items
To add items to a list:
1.

Select the item before or after which you wish to add a new item.

Right-click.
Stylus Studio displays a short-cut menu.
Alternative: Click the Report > List menu.

Select the appropriate choice from the menu.

Deleting an Item or a List

To delete an item or a list:
1.

Select the item or list you want to delete.

Click the Delete button in the toolbar (

).
Stylus Studio displays a drop-down menu.
Alternative: Right-click.
Alternative: Click the Report > List menu.

Select the appropriate choice from the menu.

Stylus Studio User Guide

1123

Publishing XML Data

Text
A text component is a block that allows you to create an area for text that can be formatted
independently from the body text in a report. The text component in Figure 538 has been
formatted using a crimson italic font, which differs from the default body text that
precedes and follows it.

Figure 538. Body Text and Text Component

Text components and body text have the same properties (Alignment, Font, Color, Size,
and so on).

Creating a Text Component

To create a text component:
1.

Click the canvas where you want to insert the text component.

Select Report > Insert > Text from the menu.

Alternative: Right-click and select Insert Text from the short-cut menu.

Graphical Representation
In the XML Publisher canvas, a text component is represented, when selected, as a
bounding box drawn with a dashed line. If the text component is not selected, the
bounding box does not appear.

1124

Stylus Studio User Guide

Working with Report Components

Images
An image is a component that contains a GIF, JPEG, or some other graphic file. You can
place image components within other components (like tables, lists, and repeaters, for
example), or directly on the report body.

Creating an Image
To create an image component:

Note

Click the canvas where you want to insert the image component.

Select Report > Insert > Image from the menu.

Alternative: Right-click and select Insert image from the short-cut menu.

Specify the location of the image file(s). See Specifying an Image Source on
page 1126 for more information.
The location of all image files must be specified relative to the target destination of
the HTML+CSS or XSL-FO. For example, do not specify c:\myFiles\images as a
source directory unless that directory is accessible to the finished report.

Graphical Representation
In the XML Publisher canvas, an image is represented as a small square with a crosshatched pattern. Figure 539 shows an image component that includes some text to its right
(photo of the author).

Figure 539. Image (with text)

Images are resolved when you preview the report only if the image files are accessible to
Stylus Studio using the source information you have specified. Unresolved images are
rendered as red Xs, as shown in Figure 540:

Figure 540. Symbol for Unresolved Image in Preview Window

Stylus Studio User Guide

1125

Publishing XML Data

Specifying an Image Source

You can use static and dynamic images in a report. A static image is one that never
changes. An example of a static image is a corporate logo that appears in a fixed place on
a report. To specify a static image, just the complete file URL in the images Source
property file://c:\MyProjects\StylusLogo.gif, as shown in Figure 541.

Figure 541. Example of a Static Image

A dynamic image is one whose source changes based on the context defined for it. An
example of a dynamic image is the cover art for the movies in the videos.xml document
the image varies based on the video id as determined by the current context.
To specify a dynamic image, you need to define the image components Source propertys
Context and XPath sub-properties:

Context defines the document context for the evaluation of the Source propertys
XPath sub-property. This can be a source document URL, or a variable.

XPath an XPath expression used to evaluate the source document; the context for
the XPath expression is determined by the Context sub-property. This can be any
XPath expression.
When you specify these properties, Stylus Studio displays <dynamic> in the Source
property field.
Note Regardless of whether you are using static or dynamic images, the image source must be

available to the finished HTML+CSS or XSL-FO report.

Example: Specifying a Dynamic Image Source
The cover art for the movies in the videos.xml document are written to the
where you installed Stylus Studio. The

\examples\VideoCenter\images\video\ directory

1126

Stylus Studio User Guide

Working with Report Components

name of each .gif file is the same as the value of the id attribute of the video repeating
element. We want to create a simple table displaying the movies title and its cover art, as
shown in Figure 542.

Figure 542. Example of Dynamic Images

To create this report in XML Publisher, we would:

Create a table by dragging the video repeating element and dropping it on the canvas.
This establishes the context for the cells in the table, as well as creating a value,
$video, that represent this context.

Drag and drop the title element in the tables first cell (as a value).

Right-click and insert an image component in the tables second cell.

Specify the context for the image:

Change the image components Context sub-property to $video. The context for
this variable (result/videos/video) was established automatically when we used
the video repeating element to create the table.

Change the image components XPath sub-property to concat(@id).gif. This

concatenates the value of the current id attribute with the string .gif to identify
image file to display. The source for these image files is specified in the following
step.

Stylus Studio User Guide

1127

Publishing XML Data

Specify the source for the image files change the body components Base URI
property to c:\Program Files\Stylyus Studio\examples\VideoCenter\images
\video\, or wherever you have installed Stylus Studio.

Specifying Image Size

By default, Stylus Studio displays the image in the finished report using the source files
dimensions. You can use the image components Width and Height properties to specify
a different size. When you do this, Stylus Studio changes the dimensions of the image
glyph (see Figure 539) on the canvas to reflect the change.

Repeaters
A repeater is a component that iterates over data in a data source based on the context
defined for it. When the report is executed, a new line is added to the report for each new
value. These lines are not formatted in any way, so, depending on your needs, you might
prefer to use the list or table components for repeating data. See Lists on page 1122 and
Tables on page 1119 for more information.

Creating a Repeater
The easiest way to create a repeater in XML Publisher is to drag and drop a repeating
element. When you drop the repeating element on the canvas, Stylus Studio displays a
short-cut menu with an Insert Repeater choice. The repeaters context and XPath are set
based on the repeating element used to create it. You specify the data you want the
repeater to contain by dragging the appropriate node from the data sources panel and
dropping it in the repeater as Value.
You can also create a repeater manually (Report > Insert > Repeater, or select Insert
Repeater from the canvas short-cut menu). When you create a repeater like this, however,
the context and XPath are not set for you, and it will iterate over the data you specify only
if you also define the Loop context and Xpath properties for an item.

Graphical Representation
In the XML Publisher canvas, a repeater is represented as a bounding box drawn with a
dashed line, usually with a loop symbol ( ) on the left side of the bounding box.
Figure 543 shows a repeater based on the title element in videos.xml. It was created by
1.

1128

Dragging the video repeating element on the canvas and selecting Insert Repeater
from the short-cut menu.
Stylus Studio User Guide

Working with Report Components

This action defines the context for the iterative action.

Dragging the title element and dropping it inside the repeater.

This action defines the data to be included in the repeater.

Figure 543. Repeater with a Text Value

The loop symbol is present only if the repeaters Loop property has values specified for
its Context and XPath sub-properties. You can specify these properties manually in the
Properties window, but it is usually easier to create the repeater by dragging a repeating
element, dropping it on the canvas, and choosing Insert Repeater.

Sorting
By default, data for the repeater component is displayed in document order. You can use
an XPath expression in the Loop propertys Sort sub-property to specify a different sort
order.

Ifs
An if is a component that represents a condition (if... then... else...). You can use if
components to control report content. You can insert if components within other
components (within a table cell, for example).

Creating an If
The easiest way to create an if component in XML Publisher is to select Report > Insert
> If from the Stylus Studio menu, or select Insert If from the canvas short-cut menu.
The if components context is established automatically only if you insert within another
component such as a table or list whose context is already set. The if component does
not inherit its context from the body component.

Stylus Studio User Guide

1129

Publishing XML Data

Graphical Representation
In the XML Publisher canvas, an if component is represented as two tabs, true and false,
within a bounding box drawn with a dashed line. Figure 544 shows an empty if
component.

Figure 544. If Component

Example
We need to create a report that contains a simple table that lists the title and rating for all
movies in the videos.xml document. In addition, if the movie carries an R rating, we
want to display the R-rated symbol (
) for emphasis. A sample of the report is

Figure 545. Example of an If Component

To create this report in XML Publisher, we would:

1130

Create a table by dragging the video repeating element and dropping it on the canvas.
This establishes the context for the cells in the table.

Drag and drop the title element in the tables first cell (as a value).

Stylus Studio User Guide

Working with Report Components

Right-click and insert an if component in the tables second cell.

Select the if component and click the If tab in the Properties window.

Set the Condition property to rating=R.

Specify the true condition:

Select the true tab.

Right-click and select Insert Image.

Set the image components Source property to the location of the image we want
to display for R-rated movies (c:\MyProjects\images\r_rating.gif, for
example).

Figure 546. Setting the True Condition

Specify the false condition:

Select the false tab.

Drag the rating node from the data sources panel and insert it as a value.

Figure 547. Setting the False Condition

Stylus Studio User Guide

1131

Publishing XML Data

Component Properties
Each component in a report the body, tables, lists, repeaters, and so on is associated
with a set of properties that control its formatting and content. The text component has
properties for Color, Font, Size, and so on. The Color property, for example, lets you
select aqua, bisque, blue, and so on. Properties vary based on the component. (See
Properties Reference on page 1154 for a complete list.)

Context and XPath Sub-Properties

Each property has Context and XPath sub-properties that let you define the conditions
under which you want to, say, display a value or apply a given formatting characteristic.
You can use the Color propertys Context and XPath sub-properties to format text based
on the value returned by an XPath expression format all R rated movies in videos.xml
using the color red, for example. (See Example: Using Context and XPath SubProperties to Format Text on page 1133 later in this section for an illustration of this
technique.)

The Properties Window

Component properties are displayed in the Properties window, a dockable window you
can place anywhere on your desktop.
To display the Properties window, click View > Properties

Figure 548. Properties Window

The Properties window consists of one or more tabbed pages. The specific tabs that are
present in the Properties window vary based on the component you have selected in the
report canvas. As shown in Figure 548, the Properties window for the rating element in
the video table includes tabs for the
1132

Stylus Studio User Guide

Working with Report Components

The context and XPath expression that return the dynamic value of the rating element
Text value
Cell
Column
Row
Table

The order of the tabs in the Properties window reflects the hierarchy of the currently
selected component, from the most specific (the currently selected component) to the
most general (the parent component to which it belongs), left to right. The report body has
Document, Decimal Format, and Text tabs that let you control global formatting
characteristics.

Example: Using Context and XPath Sub-Properties to Format Text

Our report contains a table based on the video element from videos.xml; the table lists the
movie title and rating. When we preview the report, we see that if a movies rating is R
the rating is displayed in red, while other movie ratings are displayed using the default
color.

Figure 549. Preview of an XML Publisher Report

Stylus Studio User Guide

1133

Publishing XML Data

If we look at the properties for the rating element, we can see how this was achieved.

Figure 550. Properties for the Rating Element

As you can see, Default Color property is specified as <dynamic>. Stylus Studio sets the
Default Color property to this value automatically when you specify

A context for the evaluation of an XPath expression defined in the XPath property.
Here, the context is $video. Stylus Studio created this variable, which represents the
videos.xml document, when we created the table using the video repeating element
from this document.

An XPath expression to be evaluated in the context defined by the Context property.

Here, the XPath expression is if (rating = 'R') then "red" else "".
Together, these properties control when data from the rating element in the videos.xml
document is set to the color red.

1134

Stylus Studio User Guide

Working with Report Components

Entering XPath Expressions

You can enter an XPath expression by typing directly in the XPath field. If you prefer, you
can use the XPath Editor dialog box, shown in Figure 551.

Figure 551. XPath Editor Dialog Box

The XPath Editor dialog box supports Stylus Studios Sense:X auto-completion and text
coloring, which can provide useful prompts as you type your XPath expression.
To display the XPath Editor dialog box:
1.

Click the XPath entry field for the property you want to define.
The text cursor and a more button appear in the field.

Figure 552. Opening the XPath Editor Dialog Box

Click the more button.

Stylus Studio displays the XPath Editor dialog box.

Stylus Studio User Guide

1135

Publishing XML Data

Formatting Components
Formatting in XML Publisher works in a fashion similar to that of formatting in many text
and graphical editors you select the item you want to format and then apply a style from
a tool bar, menu, or palette. An item can be

One or more words

A component like a list or table

A glyph representing data

As described later in this section, the effect of applying a style varies based on where and
how you apply it.

Formatting Numbers
XML Publisher provides special features for formatting decimal numbers. See
Formatting Decimal Numbers on page 1141.

Styles
Styles include font, background and foreground (that is, text) color, size, and alignment.
For a complete list of available styles, see Text Properties on page 1159.

Ways to Apply Styles

There are several ways to apply styles to items in XML Publisher reports. You can use

The tool bar, which is located above the XML Publisher canvas

Figure 553. XML Publisher Formatting Tool Bar

1136

Stylus Studio User Guide

Working with Report Components

The Report and short-cut menus

Figure 554. Format Choices on Short-Cut Menu

The Properties window

Figure 555. Format Properties

Each of these methods behaves in a similar fashion in that they apply a style to the
currently selected item. The Properties window, however, is slightly different in
addition to applying a stlye, it sets the default for the component that currently has focus.
See Setting Default Properties on page 1140 for more information.

Formatting Influenced by Component Hierarchy

Since all components in a report occur within the context of the body component, any
formatting you perform to the body component affects every component it contains
every table, list, text component, and so on unless that component has a default value
for the same format property specified on the Properties window. Put another way, any

Stylus Studio User Guide

1137

Publishing XML Data

formatting applied to a parent component affects all of its children unless that child has a
default value specified for it.
Consider the following example report, which shows an introductory sentence (body text)
and a list of book titles (list component).

Figure 556. Default Format Settings

All of the reports components are displayed using the XML Publisher default settings for
the body component, as seen in the toolbar (font is Arial, size is 10, non-bold, non-italic,
no underline, and so on).

1138

Stylus Studio User Guide

Working with Report Components

If we now click the Bold button on the toolbar, all of the reports text, including the list
component items, is rendered in bold the list component is a child of the body
component, so all formatting done to the body cascades to the list as well.

Figure 557. Using the Bold Tool to Format the Entire Report

Notice that the values in the Properties window have not changed although we have
changed some of the formatting characteristics for the body component, we have not set
any of its default values.
Next, we select just the title value glyph and click the Italic button.

Figure 558. Using the Italic Tool to Format Only Data Values

Notice that the label in the value glyph has been italicized. And when we preview the
report, we see that the text representing each data value (each books title element)
Stylus Studio User Guide

1139

Publishing XML Data

Retains the formatting established for the body (bold)

Includes the formatting specified just for it (italic)

The value glyph has a format state separate from the body, and this state is reflected in
both the glyph (the label is italicized) and the tool bar (when the glyph is selected, the
italic tool in the tool bar s highlighted).

Setting Default Properties

Default properties allow you to specify formatting for a child component that differs from
that of its parent components. These settings remain in effect regardless of how the
formatting for its parents changes. Return to the example illustrated in Figure 558 all of
the reports text is bold (we formatted the body component using the bold tool), and the
list text is also italic (we formatted the title value glyph).
If we do not want the list text to appear in bold, we need to establish a default for it
otherwise, it will continue to inherit the bold setting from its parent, the body component.
So, as shown in Figure 559, we click the glyph to give it focus, and then change the
Default Bold setting to Normal.

Figure 559. Default Settings Take Precedence

Clearing Formats
You can clear formats you have applied using the Clear Styles button ( ) on the tool bar
or the Report (Report > Text > Clear Styles) or short-cut menus. Format properties are
removed (or cleared) in the same way that they were applied that is, on a componentby-component basis. For example, if the body component text was italic, when you

1140

Stylus Studio User Guide

Working with Report Components

cleared the formatting the body component text would be returned to its original state.
Clear removes all formatting, regardless of whether or not the XML Publisher report was
last saved.
Note Clearing formats does not affect a components default property settings.

To clear formatting:
1.

Select the report component whose formatting you want to remove.

Click the Clear Styles button ( ).

Alternatives: Select Report > Text > Clear Styles from the menu, or select Clear
Styles from the short-cut menu (right-click).
The formatting is removed from the component you selected. Default settings are not
affected.

Formatting Decimal Numbers

XML Publisher allows you to define formatting characteristics for the decimal numbers
displayed in a report. For example, you might want to specify that all dollar values
displayed in a report end with two decimals, thus $10 would be formatted as $10.00,
$21.72 as $21.72, $99 as $99.00, and so on.
Formatting decimal numbers is a two-step process:
1.

Specify the formatting you want to use which character you want to use as the
decimal separator, for example.

Specify the pattern, called a picture string, you want the decimal numbers in your
report to match in order for this format to be applied.

Formatting for decimal numbers is specified for the report body and affects all decimal
numbers in a report for which you have specified a picture string. Formatting applies only
to dynamically generated values the total value of an order, for example and not to any
numbers that you type by hand as body text or in a text component.

Stylus Studio User Guide

1141

Publishing XML Data

Where You Specify Decimal Number Formats

You specify the formats for decimal numbers on the Decimal Format tab of the XML
Publisher Properties window, shown here:

Figure 560. Decimal Format Tab in the XML Publisher Properties Window

For example, if you want decimal values to be separated by a comma (,) instead of a period
(.), you would enter a comma in the Value field for the Decimal Separator property.
Default values are used for any properties that you do not specify. See Table 176,
Decimal Format Properties on page 1155 for more information.
In addition to defining the format of the decimal numbers in your reports, the properties
on the Decimal Format tab also affect the values you can use to define your picture string.
For example, the Digit property defines the character that you use to define digits in the
picture string. Its default value is the number character (#). Similarly, the Decimal
Separator property defines the character used to separate decimal values; its default value
is the period character (.). If you want to use values other than these in your picture strings,
you must be sure to specify them on the Decimal Format tab.

Where You Specify Picture Strings

As mentioned earlier in this section, a picture string represents a pattern for number
strings. An example of a picture string might be #,###.00. Number strings that match the
picture string you define are formatted using values you specify on the Decimal Format
tab.
You specify the picture string in the Format property on the Dynamic Value tab for the
report component the Price node, in the following illustration whose number strings
you want to format. You must specify a picture string for any number strings you want
formatted using the values you define on the Decimal Format tab. If you do not specify a

1142

Stylus Studio User Guide

Working with Report Components

picture string, no formatting is applied to the number string and it is rendered in the
finished report as-is.

Figure 561. Dynamic Value Tab

Values entered for the Format property must conform with the rules described in the
XSLT specification: http://www.w3.org/TR/xslt20/#dt-picture-string.

Example
We are producing reports for consumption by a European audience. This audience is
accustomed to seeing monetary values represented using the period (.) as the grouping
separator (for thousands, for example), and the comma (,) used as the decimal separator.
Thus, for example, a monetary typically displayed in North America as 4,230.95 needs to
be rendered as 4.230,95 for this report.
To satisfy this report requirement:
1.

In XML Publisher, display the Properties window.

Click the Decimal Format tab.

In the Decimal Separator property Value field, enter a comma (,).

In the Grouping Separator property Value field, enter a period (.).

Stylus Studio User Guide

1143

Publishing XML Data

When we have finished, the Properties window looks like this:

Figure 562. New Values Assigned for Decimal Formats

Next, we need to define the picture string for the decimal number we want to format
using these characters.
5.

In the XML Publisher canvas, select the glyph that represents the decimal number. In
this example, it is the node for book price.

In the Properties window, click the Dynamic Values tab.

In the Value field for the Format property, specify the following picture string:
#.###,00. The pound sign (#) is the default character used to represent digits in a
picture string; the zeroes after the decimal separator instruct the XML Publisher to
use 00 unless another value is present in the number string, so 82 is represented as
82,00. If we had specified the picture string as #.###,##, no decimal value would
be represented in the report because none was present in the number string, so 82
would be represented as 82,.

Generating Code for an XML Publisher Report

Once you have built and previewed your report in XML Publisher, you can generate XSLT
or XQuery code for it. The generated code includes all the instructions necessary to create
the report you composed in XML Publisher in the format (HTML or PDF) you selected
when creating the report.
Tip When you preview the XSLT or XQuery code generated by XML Publisher, the result
displayed in the Preview window should look the same as the preview of the XML

Publisher report.

1144

Stylus Studio User Guide

Generating Code for an XML Publisher Report

Supported Transformation Languages

The code generator for XML Publisher supports these transformation languages:

XSLT 1.0

XSLT 2.0

XQuery 1.0
You select the language, as well as a target for the output file, on the Generate
Transformation dialog box:

Figure 563. Generate Transformation Dialog Box

Sources
As described in Working with Data Sources on page 1097, if you plan on generating
XSLT for your XML Publisher report you must have specified at least one default source.
(Sources are not required for generating XQuery, though it is considered good practice to
specify one.)

Additional Sources
You can specify multiple sources for an XML Publisher report. The first source is
specified in the XSLT/XQuery Scenario Properties dialog box as shown in the following
table.
Table 174. How Additional Source Documents Are Referenced
Language Type

Scenario Property

Referenced in Generated Code As

XSLT

Source XML URL

A global parameter:
xsl:param name=input1

XQuery

Main Input

An external variable:
declare variable $input1 as
document-node() external

Stylus Studio User Guide

1145

Publishing XML Data

The expression associated with these variable names is displayed on the Parameter
Values page of the Scenario Properties dialog box, like the one shown for XQuery
scenarios in Figure 564.

Figure 564. Additional Sources Displayed on XQuery (XSLT) Scenario Properties

As you can also see, Figure 564 shows how data sources specified in XML Publisher are
represented in the XQuery (and XSLT) editor. This XQuery uses three XML sources:

videos.xml (it is the default source)

A relational source from the pubs data base

A local copy of books.xml, displayed on the XQuery data sources panel using the
variable name, $input1, with which it is associated

More About Relational Sources

Relational sources, like the one shown in Figure 564, are referenced in different ways by
XSLT and XQuery:

XSLT code references relational data sources within a document() function:

document('xquery:///jdbc:xquery:sqlserver://ntstylusdev:1433;table=companies;user=sa;xmlforest=true;schema=dbo;DatabaseName=
pubs;urltype=.xml')"

1146

XQuery code references relational data sources using the collection() function:

Stylus Studio User Guide

Generating Code for an XML Publisher Report

collection('pubs.dbo.companies')/companies/ticker

See Working with Relational Data Sources on page 850 for more information.

How to Generate Code

To generate code for an XML Publisher report:
1.

Preview the XML Publisher report. If it is satisfactory, continue with this procedure.

Click the Generate button.

Alternative: Select Report > Generate from the menu.
Stylus Studio displays the Generate Transformation dialog box.

Figure 565. Generate Transformation Dialog Box

Use the Transformation Language field to specify whether you want to use XSLT 1.0,
XSLT 2.0, or XQuery 1.0.

The default URI for the generated XSLT or XQuery code is displayed in the Save Into
field. Unless you specify otherwise, Stylus Studio uses the .report file name for the
.xsl or .xquery file name.

Click OK.

Stylus Studio User Guide

1147

Publishing XML Data

Example: Building an XML Publisher Report

In this example, we will build a simple XML report based on videos.xml. This XML
document is in the VideoCenter folder of the examples project.
This section covers the following topics:

Getting Started on page 1148

Insert and Populate a Table on page 1148

Simple Table Formatting on page 1150

Format Data Conditionally on page 1151

Generate the Code on page 1153

Getting Started
In this part of the procedure, we create a new XML Publisher report and specify a data
source.
To get started:
1.

Select File > New > XML Report from the Stylus Studio menu.
Stylus Studio displays the XML Report Format dialog box.

Choose XHTML+CSS if it is not already selected, and click OK.

Stylus Studio displays the XML Publisher Editor.

If the Project window is not already open, open it (View > Project Window).

Drag videos.xml from the VideoCenter folder to the data sources panel in the XML
Publisher Editor.

Insert and Populate a Table

Next, we add a table based on the video repeating element and populate its columns.

1148

Expand the videos node.

Drag the video repeating element from the data sources panel and drop it on the XML
Publisher canvas.

Select Insert Table > Empty from the short-cut menu.

Stylus Studio User Guide

Example: Building an XML Publisher Report

Stylus Studio creates a three-column table. At this point, the XML Publisher Editor
should resemble Figure 566:

Figure 566. Default Table in New XML Publisher Report

Although the table currently contains no values, if you mouse over the repeating
glyph at the left of the table ( ) you will see that it references the videos.xml
document and that the current XPath expression evaluates the video repeating element
(/result/videos/video).
8.

Right-click any cell in the table and select Remove Column from the short-cut menu.

Expand the video node in the data sources panel.

10.

Drag the title node and drop it in the first column; select Insert Value from the shortcut menu.
A value glyph with the element name appears in the cell.

11.

Repeat this step with the rating element, dropping it in the second column.

12.

Right-click the table again, and select Add Row Before.

Stylus Studio adds a new row to the table. Note that the new row does not repeat the
repeating glyph is associated only with the second row, the row that contains the data.

13.

Type Title in the first column and Rating in the second.

Stylus Studio User Guide

1149

Publishing XML Data

14.

Click Preview ( ).
Stylus Studio creates a three-column table. At this point, your XML Publisher Editor
should resemble this:

Figure 567. Preview of XML Publisher Report

15.

Click the Hide docked window button (the small X) to close the Preview window.
This gives us more room to work, and Stylus Studio will automatically display the
Preview window the next time we preview the report.

Simple Table Formatting

In this section, we will perform some simple formatting to make the table more
presentable. We will start by making the column headings, Title and Rating, bold.

1150

16.

First, click the Show Text Symbols button ( ) in the toolbar.

This removes text symbols (like spaces and paragraph markers) from the canvas,
which can make the canvas easier to work with while you build the report.

17.

Click anywhere in the cell containing the Title string.

18.

Click the Bold tool on the toolbar ( ).

The Title string appears bold in the canvas.

19.

Make the Rating string bold.

Stylus Studio User Guide

Example: Building an XML Publisher Report

Next, we want to adjust the width of the first column, so the ratings appear closer to the
title.
20.

Click either of the rows in the tables first column.

21.

Click the Column tab in the Properties window. (If the Properties window is not
displayed, select View > Properties from the Stylus Studio menu.)

22.

Enter 40% for the Width property.

23.

Click Preview ( ).
The Preview window displays the changes.

Figure 568. Changes to the Reports Table

Format Data Conditionally

The last action we will perform on the table is to write an XPath expression to display the
R rating for movies in a bold red.
24.

Click the rating glyph.

25.

In the Properties window, expand the Default Color property.

26.

Click the XPath field, and then click the more button (
Stylus Studio displays the XPath Editor dialog box.

Stylus Studio User Guide

1151

Publishing XML Data

27.

Type the following XPath expression:

if (rating = 'R') then 'red' else ""

Notice Stylus Studios Sense:X auto-completion and text coloring as you type.

Figure 569. XPath Editor Dialog Box

28.

Click OK.

29.

Next, use the same process to enter this XPath expression for the Bold property:
if (rating = 'R') then 'bold' else ""

30.

Click Preview ( ).
Our report now looks like this:

Figure 570. Finished Example Report

1152

Stylus Studio User Guide

Example: Building an XML Publisher Report

Generate the Code

Once the report is finished, we can generate XSLT or XQuery code to produce a report.
31.

Click the Generate button on the toolbar.

Stylus Studio displays the Generate Transformation dialog box.

Figure 571. Generate Transformation Dialog Box

We want to use XSLT to generate our report, so we do not need to change the values
for Document Type or Transformation Language.
32.

The default name for the .xsl file is based on the .report file name. We change
Untitled1.xsl to myMovieRatings.xsl and click OK.
Stylus Studio opens the generated XSLT in the XSLT Editor, as shown in Figure 572.

Figure 572. XSLT Generated from the XML Publisher Report

Stylus Studio User Guide

1153

Publishing XML Data

33.

If we preview the XSLT, we see the same results as when we previewed the report in
XML Publisher.

Figure 573. Preview of the XSLT Generated by XML Publisher

Properties Reference
This section contains reference information for the report component properties displayed
in the Properties window. Where appropriate, properties are grouped by component the
section Table Properties on page 1157 has subsections for row and column properties,
for example. The text property is associated with many components, as well as being a
component in its own right. It has its own subsection (Text Properties on page 1159).
This section is organized as follows:

Context and XPath Sub-Properties on page 1155

Body Properties on page 1155

Table Properties on page 1157

List Properties on page 1159

Text Properties on page 1159

Repeater Properties on page 1160

If Properties on page 1161

Image Properties on page 1161

Dynamic Value Properties on page 1161

1154

Stylus Studio User Guide

Properties Reference

Context and XPath Sub-Properties

All of the properties in this section have Context and XPath sub-properties. They are
described in Component Properties on page 1132. In addition, some properties (ifs and
repeaters, for example) have sub-properties that are unique to them. Unique subproperties are described with the property to which they pertain.

Body Properties
Body properties affect all other components in an XML Publisher report unless they have
their own format settings specified for them. Body properties are displayed on these tabs
Document, Decimal Format, and Text.
Table 175. Document Properties
Property

Description

Base URL

Base URL used for HTML links and image resolution.

Background

Sets the background color for the report.

Table 176. Decimal Format Properties

Property

Description

Zero Digit

The character used as the digit zero. The default is the digit zero (0).

Digit

The character used for a digit in the picture string. The default is
number sign character (#).

Decimal Separator

The character used for the decimal sign. The default is the period
character (.).

Grouping Separator

The character used as a grouping (thousands, for example) separator.

The default is the comma character (,).

Pattern Separator

The character used to separate positive and negative sub-pictures in

a picture string. The default is the semi-colon character (;).

Minus Sign

The character used as the default minus sign. The default is the
hyphen-minus character (-, #x2D).

Stylus Studio User Guide

1155

Publishing XML Data

Table 176. Decimal Format Properties
Property

Description

Percent

The character used as a percent sign. The default is the percent

character (%).

Per mille

The character used as a per mille sign. The default is the Unicode
per-mille character (#x2030).

Infinity

The string used to represent infinity. The default value is the string
Infinity.

NaN

The string used to represent the NaN value. The default is the string
NaN (not a number).

Table 177. Text Properties

1156

Property

Description

Alignment

Aligns body content along left margin, right margin, or in the center.
Default is None.

Font

Sets the font for body contents. If no value is specified, Stylus Studio
uses the font specified in the toolbar.

Size

Sets the font size for body contents. If no value is specified, Stylus
Studio uses the font size specified in the toolbar.

Color

Sets the font color for body contents. If no value is specified, Stylus
Studio uses the value specified by the Foreground Color tool in the
toolbar.

Background

Sets the background color for body contents. If no value is specified,

Stylus Studio uses the value specified on the Document tab.

Bold

Sets the body content to bold. If no value is specified, Stylus Studio

uses the value specified by the Bold tool in the toolbar.

Italic

Sets the body content to italic. If no value is specified, Stylus Studio

uses the value specified by the Italic tool in the toolbar.

Stylus Studio User Guide

Properties Reference
Table 177. Text Properties
Property

Description

Underline

Sets the body content to underline. If no value is specified, Stylus

Studio uses the value specified by the Underline tool in the toolbar.

Base URL

Base URL used for HTML links and image resolution.

Table Properties
See also:

Row Properties on page 1158

Column Properties on page 1158

Cell Properties on page 1158

Text Properties on page 1159

Table 178. Table Properties
Property

Description

Component Name

The name of the repeating element on which the table is based. This
name appears in the navigation bar glyph that represents the table.
Editable.

Width

The table width. If expressed as a percent, the table is drawn relative

to the available page. If expressed as a number, the value is
interpreted in points (pt).

Border

The width of the line used to draw the table border, in points (pt).

CellSpacing

The amount of space between cells, in points (pt).

CellPadding

The amount of space between a cell border and its contents, in points
(pt).

Alignment

Aligns cell contents along left border, right border, or in the center.
Default is None.

Stylus Studio User Guide

1157

Publishing XML Data

Row Properties
Table 179. Row Properties
Property

Description

Loop

A group of properties (Context, XPath, and Sort) that together

describe how to iterate over a node set. See Component
Properties on page 1132.

Sort

A sub-property of Loop that allows you to specify, using an XPath

expression, for example, how to sort table rows. If no value is
specified, rows are displayed in document order.

Height

The row height in points (pt).

Background

The color of the row background. (Set the color of row values using
the Text tab.

Column Properties
Table 180. Column Properties
Property

Description

Width

The column width in points (pt).

Background

The color of the column background.

Cell Properties
Table 181. Cell Properties

1158

Property

Description

Background

The color of the cell background.

Stylus Studio User Guide

Properties Reference

List Properties
See also Item Properties on page 1159.
Table 182. List Properties
Property

Description

Component Name

The name of the repeating element on which the list is based. This
name appears in the navigation bar glyph that represents the list.
Editable.

List Type

The type of symbol or character you want to use for the list: disk (the
default), circle, decimal, lower-alpha, none, square, and upperalpha.

Item Properties
Item properties are the same as Text properties. See Text Properties on page 1159.

Text Properties
Text properties are applicable to text components (Insert > Text) as well as to text in other
components (tables, lists, repeaters, and ifs).
Table 183. Text Properties
Property

Description

Alignment

Aligns text along left margin, right margin, or in the center. Default
is None.

Font

Sets the font for the selected text. If no value is specified, Stylus
Studio uses the font specified in the toolbar.

Size

Sets the font size for the selected text. If no value is specified, Stylus
Studio uses the font size specified in the toolbar.

Color

Sets the font color for the selected text. If no value is specified,
Stylus Studio uses the value specified by the Foreground Color
tool in the toolbar.

Stylus Studio User Guide

1159

Publishing XML Data

Table 183. Text Properties
Property

Description

Background

Sets the background color for the selected text. If no value is

specified, Stylus Studio uses the value specified by the
Background Color tool in the toolbar.

Bold

Sets the selected text to bold. If no value is specified, Stylus Studio

uses the value specified by the Bold tool in the toolbar.

Italic

Sets the selected text to italic. If no value is specified, Stylus Studio

uses the value specified by the Italic tool in the toolbar.

Underline

Sets the selected text to underline. If no value is specified, Stylus

Studio uses the value specified by the Underline tool in the toolbar.

Repeater Properties
See also Text Properties on page 1159.
Table 184. Repeater Properties

1160

Property

Description

Loop

A group of properties (Context, XPath, and Sort) that together

describe how to iterate over a node set. See Component
Properties on page 1132.

Sort

A sub-property of Loop that allows you to specify, using an XPath

expression, for example, how to sort the items in the repeater. If no
value is specified, items are displayed in document order.

Direction

The way in which the data values that make up the repeaters items
will be added to the report vertical (in a list), or horizontal (in a
row). The default is Vertical.

Stylus Studio User Guide

Properties Reference

If Properties
See also Text Properties on page 1159.
Table 185. If Properties
Property

Description

Condition

An XPath expression used to define the condition. Actions based on

this condition are specified on the If glyphs true and false tabs.

Image Properties
Table 186. Image Properties
Property

Description

Width

The image width in points (pt).

Height

The image height in points (pt).

Source

The location of the image file to be displayed in the report. This can
be an absolute path, or a relative path specified in conjunction with
the Body components Base URL property.

Alignment

Aligns the image relative to the page left, right, or in the center.
Default is None.

Dynamic Value Properties

See also Table 176, Decimal Format Properties on page 1155.
Table 187. Dynamic Value Properties
Property

Description

Format

Allows you to specify a picture string for numbers (#,###.##, for

example). Number strings that match this picture string are
formatted using values you specify on the Decimal Format tab. All
numbers in a report are formatted using the values specified there.
Values entered for the Format property must conform with the rules
described in the XSLT specification:
http://www.w3.org/TR/xslt20/#dt-picture-string

Stylus Studio User Guide

1161

Publishing XML Data

1162

Stylus Studio User Guide

Chapter 16

Integrating with Third-Party File Systems

Integration with TigerLogic XDMS is available only in Stylus Studio XML

Enterprise Suite.
Stylus Studio is fully integrated with Raining Data TigerLogic XML Data
Management Server (TigerLogic XDMS).
This chapter describes how to work with this file system in Stylus Studio.

Using Stylus Studio with TigerLogic XDMS

Integration with the TigerLogic XDMS file system is available only in Stylus Studio
XML Enterprise Suite.
This section describes how to use Stylus Studio with the TigerLogic XDMS file system
and covers the following topics:

Overview on page 1164

Connecting to TigerLogic XDMS on page 1165

Using Documents Stored on TigerLogic XDMS on page 1167

Creating Collections on page 1168

Stylus Studio User Guide

1163

Integrating with Third-Party File Systems

Overview
Stylus Studio can read and write well-formed XML documents (.xml, .xsl, and so on)
from/to TigerLogic XDMS collections. In Stylus Studio, you reference external files
using a URL. The URL used to access TigerLogic XDMS files is
tig://server:port/database_ name/collection_name/file_name.xml:

tig is the prefix that specifies that files will be read from TigerLogic XDMS

server:port is the server name that hosts the TigerLogic XDMS file system; the port is
the port used to connect to the server

database_name is the name of the TigerLogic XDMS database you want to access

collection_name is the name of the TigerLogic XDMS collection associated with the
document you want to open

file_name.xml is the name of the XML document you wish to access within that
collection
For example, to access the auction.xml document in mycollection, you might enter the
following in the URL field of the Stylus Studio Open dialog box:
tig://ntstylus-dev:3408/mydb/mycollection/auction.xml

Note Stylus Studio treats collections very much like directories, and the XML documents
stored within a collection are treated like files within a directory.
You can save files back to the same collection from which they were read, or to some other
file system (your local machine, for example). You can create new collections.
Note You can use a TigerLogic XDMS URL to open an XML document anywhere you can

specify URLs in Stylus Studio. For example, you can use the TigerLogic XDMS URL to
specify the source document for XQuery Mapper and then process the XQuery using the
TigerLogic XDMS XQuery processor.

TigerLogic XDMS Version Support

Stylus Studio supports TigerLogic XDMS Version 2.6.

1164

Stylus Studio User Guide

Using Stylus Studio with TigerLogic XDMS

Connecting to TigerLogic XDMS

The TigerLogic XDMS file system is accessible from the

Open dialog box

File Explorer window

In addition, if you know the file system URL for a specific TigerLogic XDMS database,
you can enter it in a URL field (in the Open dialog box, for example) and connect to the
file system in that fashion.

What Happens When You Connect

When you connect to the server hosting TigerLogic XDMS, Stylus Studio caches the
information used to establish the connection host name and port, username, and
password for the duration of the Stylus Studio session. When you exit Stylus Studio, all
connections are dropped. Only the host name and port information is retained to help
simplify subsequent connections.
Note If a document in Stylus Studio (an XQuery or XSLT, for example) uses a document stored

in a TigerLogic XDMS collection, when you open that document in a subsequent session,
Stylus Studio automatically prompts you for the TigerLogic XDMS connection
information.

How to Connect to TigerLogic XDMS

To connect to TigerLogic XDMS:
1.

In the File Explorer window, expand the TigerLogic XDMS folder.

Figure 574. TigerLogic XDMS Icon in File Explorer

Stylus Studio User Guide

1165

Integrating with Third-Party File Systems

Alternative: On the Stylus Studio menu, Click File > Open, and then click the
TigerLogic XDMS icon.

Figure 575. TigerLogic XDMS Icon in Open Dialog Box

Stylus Studio displays the Choose Server dialog box.

Complete the Server Name, (server address and port; myServer:3008, for example)
User Name, and Password fields, and click OK.
Stylus Studio connects you to the host specified in the Server name field. Icons
representing the host and the TigerLogic XDMS databases residing on that host
appear in the File Explorer window.

Optionally, expand the database folders to view the TigerLogic XDMS collections
stored on that database.

Optionally, expand the collection folders to view the XML documents stored there.

Reconnecting
If you lose your connection with the server hosting the TigerLogic XDMS file system, and
a document from a TigerLogic XDMS collection is open, Stylus Studio displays the
Authentication Required dialog box the next time you try to access that document.

Figure 576. Authentication Required Dialog Box

This dialog box can appear, for example, when you

Re-start Stylus Studio

Refresh an XSLT or XQuery that uses an XML document from a TigerLogic XDMS
collection
The Authentication Required dialog box prompts you for the username and password you
used when you first established a connection with the server.

1166

Stylus Studio User Guide

Using Stylus Studio with TigerLogic XDMS

Using Documents Stored on TigerLogic XDMS

XML documents stored on the TigerLogic XDMS file system are available to you in
Stylus Studio once you establish a connection to the server hosting TigerLogic XDMS, as
described in Connecting to TigerLogic XDMS on page 1165.

Opening Documents
You can open a document stored in the TigerLogic XDMS file system by dragging it from
the File Explorer window into an open document editor, the document editor tab area, or
some other target. See Dragging and Dropping Files in the Stylus Studio on page 97 and
Using the File Explorer on page 94 for more information. You can also select a
document using the Open dialog box (File > Open).

Saving Documents
When you save a document to the TigerLogic XDMS file system, TigerLogic XDMS first
validates the document to ensure that it is well-formed XML. If the document is wellformed, the document is saved; otherwise, you receive an error from the TigerLogic
XDMS server.
Tip Use the Stylus Studio well-formedness checker

to check your XML documents

before saving them to TigerLogic XDMS.

Auto-Save and Backup Files
Stylus Studio has an option (select Tools > Options from the Stylus Studio menu) that
automatically saves modified documents at an interval you determine (every 10 minutes
is the default). This option is off by default.
The creation of backup files is managed by the TigerLogic XDMS file system. Stylus
Studio does not create .bak files of files saved to the TigerLogic XDMS file system.

Using Documents in XQuery and XSLT

You can use XML documents stored in the TigerLogic XDMS file system as source and
target documents in Stylus Studio XQuery and XSLT. They are treated as any other
document with one exception: when you open a document in Stylus Studio that uses a
document stored in the TigerLogic XDMS file system, Stylus Studio prompts you to
supply authentication information (username, password) before restablishing connection
with the server hosting the TigerLogic XDMS file system.

Stylus Studio User Guide

1167

Integrating with Third-Party File Systems

Creating Collections
You can create new TigerLogic XDMS collections in Stylus Studio.
To create a TigerLogic XDMS collection:
1.

Connect to a TigerLogic XDMS server, as described in Connecting to TigerLogic

XDMS on page 1165.

Open the File Explorer window if it is not already open (View > File Explorer).

Right-click the TigerLogic XDMS server instance in which you wish to create the
collection.

Select New Folder from the short-cut menu.

A new folder icon appears under the icon for the TigerLogic XDMS server instance
with the default name, New Folder.

Edit the default collection name and press Enter.

Alternative:
You can also create a new TigerLogic XDMS collection from the Open dialog box.

1168

Connect to a TigerLogic XDMS server, as described in Connecting to TigerLogic

XDMS on page 1165.

Click the New Folder button on the Open dialog box.

Stylus Studio User Guide

Chapter 17

Extending Stylus Studio

Stylus Studio provides several ways to extend its native functionality. This chapter
describes features that allow you to specify other XML validation engines, and features
that allow you to define and register custom document wizards.
This chapter covers the following topics:

Custom XML Validation Engines on page 1170

Custom Document Wizards on page 1176

Stylus Studio User Guide

1169

Extending Stylus Studio

Custom XML Validation Engines

Stylus Studio supports several XML validation engines, including the MSXML4.0 SAX
Parser, Xerses-J 2.3.0, and .NET XML. The custom validation engine feature lets you
register your own XML validation engine with Stylus Studio. Custom validation engines
are added to the Validate Document drop-down list in the XML Editor once you register
them with Stylus Studio, as shown in Figure 577.

Figure 577. Validate Document Drop-Down List

Output for custom validation engines is displayed in Stylus Studios Output Window.
Output for other custom applications, such as that created by the custom document
wizard, is also displayed in Stylus Studios Output Window.

Figure 578. Output Window

Registering a Custom Validation Engine

The process of registering a custom validation involves the following steps:
1.

1170

Make the necessary custom validation engine available to Stylus Studio.

Stylus Studio User Guide

Custom XML Validation Engines

Configure the custom validation engine on the Custom Validation Engines page of
the Options dialog box. This step involves
a.

Providing a name.

Specifying a command line template.

Defining any arguments required by the command line.

Optionally specifying the initial directory, path, and classpath to be used by the
custom validation engine.

Optionally setting a feature that prompts the custom validation engine user for
arguments when the custom validation engine is run.
More information for each of these steps is provided in the following section,
Configuring a Custom Document Wizard on page 1177.
e.

Configuring a Custom Validation Engine

This section provides information and procedures for configuring a custom validation
engine. It covers the following topics:

The Custom Validation Engines Page on page 1172

How to Configure a Custom Validation Engine on page 1175

Stylus Studio User Guide

1171

Extending Stylus Studio

The Custom Validation Engines Page

You use the Custom Validation Engines page of the Options dialog box to work with
custom validation engines in Stylus Studio.

Figure 579. Custom Validation Engines Page

How to display
To display the Custom Validation Engines page:
1.

In the Stylus Studio menu bar, select Tools > Options.

The Options dialog box appears.

If necessary, expand Application Settings and click Custom Validation Engines.

The Custom Validation Engines page appears.

About macros
Stylus Studio provides macros for some fields to help speed creation of custom validation
engines. Any macro you use to configure the custom validation engine is resolved when
it is run.
Available macros vary based on the field for which they are being used. To display macros
available for a given field, click
. Predefined macros include

${FilePath} The complete path of the XML file to be validated.

1172

Stylus Studio User Guide

Custom XML Validation Engines

${FileDir}

The directory in which the XML file to be validated is stored.

${FileName} The name of the XML file to be validated.
${FileExt} The extension of the XML file to be validated.
${ClassPath} The Classpath environment variable.
${StylusDir} The path of the Stylus Studio installation directory.
${SchemaURLFile} Expands into "-schemaURLFile tempfile.txt" where tempfile.txt
is a text document containing the name of an XML Schema on each separate line.
(The names of the XML Schema are specified using "Associate Schema to Folder" in
the Project window.) Each XML Schema should be pre-loaded before attempting
validation, so that even XML documents that carry no reference to an XML Schema
can be validated.

Name
When you click the New button (
)to create a new custom validation engine, Stylus
Studio displays an entry field for the name.

Figure 580. Specifying a Custom Validation Engine Name

You should replace the default name (Validation Engine 1, for example) with the name
you want to associate with the custom validation engine. The name you enter is displayed
in the drop-down in the XML Editor.
Custom validation engines are displayed in the Validate Document drop-down list in the
order in which they appear here.
You can change the custom validation engine order by
1.

Selecting the custom validation engine whose order in the list you want to change.

Clicking the up or down arrow to the right of the custom validation engine list box as
needed.

Stylus Studio User Guide

1173

Extending Stylus Studio

Command
You use the Command field to specify the command line used to invoke the custom
validation engine. This is typically the path to the .exe, .cmd, or .bat file that starts the
application.
Arguments
You use the Arguments field to specify any arguments required by the custom validation
engine. Click
to browse predefined macros.
Initial Directory
You use the Initial directory field to specify the directory you want Stylus Studio to use as
the current directory when the custom validation engine is run. Click
to browse
predefined macros.
Path
You use the Path field to define paths to any files (such as .exe and .dll) required by the
custom validation engine. You do not have to define any paths that are already defined in
your PATH environment variable. Separate multiple paths with a semicolon. Click
to
browse predefined macros.
Classpath
You use the Classpath field to define paths to any JVM files required by the custom
validation engine (such as .jar and .class). You do not have to define any paths that are
to browse predefined
already defined in your PATH environment variable. Click
macros.
Prompt for arguments
The Prompt for arguments feature displays a dialog box when the custom validation
engine is run.

Figure 581. Argument Prompt

1174

Stylus Studio User Guide

Custom XML Validation Engines

The Arguments field allows the user to change the command line and arguments
configured with the custom validation engine when it was registered with Stylus Studio.

How to Configure a Custom Validation Engine

Before performing this procedure, you should be familiar with the information in The
Custom Validation Engines Page on page 1172.
To configure a custom validation engine:
1.

Display the Custom Validation Engines page of the Options dialog box. See How to
display on page 1172 if you need help with this step.

Click the New button and enter a name for the custom validation engine. Remember
that this value is displayed in the Validate Document drop-down list in the XML
Editor.

Specify the command line any required arguments. See Command on page 1174
and Arguments on page 1174 if you need help with this step.

Optionally, specify an initial directory, path and classpath.

Click Prompt for arguments if you want Stylus Studio to display a dialog box that
allows the user to change the command line or arguments when the custom validation
engine is run.

Click OK.

Stylus Studio User Guide

1175

Extending Stylus Studio

Custom Document Wizards

Stylus Studios custom document wizard feature allows you to create and configure
document wizards that invoke third-party file conversion and document generation tools,
such as Thai Open Sources Trang. When run, a custom document wizard passes
argument values provided by the user (the name of the file to be converted, for example)
to the command line that invokes the third-party tool. The third-party tool generates an
output file as specified in the custom document wizards command line, and the file is then
opened by Stylus Studio in the appropriate editor.
An example of a custom document wizard is the DTD to XML Schema (Trang) document
wizard shipped with Stylus Studio.

Arguments defined in
Stylus Studio

Values entered by
custom document
wizard users

Figure 582. A Custom Document Wizard

This document wizard was created using the custom document wizard feature.

1176

Stylus Studio User Guide

Custom Document Wizards

Registering a Custom Document Wizard

The process of registering a custom document wizard in Stylus Studio involves the
following steps:
1.

Make the necessary third-party software available to Stylus Studio. For example, any
.jar or .exe files associated with the document conversion or generation tool must be
accessible from the Stylus Studio installation.

Configure the custom document wizard on the Custom Document Wizards page of
the Options dialog box. This step involves
a.

Providing a name and, optionally, an icon, for the custom document wizard.

Setting the document type.

Specifying a command line template.

Defining any arguments required by the command line.

Optionally setting a trace feature that displays processing provided by the thirdparty tool.
More information for each of these steps is provided in the following section,
Configuring a Custom Document Wizard on page 1177.
e.

Configuring a Custom Document Wizard

This section provides information and procedures for configuring a custom document
wizard. It covers the following topics:

The Custom Document Wizards Page

Defining Arguments

How to Configure a Custom Document Wizard

Stylus Studio User Guide

1177

Extending Stylus Studio

The Custom Document Wizards Page

You use the Custom Document Wizards page of the Options dialog box to work with
custom document wizards in Stylus Studio.

Figure 583. Custom Document Wizards Page

This section describes how to display the Custom Document Wizards page and
information about its fields.
How to display
To display the Custom Document Wizards page:
1.

In the Stylus Studio menu bar, select Tools > Options.

The Options dialog box appears.

If necessary, expand Application Settings and click Custom Document Wizards.

The Custom Document Wizards page appears.

About macros
Stylus Studio provides macros for some fields to help speed creation of custom document
wizards. Available macros vary based on the field for which they are being used. To
display macros available for a given field, click
.

1178

Stylus Studio User Guide

Custom Document Wizards

Predefined macros include

${StylusDir}, which indicates that the path you are specifying is relative to the Stylus
Studio installation directory.

${PATH}, which specifies the PATH environment variable.

${OutputFile}, which is used to specify the output generated by the document wizard.
This macro is available in the Command field only.
In addition, Stylus Studio creates argument variable macros for any arguments you define
and displays them with other Command field macros.
Name
)to create a new custom document wizard, Stylus
When you click the New button (
Studio displays an entry field for the name.

Figure 584. Specifying a Custom Document Wizard Name

You should replace the default name (DocumentWizard1, for example) with the name you
want to associate with the custom document wizard. The name you enter is

Displayed in the Document Wizards dialog box along with the icon you specify for
the custom document wizard.

Used in the title bar of the dialog box the user sees when running the custom
document wizard.

Stylus Studio User Guide

1179

Extending Stylus Studio

Document type
The Document type field displays a drop-down list of available document types when you
click it:

Figure 585. Document Type Field

The document type is the type of output generated by the custom document wizard (XML
Schema, XQuery, and so on). The value you select determines

The tab in the Document Wizards dialog box on which the custom document wizard
is displayed (XML Editor, XSLT Editor, or Java, for example)

The editor Stylus Studio uses to display the output generated by the document wizard
Icon bitmap
You use the Icon bitmap field to specify the path for the icon you want to represent the
custom document wizard. This icon, along with the name you give the custom document
wizard, is displayed in the Document Wizards dialog box. Click
to browse for the
file you want to specify or to insert the ${StylusDir} macro.
If you leave the Icon bitmap field blank, Stylus Studio uses the following default icon for
the custom document wizard:
Command line
You use the Command line field to specify a command line template. Stylus Studio uses
this template to compose the command line that invokes the custom document wizard.
Variables, such as ${InputFile}, are used in place of actual arguments. Users specify
argument values when they run the custom document wizard.
Consider the following example:
java -cp my.jar com.exln.stylus.Import ${QuoteChar} ${InputFile} ${OutputFile}

1180

Stylus Studio User Guide

Custom Document Wizards

This command line template allows Stylus Studio to start the specified Java class with a
command line that includes the QuoteChar, InputFile, and OutputFile arguments.
Argument variables can appear anywhere in the command. They must be in the form
${name}. For example:
${InputFile}
${OutputFile}
${LoggingOption}
${SomeArgument}

You must specify the ${OutputFile} argument variable in every command line template.
Stylus Studio always generates the name of the file it opens as the value for the
${OutputFile} argument variable.
to display a menu that provides shortcuts
As with the Icon bitmap field, you can click
that help you specify the command line template. This menu lets you

Display the Custom Document Wizard Arguments dialog box, in which you can
specify the command line arguments and their properties. See Defining Arguments
on page 1182 for more information.

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro.

Insert argument variable macros for arguments you have already defined.
Initial directory
You use the Initial directory field to specify the directory you want Stylus Studio to use as
the current directory when the custom document wizard is run. Click
to browse for
the file you want to specify or to insert the ${StylusDir} macro.
Path
You use the Path field to define paths to any files required by the custom document
wizard. You do not have to define any paths that are already defined in your PATH
environment variable. Separate multiple paths with a semicolon.
Click
to display a menu that provides shortcuts that help you specify the PATH field.
From this menu you can

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro.

Insert the ${PATH} macro.

Stylus Studio User Guide

1181

Extending Stylus Studio

Trace execution
If the custom document wizard you are configuring outputs processing information (error
messages, stack traces, and so on), you can use the Trace execution feature to display this
information in the Output Window of the Stylus Studio editor used to display the custom
document wizards generated document.

Defining Arguments
You must define any arguments required by the custom document wizard using the
Custom Document Wizard Arguments dialog box.

Figure 586. Custom Document Wizard Arguments Dialog Box

Stylus Studio uses the arguments you define here to

Compose the dialog box used to run the custom document wizard. That dialog box
enables users to provide values for the arguments you define.

Create argument variable macros, which you can then use to compose the command
line template. Stylus Studio displays the argument variable macro it creates in the
Command field menu.
Note Every variable used in the command line template must be defined in the Custom
Document Wizard Arguments dialog box.

How to display
There are two ways to display the Custom Document Wizard Arguments dialog box:

Click the Arguments button on the Custom Document Wizard page. Use this
procedure if you want to define arguments before composing the command line
template.

1182

Stylus Studio User Guide

Custom Document Wizards

Select Edit Arguments from the Command field menu that is displayed when you
click
. You can use this procedure if you want to define arguments while
composing the command line.

OutputFIle argument
Stylus Studio creates an OutputFile argument for each custom document wizard. You
cannot delete this argument. You can change its order, if necessary, as described in the
following section.
Argument order
By default, the arguments you define in the Custom Document Wizard Arguments dialog
box are displayed to users in the order in which they are created. Arguments are displayed
in a simple two-column grid, with the argument description in the first column, and an
entry field for the argument value in the other. (See Figure 582 for an illustration of a
custom document wizard dialog box.)
Also by default, the OutputFile argument appears first.
You can change the argument order by
1.

Selecting the argument whose order you want to change.

Clicking the up or down arrow to the right of the argument list box as needed.

Note Whether or not the argument order defined here has to match the argument order in the

command line template will vary from one custom document wizard to the next
arguments for some applications can be order independent, for example. Generally
speaking, it is good practice for the argument order in the Custom Document Wizard
Arguments dialog box to match that in the command line template.
Argument attributes
You can specify the following attributes for each argument you define:

Name. Stylus Studio uses the value you enter in the Name field to compose the
argument variable macro. This name is not displayed to custom document wizard
users. Required.

Description. The value you enter in the Description field appears in the custom
document wizard dialog box that is displayed to users when they run the wizard. The
description should provide users with adequate information about the arguments

Stylus Studio User Guide

1183

Extending Stylus Studio

expected value. It can be useful to distinguish input and output arguments, for
example. Required.
Flag. The flag associated with the argument (-v, or simply - or /, for example). When
Stylus Studio composes the command line for the custom document wizard, it uses
the flag value as a prefix to the argument value supplied by the user.
The Flag field must be specified for Boolean arguments.

Note

Type. The arguments data type. Table 188 summarizes valid values for the Type field
and describes possible values for those types
Table 188. Type Field Values
Type

Description

boolean

The value for a Boolean argument must be true or false. If the

value is true, Stylus Studio inserts the value of the associated Flag
attribute in the command line. No value other than the Flag value
appears in the command line for Boolean arguments. If the value is
false, the associated Flag value does not appear in the command
line.
If you set Type to boolean, you must specify the arguments Flag
attribute.

1184

InputFile

The value for an InputFile argument is a URL that the custom

document wizard user enters or selects by clicking the Browse
button. If the format of the URL is for a protocol other than the file
protocol, Stylus Studio copies the file into a temporary local file and
uses the name of the temporary local file in the command line. You
can specify multiple arguments whose data type is InputFile.

OutputFile

The custom document wizard user does not specify a value for the
OutputFile argument. Exactly one argument must be of the
OutputFile type. Stylus Studio generates a value for the
OutputFile argument and inserts it in the command line.

string

The value for a string argument can be anything specified by the

custom document wizard user. Stylus Studio encloses the string
values in quotation marks when composing the command line.

Default Value. The value used by Stylus Studio for optional arguments, unless another
value is specified by the user when the custom document wizard is run. Default values
Stylus Studio User Guide

Custom Document Wizards

for required arguments are ignored Stylus Studio requires users to enter values for
required arguments.
Optional. Whether or not the argument is optional. Valid values for this field are true
or false.

How to define an argument

To define an argument:
1.

Display the Custom Document Wizard Arguments dialog box. See How to display
on page 1182 if you need help with this step.

Click the New button (

).
A new argument is displayed in the Custom Document Wizard Arguments dialog
box, with a default name and other default values.

Figure 587. Custom Document Wizard Arguments Dialog Box

Complete the argument attributes as described in earlier in this section. Remember

that Description values appear in the custom document wizard dialog box when the
user runs the wizard.

To define another argument, click the New button again.

If necessary, use the Up and Down arrows to change the argument order. Remember
that the order in which arguments are displayed here is the order in which they appear
in the custom document wizard dialog box when the user runs the wizard.

Click OK.

Stylus Studio User Guide

1185

Extending Stylus Studio

How to Configure a Custom Document Wizard

Before performing this procedure, you should be familiar with the information in The
Custom Document Wizards Page on page 1178 and Defining Arguments.
To configure a custom document wizard:

1186

Display the Custom Document Wizards page of the Options dialog box. See How
to display on page 1178 if you need help with this step.

Click the New button and enter a name for the custom document wizard. Remember
that this value is used as the title for the dialog box displayed to the user when they
run the wizard, as well as for the label associated with the custom document wizard
icon displayed in the Document Wizards dialog box.

Click the Arguments button and define the wizards arguments on the Custom
Document Wizard Arguments dialog box. See Defining Arguments on page 1182
if you need help with this step.

Select the custom document wizards document type.

Specify the command line template. See Command line on page 1180 if you need
help with this step.

Optionally, specify an initial directory and path.

Click Trace execution if you want to display processing information generated by the
custom document wizard in the Output Window of the Stylus Studio editor window
associated with the custom document wizards Document type.

Click OK.

Stylus Studio User Guide

Chapter 18

The Stylus Studio Java API

Note The material previously in this chapter was deprecated in Stylus Studio 2007 XML

Enterprise Suite Release 2. The functionality provided by the Stylus Studio Java API has
been replaced by DataDirect XML Converters standalone components for Java and
.NET. See the DataDirect XML Converters documentation for more information:
http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp.

Stylus Studio User Guide

1187

The Stylus Studio Java API

1188

Stylus Studio User Guide

Chapter 19

Stylus Studio GUI Reference

This section includes topics associated with Stylus Studios context-sensitive help. To
display context-sensitive help within Stylus Studio, press F1.

Generate XQuery from EDI Standards

Generate XQuery/XML Schema
Go To (Custom XML Conversion)
Go To
Group Definition

I
Illegal Character Found
Import File
Imported Files
Imported Modules

J
Java Class Browser
Java Code Generation
Java Editor

K
Keyboard Accelerators

L
Lookup List

M
Message Definition

N
Name
Named Template

1192

Stylus Studio User Guide

Named/Matched Template
New Custom XML Conversion Definition
New EDI to XML Conversion
New Function
Notes

O
Open and Save As
Options
Options - Application Settings
Options General Back-mapping
Options General Components XML Converters for Java
Options General Components XML Converters for .NET
Options General Components DataDirect XQuery
Options - General - Custom Document Wizards
Options - General - Custom Tools
Options - General - Custom Validation Engines
Options - General - Editor Format
Options - General - Editor General
Options - General - Editor Sense:X
Options - General - File Types
Options - General - Java Virtual Machine
Options General Spell Checking
Options - Module Settings - EDI to XML - EDI Viewer Settings
Options - Module Settings - Java - Debugger
Options - Module Settings - WSDL Editor - WSDL Details
Options - Module Settings - XML Diff - Engine

Stylus Studio User Guide

1193

Stylus Studio GUI Reference

Options - Module Settings - XML Diff - Presentation

Options - Module Settings - XML Editor - XML Settings
Options - Module Settings - XML Schema Editor - Schema Details
Options - Module Settings - XML Schema Editor - Documentation
Options - Module Settings - XML Schema Editor - XML Schema to XML
Options - Module Settings - XQuery - Mapper
Options - Module Settings - XQuery - XQuery Settings
Options - Module Settings - XSLT Editor - Mapper
Options - Module Settings - XSLT Editor - XSLT Settings
Output Window

P
Personal Dictionary Editor
Preview Window
Processor Mismatch
Processor Settings (XQuery)
Processor Settings (XSLT)
Project Window
Project Wizards
Properties for Custom XML Conversions
Properties for DTD Nodes
Properties for EDI to XML Conversions
Properties for XML Pipelines
Properties for XML Publisher
Properties for XML Schema and WSDL Documents
Proxy Settings

1194

XQuery Editor XQuery Source Tab

XQuery Editor Mapper Tab
XQuery Editor Plan Tab
xsl:choose
XSLT Editor Mapper Tab
XSLT Editor Params/Other Tab
XSLT Editor XSLT Source Tab

1198

Stylus Studio User Guide

About Stylus Studio XML Enterprise Suite

The About... dialog box displays information about your Stylus Studio installation,
including your Installation ID and available number of licenses.

Fields
Framework version

The build number of your Stylus Studio installation.

Module versions

The build number associated with Stylus Studio feature modules.

Java Virtual Machine

Version number and related information for the Java Virtual Machine that Stylus
Studio detected on your system.
Visit Our Home Page

An invitation to visit our home on the World Wide Web.

Discussion Forum

The URL for the Stylus Studio Developer Network (SSDN), Stylus Studios online
forum and resource for XML developers.

Button
Activation and Registration

You use this button to activate or register your copy of Stylus Studio. You might need
to do this if, for example, you complete your evaluation of a Stylus Studio trial copy
and then decide to purchase it.

For More Information

Getting Started with Stylus Studio on page 1

Stylus Studio User Guide

1199

Stylus Studio GUI Reference

About Stylus Studio XML Home Edition

The About... dialog box displays information about your Stylus Studio installation,
including your Installation ID and available number of licenses.

Fields
Framework version

The build number of your Stylus Studio installation.

Module versions

The build number associated with Stylus Studio feature modules.

Java Virtual Machine

Version number and related information for the Java Virtual Machine that Stylus
Studio detected on your system.
Visit Our Home Page

An invitation to visit our home on the World Wide Web.

Discussion Forum

The URL for the Stylus Studio Developer Network (SSDN), Stylus Studios online
forum and resource for XML developers.

Button
Activation and Registration

For More Information

Getting Started with Stylus Studio on page 1

1200

Stylus Studio User Guide

About Stylus Studio XML Professional Suite

The About... dialog box displays information about your Stylus Studio installation,
including your Installation ID and available number of licenses.

Fields
Framework version

The build number of your Stylus Studio installation.

Module versions

The build number associated with Stylus Studio feature modules.

Java Virtual Machine

Version number and related information for the Java Virtual Machine that Stylus
Studio detected on your system.
Visit Our Home Page

An invitation to visit our home on the World Wide Web.

Discussion Forum

The URL for the Stylus Studio Developer Network (SSDN), Stylus Studios online
forum and resource for XML developers.

Button
Activation and Registration

For More Information

Getting Started with Stylus Studio on page 1

Stylus Studio User Guide

1201

Stylus Studio GUI Reference

Add Column
The XML Editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
You use the Add Column dialog box to add attribute and element columns to a table in the
Grid tab of the XML Editor. Columns are added to the table after the last column of its
type new attribute columns follow the last attribute column, for example.

Fields
Column name

The name you want to assign to the column; becomes the attribute or element name
in XML.
Default value

The default value you want to assign to a column.

For More Information

Adding Columns on page 170
Working with Columns on page 170
Using the Grid Tab on page 161

1202

Stylus Studio User Guide

Add Element or Composite Reference

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Add Element or Composite Definition dialog box to add an element or
composite reference to a segment, composite, repetition, variation, or to another element
or segment reference. The modified definition resides in the SEF file for your EDI to
XML Conversion.

Fields
Choose an element or composite

You can choose an existing element or composite from the Choose an element or
composite drop-down list, or create a new one by clicking either the New Element or
New Composite button. Clicking these buttons displays the Element Definition dialog
box or Composite Definition dialog box, respectively.
Modifier

Indicates whether the element or composite reference is used in your customized EDI
structure. For new element or composite references, you can leave this field empty. If
you are modifying an existing element or composite reference because you want to
indicate that it is not used in your customized EDI structure, set Modifier to Not Used
instead of removing it from the EDI structure.
Valid values for this property are Dependent, Must be used, Not recommended, Not
used, Recommended.
Requirement

Whether the reference is Optional, Mandatory, Conditional, or Dependent. The

default is Optional for most dialects; it is Conditional for EDIFACT.
Repeat Count

The number of times the reference can occur within the segment, composite, or other
definition.
Minimum

The references minimum length. (Displayed for element reference

Maximum

The references maximum length.

Ordinal

Stylus Studio User Guide

1203

Stylus Studio GUI Reference

The references place within the segment, composite, or other definition. This field is
grayed out unless you have set the EDI Structure Loop Sequence Enabled property
to True. Default value if present, has been calculated not to interfere with other
definitions.

For More Information

Creating an Element or Composite Reference on page 351
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1204

Stylus Studio User Guide

Add References to Schema

You use the Add References to Schema dialog box specify the external XML Schemas
you want to reference in the current XML Schema including the Schema element in a
WSDL document. You can reference external XML Schemas by including them,
importing them, or redefining them.

Fields
Type of reference

The way in which you want the external XML Schema referenced by the current
XML Schema:

Include The external schema is referenced using the xsd:include instruction.

Import The external schema is referenced using the xsd:import instruction.

Redefine The external schema is referenced using the xsd:redefine instruction,

which allows you to modify complexTypes, simpleTypes, and groups in the
current XML Schema.
Document location

The URL of the external XML Schema referenced by the current XML Schema or
Schema element in a WSDL document. Used to specify the schemaLocation= attribute
of the referencing instruction (xsd:include, for example).

For More Information

Referencing XML Schemas in the Diagram View on page 638
Referencing External XML Schemas on page 636
Defining an XML Schema Using the Diagram Tab Getting Started on page 66
Defining XML Schemas on page 567

Stylus Studio User Guide

1205

Stylus Studio GUI Reference

Add Segment Reference

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Add Segment Reference dialog box to add a segment reference to a group or
message. The customized EDI definition resides in the SEF file for your EDI to XML
Conversion. You can choose an existing segment or create a new one to create the segment
reference.

Fields
Choose a segment

The segment you want to use to create the segment reference. Choose an existing
segment from the drop-down list, or create a new segment by clicking the New button.
(Clicking the New Segment button displays the Segment Definition dialog box,
which you use to create the new segment.)
Modifier

Indicates whether the segment reference is used in your customized EDI structure.
For new segment references, you can leave this field empty. If you are modifying an
existing segment reference because you want to indicate that it is not used in your
customized EDI structure, set Modifier to Not Used instead of removing the segment
reference from the EDI structure.
Valid values for this property are Dependent, Must be used, Not recommended, Not
used, Recommended.
Requirement

Whether the segment reference is Optional, Mandatory, Conditional, or Facultatif.

The default is Optional for most dialects; it is Conditional for EDIFACT.
Maximum Use

The number of times the segment reference can appear within a group or message.
Ordinal

The segment references place within the group or message.

Position

The position within the group or message at which the segment reference starts.

1206

Stylus Studio User Guide

Add Segment Reference

For More Information

Creating a Segment Reference on page 349
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

Stylus Studio User Guide

1207

Stylus Studio GUI Reference

Add Table
The XML Editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
You use the Add Table dialog box to add a nested table to a table in the Grid tab of the
XML Editor.

Fields
Path to the root

The path to the root. By default, the table you add is created as a child of the current
table.
Row element name

The name you want to use for the row element in the XML.
Number of rows

The number of rows you want to create in the new table. The default is 2.

For More Information

Adding a Nested Table on page 173
Working with Tables on page 172
Using the Grid Tab on page 161

1208

Stylus Studio User Guide

Assign Shortcut

Assign Shortcut
Use the Assign Shortcut dialog box to specify the keyboard shortcut for performing a
Stylus Studio task. To display the Assign Shortcut dialog box, select Tools > Keyboard
from the Stylus Studio menu bar. In the Select a macro field, click the macro for which
you want to define a shortcut. Click Create Shortcut.

Fields
Press new shortcut key:

Press the key or keys that you want to be the shortcut. For example, Ctrl+E, F7,
Alt+H.

For More Information

Defining Keyboard Shortcuts on page 125

Stylus Studio User Guide

1209

Stylus Studio GUI Reference

Associate Schema with Variable

You use the Associate Schema with Variable dialog box to change the association of an
XML document being used as a data source for XQuery.

For More Information

Source Documents and XML Instances

1210

Stylus Studio User Guide

Associate XML Schemas to Project Folder

You use the Associate XML Schemas to Project Folder dialog box to associate an XML
Schema with a Stylus Studio project folder. This feature allows you to validate any XML
document in the project against that XML Schema without explicitly associating the
document with the XML Schema if the XML document contains a namespace prefix
found in the XML Schema associated with the project, Stylus Studio can validate it.

Fields
Schema files

The name of the XML Schema file associated with the current project.
Namespace URI

The namespace URI associated with the XML Schema.

Buttons
Displays the Open dialog box, which lets you browse for an XML Schema.
Disassociates the selected XML Schema from the project.

Associating an XML Schema with a Project

To associate an XML Schema with a project:
1.

Right-click the project folder you want to associate with an XML Schema.

Select Associate Schemas to Folder from the shortcut menu.

The Associate XML Schemas to Project Folder dialog box appears.

Click the browse button (

).
The Open dialog box appears.

Browse for the XML Schema you want to associate with the project.

Click OK.
The XML Schema you selected appears in the Schema Files field; the namespace
URI defined in that XML Schema appears in the field.

Stylus Studio User Guide

1211

Stylus Studio GUI Reference

Click OK.

For More Information

Validating XML Documents
Associating an External Schema With a Document

1212

Stylus Studio User Guide

Associate with XML Instance

XML Publisher is available only in Stylus Studio XML Enterprise Suite.
The Associate with XML Instance dialog box prompts you to associate an XML instance
with any XML Schema or DTD documents you are using as data sources in your XML
Publisher report.

Fields
Schema

The URL of the XML Schema or DTD you selected as a data source.
XML Instance

The URL of the XML instance you want to associate with the XML Schema.

For More Information

Using XML Schema or DTD as a Data Source
Adding a Data Source
Working with Data Sources
Building an XML Publisher Report

Stylus Studio User Guide

1213

Stylus Studio GUI Reference

Attach to JVM
To connect Stylus Studio to a JVM that is running in another application, click Attach in
the Stylus Studio tool bar. JVM 1.4.x is required. This is useful for debugging applications
while they are running.

Fields
Host

Specify the name of the host machine for the JVM you want to attach. The default is
localhost.
Port

Specify the port you want to use. The default is 8000.

For More Information

Requirements for Java Debugging on page 561
Setting Options for Debugging Java on page 562
Example of Debugging Java Files on page 564

1214

Stylus Studio User Guide

Authentication Required

Authentication Required
The Authentication Required dialog box appears when you are trying to open a document
on a server to which you previously established a connection, and the connection has been
dropped or lost. This can happen, for example, upon restarting Stylus Studio when the last
document opened was one stored on a remote database. The servers host and port are
displayed by default. You need to provide the username and password required to log in
to that host.

Fields
User Name

The name used to log in to the host displayed at the top of the Authentication
Required dialog box.
Password

The password associated with the username.

Stylus Studio User Guide

1215

Stylus Studio GUI Reference

Backmap Stack
The Backmap Stack window displays the code stack of XSLT instructions that generated
a particular part of the result document. To display the Backmap Stack window, in the text
or browser view of the Preview window click the output for which you want to see the
XSLT instructions.
You can do this during debugging or after completely applying a stylesheet.
The Backmap Stack window displays one or more XSLT instructions, and flags the line
in the stylesheet that contains the first instruction in the list. To find the location of another
instruction, click that instruction in the Backmap Stack window.

For More Information

Displaying XSLT Instructions for Particular Output on page 556

1216

Stylus Studio User Guide

Breakpoints

Breakpoints
In the Stylus Studio tool bar, click Breakpoints
all open files.

to display a list of the breakpoints in

Fields
Locations

Lists the file path and line number for each breakpoint in each open file.

Buttons
Remove

Removes the breakpoints from the selected locations. Select the locations where you
want to remove the breakpoints, click Remove, and then click OK.
Remove All

Removes all breakpoints in all open files. Click Remove All and then click OK.
Go To

Closes the Breakpoints dialog box and moves the cursor to the first selected
breakpoint location. Does nothing if no locations are selected.

For More Information

Using Breakpoints on page 552

Stylus Studio User Guide

1217

Stylus Studio GUI Reference

Build Project From SCC

Use the Build Project From SCC dialog box to specify the source code control application
that contains files from which you want to create a Stylus Studio project.
To display this dialog box, select File > Project > New Project Wizard from the Stylus
Studio menu bar. In the Project Wizards dialog box that appears, click Project From SCC
and click OK.

Fields
Provider to use

Click the down arrow. Stylus Studio displays a list of the source code control
applications you have installed. Click the one that controls the files from which you
want to create a Stylus Studio project.
Recursively import all subprojects

If you want the Stylus Studio project to contain a hierarchy of files, check this box.
User Name

Appears if you click Advanced.

Project Name

Appears if you click Advanced.

Auxiliary Path

Appears if you click Advanced.

Working Dir

Appears if you click Advanced. Specify a local directory.

Buttons
Advanced

Displays additional fields.

For More Information

Using Stylus Studio with ClearCase on page 113
Using Stylus Studio with Zeus CVS on page 116

1218

Stylus Studio User Guide

C# Code Generation

C# Code Generation
The C# Code Generation wizard is available only in Stylus Studio XML Enterprise
Suite.
You use the C# Code Generation dialog box to specify information Stylus Studio will use
to generate C# code for the current XQuery or XSLT. C# files are generated with a .cs
extension.

Fields
Target directory

The target directory in which you want the C# code created.

Stylus Studio uses the namespace name to create a folder in the target directory you
specify. If you use myNamespace, for example, the generated code is written to
c:\temp\myPipelineC#Code\myNamespace. (Though optional, it is considered good
practice to create a namespace.)
Class name

Stylus Studio uses the class name for the .cs file created by the Code Generation
wizard. For example, if you provide the name myClass, Stylus Studio creates
c:\temp\myPipelineC#Code\myClass.cs. Stylus Studio uses the XML pipeline name
as the default class name.
Saxon .NET folder

Allows you to specify the location of Saxon .NET on your system. Stylus Studio adds
this URL to the Microsoft Visual Studio 2005 project, allowing the generated C# code
for .NET to compile.
Create a Main method

Whether or not you want the resulting .cs file to contain a static
[ ] args) method.

void Main(String

Open the generated file

Whether or not you want to open the generated code file. If selected, the generated C#
file is opened in whatever application is registered to open .cs files.

Stylus Studio User Guide

1219

Stylus Studio GUI Reference

Embed the XQuery source in the generated program

Whether or not you want to embed the XQuery source in the generated C# code. This
option is available when using either the Saxon XQuery or DataDirect XQuery
processors.
Note: This option appears only if you are generating XQuery code.
Add the class to a Visual Studio 2005 project

Either creates a new Visual Studio 2005 project or updates an existing one. If a new
project is created, it is automatically opened with whatever application is registered
to open .csproj files. The .csproj file contains all the necessary references to the
generated .cs file, as well as all the .dll files that the .cs file requires.
To run the .cs file, simply press Ctrl+F5 in Visual Studio.

For More Information

Generating C# Code for XQuery
Generating C# Code for XSLT

1220

Stylus Studio User Guide

Call Stack

Call Stack
The Call Stack window displays a list of the locations at which processing was suspended.
To display the Call Stack window, click Call Stack
in the Stylus Studio tool bar. This
button is active only when processing is suspended because of a breakpoint.
For Java classes, Stylus Studio displays the class name, function name, parameters, and
line number. For stylesheets, Stylus Studio displays the template name, path for the
stylesheet, and the line number.
When processing is complete, the call stack is empty.
When execution is suspended, you can use the Call Stack window to jump directly to the
Java or XSLT source. Double-click on a stack line to go to that location. A green triangle
appears to indicate this location in the source file.

For More Information

Displaying a List of Process Suspension Points on page 555

Stylus Studio User Guide

1221

Stylus Studio GUI Reference

Choose Module
Stylus Studio displays the Choose Module dialog box when you try to open a file and that
file has a file name extension that Stylus Studio does not recognize.

Fields
Choose a module

Click the Stylus Studio module that you want to use to view your file.
Always use this module for this file type

Click this box when you want Stylus Studio to always use the module you selected to
open files with the same file name extension as the file you are now opening.

For More Information

Opening Unknown File Types on page 93

1222

Stylus Studio User Guide

Choose Provider

Choose Provider
When you want to put a file under source control, you must specify the source code
control provider you want to use.
To display the Choose Provider dialog box, the file you want to add to source control must
belong to a project. Select the file, and then click Add to Source Control in the Stylus
Studio tool bar.

Fields
Choose the Source Code Control Provider to use:

Click the down-arrow and select an installed source code control provider.

For More Information

Using Stylus Studio with Source Control Applications on page 109

Stylus Studio User Guide

1223

Stylus Studio GUI Reference

Choose Root Element

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite. XML Publisher is available only in Stylus
Studio XML Enterprise Suite.
You use the Choose Root Element dialog box to specify the element you want to use as
the root element when using an XML Schema or a DTD as a data source (in the XQuery
Mapper and XML Publisher) or as a target document structure (in the XQuery Mapper).

Fields
Choose Root Element

This field displays a list of elements in the DTD or XML Schema. Click the dropdown list, and then click the element that you want to specify as the root element.
Associate With

This field appears only when you add a second DTD or XML Schema to the XQuery
Mapper source. You use it to specify the XML instance that you want to associate
with the DTD or XML Schema.
This field does not appear if the DTD or XML Schema is the first source document
you add to the XQuery Mapper Stylus Studio uses the XML Source document
specified in the Scenario Properties dialog box as the XML instance in this case.

For More Information

XQuery Mapper
Building an XQuery Using the Mapper
Data Sources
Specifying a Target Structure
Source Documents and XML Instances

XML Publisher
Using XML Schema or DTD as a Data Source
Adding a Data Source

1224

Stylus Studio User Guide

Choose Root Element

Working with Data Sources

Stylus Studio User Guide

1225

Stylus Studio GUI Reference

Choose Server
Use the Choose Server dialog box to connect to a server (WebDAV, FTP, TigerLogic
XDMS, and so on).

Fields
Server Name

Type the name of the host on which the server you want to access resides.
User Name

Type your user name on the specified host.

Password

Type your password on the specified host.

For More Information

Opening Files in Stylus Studio

1226

Stylus Studio User Guide

Choose Source and Destination Schema

Use this dialog box to specify the locations of the source and destination schemas for a
stylesheet you want to create.

Fields
Add Source Document
File Path

Absolute path of an XML document whose schema you want to map to another XML
document.
Root Element

If the source schema is a DTD or XML Schema, identify the node that you want to be
the root element.
Set Target Document
File Path

Absolute path of an XML document whose schema you want another XML document
to map to.
Root Element

If the destination schema is a DTD or XML Schema, identify the node that you want
to be the root element.

For More Information

Overview of the XSLT Mapper on page 508
Steps for Mapping XML to XML on page 515

Stylus Studio User Guide

1227

Stylus Studio GUI Reference

Choose the WSDL Operation

You use the Choose the WSDL Operation dialog box to specify the WSDL document and
the Web services operation you want to represent in the XQuery Mapper using the
ddtek:wscall function.

Fields
WSDL File

The location and name of the WSDL document whose operation(s) you want to represent
in the XQuery Mapper.
Operation Name

The name of the Web services operation you want to represent in the XQuery Mapper.
This field is populated only after you select a WSDL document.

For More Information

Creating a ddtek:wscall Function on page 921
Choosing a ddtek:wscall Function on page 921
Using Web Services in XQuery on page 921

1228

Stylus Studio User Guide

Class Properties

Class Properties
To specify arguments that Stylus Studio uses to run the active Java class, select Java >
Class Properties from the Stylus Studio menu bar. You must have a Java file open in
Stylus Studio for Java to appear in the menu bar.

Fields
Arguments when running class

Specify any arguments needed to run your Java code.

For More Information

Debugging Java Files on page 561

Stylus Studio User Guide

1229

Stylus Studio GUI Reference

Code Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Code Definition dialog box to add a code value to a code list or element. The
customized EDI definition resides in the SEF file for your EDI to XML Conversion. You
can create a code with a single value or a range of values.

Fields
Single Code

Use the Value and Description fields in the Single Code group box to create a single
code value and a description. Values are always created in upper case.
Range

Use the Begin and End fields in the Range group box to create a range of code values
AA to AZ, for example. Values are always created in upper case.

For More Information

Creating a Code on page 354
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1230

Stylus Studio User Guide

Code List Definition

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Code List Definition dialog box to add a code list definition to the EDI
structure associated with your EDI to XML Conversion. The code list definition resides
in the SEF file for your EDI to XML Conversion.

Fields
Code List Name

The name you want to give to the code list. Names are always created in upper case.

For More Information

Adding a Code List on page 347
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

Stylus Studio User Guide

1231

Stylus Studio GUI Reference

Composite Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Composite Definition dialog box to add a composite definition to the EDI
structure associated with your EDI to XML Conversion. The composite definition resides
in the SEF file for your EDI to XML Conversion.

Fields
Composite Name

The name you want to give to the composite. Names are always created in upper case.
Description

The description associated with this composite. This field is optional.

For More Information

Adding a Composite on page 347
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1232

Stylus Studio User Guide

Configure External XQuery Processor

You use the Configure External XQuery Processor dialog box to specify the port number
on which you want Stylus Studio to listen for messages from the external instance of the
XQuery processor.

Fields
Port number

The port number on which you want Stylus Studio to listen for messages from the
external XQuery processor.

For More Information

Selecting an XQuery Processor
Creating an XQuery Scenario on page 900

Stylus Studio User Guide

1233

Stylus Studio GUI Reference

Connection Settings
You use the Connection Settings dialog box to specify connectivity settings for a
relational database server.

Fields
Database Type

The type of database to which you want to connect. You can connect to one of the
default relational databases supported by Stylus Studio (Oracle, MS SQL Server,
Informix, and so on).
See Supported Databases for more information about this field.
Driver Classpath

For certain relational databases (MySQL Community Edition and PostgreSQL, for
example), you need to specify the classpath of the driver that supports the relational
database.
Server URL

The servers network location and other information including the server name, the
port through which the connection is established, and other information, such as a
server ID (SID). Stylus Studio displays default information for this field when you
select a database type.
See Using the Server URL Field for more information about this field.
Username

The username required to log in to the database.

Password

The password associated with the username.

For More Information

How to Create a Database Connection
How to Edit a Database Connection
Creating a Database Connection
Working with Relational Data Sources

1234

Stylus Studio User Guide

Convert DTD to XML Schema

You use the DTD to XML Schema document wizard to convert a Document Type
Definition (DTD) to an XML Schema (an .xsd file in Stylus Studio).

Fields
DTD URL

The URL of the DTD file you want to convert to an XML Schema.
Use a target namespace

Optionally, the URL of the target namespace you want to specify in the XML Schema
created by the document wizard.

For More Information

Creating XML Schema from a DTD on page 569
Creating XML Schema from an XML Document on page 574
Creating Your Own XML Schema on page 569
Creating an XML Schema in Stylus Studio on page 568

Stylus Studio User Guide

1235

Stylus Studio GUI Reference

Convert HTML to XML

You use the Convert HTML to XML document wizard to convert an HTML file to an
XML document.

Fields
Choose HTML File to Convert to XML

The name of the HTML file you want to convert to XML.

For More Information

Creating XML Documents

1236

Stylus Studio User Guide

Convert HTML to XSLT

You use the Convert HTML to XSLT document wizard to convert an HTML file to an
XSLT stylesheet (.xsl).

Fields
Choose HTML file to convert

The name of the HTML file you want to convert to XSLT.

For More Information

Getting Started with XSLT

Stylus Studio User Guide

1237

Stylus Studio GUI Reference

Convert XML to XML Schema

You use the Convert XML to XML Schema document wizard to convert an XML
document to XML Schema (.xsd).

Fields
XML Document

The path of the XML document you want to convert to XML Schema. You can type
the path, or you can use the browse button (
) to navigate computer and network
file systems.
Generated XSD

The path of the XML Schema document you to create. You can type the path, or you
can use the browse button (
) to navigate computer and network file systems.

For More Information

Creating XML Schema from an XML Document
Creating an XML Schema in Stylus Studio

1238

Stylus Studio User Guide

Create Java Console

You use the Create Java Console dialog box to provide information for the Java Console
document wizard.

Fields
Package

Specify the Java package you want the new class to be in.
Class

Specify the name of the new Java class you want the wizard to create.

For More Information

Using the Java Editor
Debugging Java Files

Stylus Studio User Guide

1239

Stylus Studio GUI Reference

Create Java Servlet

You use the Create Java Servlet dialog box to provide information for the Java Servlet
document wizard.

Fields
Package

Specify the Java package you want the new class to be in.
Class

Specify the name of the new Java class you want the wizard to create.
Content Type

The servlets content type select HTML, XHTML, or XML from the drop-down list.

For More Information

Using the Java Editor
Debugging Java Files

1240

Stylus Studio User Guide

Create Relationship

Create Relationship
You use the Create Relationship dialog box to specify the nodes from one or more data
sources you want to use to group data, and to choose the operator used to compare the
node values.

Fields
You use the following fields to specify information for the from (Link From) and to (Link
To) data sources from which you are grouping data. You also choose the operator that is
used to compare the node values.
Table 189. Link From and Link To Properties
Field

Link From

Link To

Data Source

The URL of the first file added to the

data sources panel in the XML
Publisher Editor. You can choose a
different data source, if you have
added one, using the drop-down list.

The URL of the second file (if any)

added to the data sources panel in the
XML Publisher Editor. You can
choose a different data source, if you
have added one, using the drop-down
list.

Key

The node in the Link From data

source whose values you want to
compare to the values in a node in the
Link To data source.

The node in the Link To data source

whose valued are being compared to
the values of the node you selected
from the Link From data source.

Context

Sets the context for the outer FOR

loop in the generated XQuery or
XSLT code. Defaults to the node
selected in the Key field.

Sets the context for the inner FOR

loop in the generated XQuery or
XSLT code. Defaults to the node
selected in the Key field.

Compare

Control used to specify the type of comparison operation you want to perform on the
data source nodes you select. Valid values are:

Equal

Not equal

Less than

Greater than

Stylus Studio User Guide

1241

Stylus Studio GUI Reference

Less than or equal to

Greater than or equal to

For More Information

Grouping Data
Working with Data Sources
Building an XML Publisher Report

1242

Stylus Studio User Guide

Create Schema or DTD

Use the Create Schema or DTD dialog box to have Stylus Studio to create an XML
Schema or DTD based on the content of the current XML document and associate it with
that document.

Fields
Generate XML Schema

Stylus Studio generates an XML Schema based on the content of the current XML
document and associates the schema with that document.
Output File

Use this field to specify or select the location for the new XML Schema document.
Generate DTD

Stylus Studio generates a DTD based on the content of the current XML document.
Click Internal to insert the DTD at the beginning of your XML document.
Click External to place the DTD in a separate file that your XML document
references. If you click External, type a file path for the file that will contain the
schema, or click Browse to navigate to the desired location.

For More Information

Creating XML Schema from an XML Document
Defining Document Type Definitions on page 665

Stylus Studio User Guide

1243

Stylus Studio GUI Reference

Create User-Defined Catalog

You use the User-Defined Catalog Wizard to

Create your own catalog based on other catalogs and, optionally, add that catalog to
the current project

Add other catalogs to the list of available catalogs

Fields
Choose catalogs

A list of publicly available catalogs. This list is dynamic as new catalogs become
available, they are displayed by the User Defined Catalog Wizard.
Description

The description of the catalog in the Choose catalogs list box that currently has
focus.
Add to current project

Check this box if you want to add the user-defined catalog you are creating to the
current Stylus Studio project.
Save catalog to

Specifies the name and location of the user-defined catalog you are creating and
adding to the current project. You use this field only if you are adding the user-defined
catalog to the current project.

Buttons
Add catalog to list

Click this button if you want to add another catalog to catalogs displayed in the
Choose catalogs list.

1244

Stylus Studio User Guide

Create XML Document from DTD

You use the Convert DTD to XML document wizard to create an XML document based
on an existing DTD.
To get started, select File > Document Wizards from the Stylus Studio menu bar. In the
Document Wizards dialog box that appears, click DTD to XML, and click OK.
In the Create XML Document from DTD dialog box, specify the DTD from which you
want to create an XML document in the DTD File field. Next, specify the element that you
want to be the root element in the new XML document, and whether or not you want
expand each element only once (this results in a smaller XML document file).

Fields
DTD File

Type or navigate to a DTD from which you want to create an XML document. Click
to display the Open dialog box, where you can select the DTD you want.
Root Element

Allows you to specify the element that you want to be the root element in the new
XML document.
Expand each element only once

Check box that allows you to specify whether or not you want expand each element
only once in the final XML document this results in a smaller XML document file.

For More Information

Using Schemas with XML Documents on page 207

Stylus Studio User Guide

1245

Stylus Studio GUI Reference

Create XML Document from XML Schema

You use the Create XML Document from XML Schema dialog box to select the XML
Schema from which you want to create an XML document, and to specify characteristics
about that document including the root node, and whether or not you want to generate
comments in the XML.
Note If the XML Schema contains an element defined using a built-in type, the instance of that

Fields
Schema File

The XML Schema from which you want to create the XML document.
Schema Root

The element node in the XML Schema you want to use as the XML documents root.

For More Information

Using Schemas with XML Documents on page 207

1246

Stylus Studio User Guide

Custom Document Wizard Arguments

To display the Custom Document Wizard Arguments dialog box, select Tools > Options
from the Stylus Studio menu. Click Custom Document Wizards. In the Custom
Document Wizards dialog box, click Arguments.
Use the Arguments dialog box to specify the properties for the arguments required to run
a custom document wizard. Stylus Studio uses the properties to display a dialog box for
your custom document wizard. The end-user enters values for the arguments and then
Stylus Studio maps the values to the variables in the custom document wizard command
line.
The order in which the arguments appear in the Custom Document Wizard Arguments
dialog box is the order in which they appear in the dialog box that Stylus Studio generates
for user input before running your wizard.

Fields
Name

Specify the name of the argument that would appear in the command line that
executes your application. Required.
Description

Specify some text that indicates the purpose of this argument. When Stylus Studio
generates the dialog box for your custom document wizard, it uses the text you
specify here as the field name that prompts the user to enter a value. The user then
enters a value for this argument. Required.
Flag

This property allows you to specify a string that Stylus Studio uses as a prefix to the
argument value the user specifies. When Stylus Studio generates the command line
for executing your application, it inserts the flag you specify followed by a space
followed by the value that the user specifies for the argument. For example, you might
specify leading punctuation such as a dash (-) or forward slash (/).
The Flag property is required for Boolean arguments. It is optional for arguments of
other data types. When the value of a Boolean argument is true, Stylus Studio inserts
the value of the Flag property in the command line for executing your application.
Type

Specify the data type of the argument. This can be boolean, string, InputFile, or
OutputFile.

Stylus Studio User Guide

1247

Stylus Studio GUI Reference

Default Value

Specify a default value for this argument if it is an optional argument. Stylus Studio
uses this default value if the argument is optional and the end-user does not specify a
value. If you specify a default value for an argument that is required, Stylus Studio
ignores the default value. If an end-user does not specify a value for a required
argument, Stylus Studio displays a message that reminds the end-user that the
argument is required.
If the type of an argument is OutputFile, you cannot specify a default value.
Optional

Boolean value that indicates whether this argument is required for this custom
document wizard. When the type of an argument is OutputFile, the value of the
Optional property is always False and you cannot change it. That is, when the type of
an argument is OutputFile, the end-user must specify an argument value.

Buttons
Define a new argument.
Delete the selected argument.
Move the selected argument one place up in the list of arguments. The order of the
arguments here determines the correspondence to the %1, %2, %3, and so on, variables.
Move the selected custom document wizard one place down in the list of custom tools.

For More Information

Custom Document Wizards on page 1176

1248

Stylus Studio User Guide

Custom XML Conversion Editor

Stylus Studio GUI Reference

DataDirect XQuery Options

DataDirect XQuery is available only in Stylus Studio XML Enterprise Suite.
Stylus Studio is able to resolve certain URIs such as http://, file://, and ftp://. The
DataDirect XQuery Options dialog box allows you to register custom URI resolvers for
URI types that are not natively supported by Stylus Studio.
You can register one or more custom URI resolvers:

Collection URI resolver to resolve URIs in collection functions

Module URI resolver to resolve URIs in import module statements

Document URI resolver to resolve URIs in document functions

Fields
Collection URI Resolver Class

Use this field to specify the Java class for the custom collection URI resolver that you
want to register with Stylus Studio.
Module URI Resolver Class

Use this field to specify the Java class for the custom module URI resolver that you
want to register with Stylus Studio.
Document URI Resolver Class

Use this field to specify the Java class for the custom document URI resolver that you
want to register with Stylus Studio.

For More Information

Using Custom URI Resolvers
Selecting an XQuery Processor

1252

Stylus Studio User Guide

Default Value

Default Value
XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the Default Value dialog box to specify the default value to use for an XML
pipeline nodes input port. Default values specified here are always overridden if the input
port receives a value from another nodes output port.

Fields
Use this value as the default

Hard-coded default value that will persist across all XML pipeline executions, unless
the default value is overridden by a dynamic value (such as a value provided by
another nodes output port).
Read default value from this URL

A URL from which the default value will be read.

For More Information

Input and Output Ports
Adding Nodes to an XML Pipeline
XML Pipeline Node Properties Reference
Working with Nodes

Stylus Studio User Guide

1253

Stylus Studio GUI Reference

Description
The Description dialog box allows you to edit a value in the Properties window.

1254

Stylus Studio User Guide

Diagram Properties Schema Details

You use the Schema Details page of the Diagram Properties dialog box to specify which
properties of an XML Schemas nodes you want to display in the Diagram tab of the XML
Schema Editor. For each type of node (elements, complexTypes, and so on) and for a
nodes individual properties (name, type, and so on), you use the Inline visibility in
diagram settings to

Show the property and its value

Show the property only if it is not empty

Hide the nodes properties

In order to streamline presentation of the XML Schema in the diagram, most properties
are hidden by default.
Note You set node display properties for WSDL elements separately, using the WSDL Details

page.

Example
The following illustrations show how Inline visibility in diagram settings affect the
appearance of the Mode element in the ProductLine complexType.
Hide setting. This is the default setting. (The ProductInfo node is included for context).

Figure 588. Hide setting

Stylus Studio User Guide

1255

Stylus Studio GUI Reference

Show setting. Notice that even properties that do not have a value defined for them are

displayed:

Figure 589. Show setting

Show if not empty setting. Only those values for the Mode element that have been
explicitly set are displayed in the diagram:

Figure 590. Show if not empty setting

Fields
Category/Property

The node and, optionally, properties whose inline visibility settings you want to
change.
Inline visibility in diagram

The conditions under which you want to display a property and its values in the XML
Schema diagram. Inline visibility options are:

Hide The property and its value is always hidden. This is the default.

Show The property and its value is always displayed, even if the property does
not have a value.

1256

Stylus Studio User Guide

Diagram Properties Schema Details

Show if not empty The property and its value is displayed only if the property
has a value. Properties with a default value (maxOccurs=1, for example) and
properties for which no value has been explicitly set do not appear using this
setting.

Tip If all of a nodes properties have the same show/hide setting (Hide or Show if not empty,
for example), that value is displayed in the Inline Visibility in Diagram field. If no value
is displayed in the Inline Visibility in Diagram field, it means that two or more properties

have different show/hide settings.

Permanently Setting Display Properties

You can permanently set XML Schema diagram properties using the Options dialog box.
See Options - Module Settings - XML Schema Editor - Schema Details on page 1355.

For More Information

Introduction to the XML Schema Editor Diagram Tab
Defining an XML Schema Using the Diagram Tab Getting Started

Stylus Studio User Guide

1257

Stylus Studio GUI Reference

Diagram Properties WSDL Details

The WSDL Editor is available only in Stylus Studio XML Enterprise Suite.
You use the WSDL Details page of the Diagram Properties dialog box to specify which
properties of a WSDL documents nodes you want to display in the Diagram tab of the
WSDL Editor. For each type of node (message, binding, and so on) and for a nodes
individual properties (name, type, and so on), you use the Inline visibility in diagram
settings to

Show the property and its value

Show the property only if it is not empty (that is, undefined)

Hide the nodes properties

In order to streamline presentation of the WSDL in the diagram, most properties are
hidden by default.
Note You set node display properties for XML Schema elements separately, using the Schema
Details page.

Example
By default, Name, Binding, Address Type, and Address properties are shown for all port
elements, as shown in the following illustration. Notice that even properties that do not
have a value defined for them are displayed:

Figure 591. Show all properties

1258

Stylus Studio User Guide

Diagram Properties WSDL Details

Show if not empty setting. Only those values for the port element that have been explicitly

set are displayed in the diagram. (In this example, notice that the Address property is no
longer displayed.)

Figure 592. Show if not empty setting

Hide setting. If you choose this setting, none of the elements properties is displayed in

the diagram.

Figure 593. Hide setting

Fields
Category/Property

The node and, optionally, properties whose inline visibility settings you want to
change.
Inline visibility in diagram

The conditions under which you want to display a property and its values in the
WSDL diagram. Inline visibility options are:

Hide The property and its value are always hidden. This is the default for most
elements.

Show The property and its value are always displayed, even if the property does
not have a value.

Show if not empty The property and its value are displayed only if the property
has a value. Properties with a default value (maxOccurs=1, for example) and
properties for which no value has been explicitly set do not appear using this
setting.
Tip If all of a nodes properties have the same show/hide setting (all are set to Hide, for
example), that value is displayed in the Inline Visibility in Diagram field. If no value is
displayed in the Inline Visibility in Diagram field, it means that two or more properties

have different show/hide settings.

Stylus Studio User Guide

1259

Stylus Studio GUI Reference

Permanently Setting Display Properties

You can permanently set WSDL diagram properties using the Options dialog box. See
Options - Module Settings - WSDL Editor - WSDL Details on page 1347.

For More Information

Working with WSDL Elements
Using the WSDL Editor

1260

Stylus Studio User Guide

Diff Folders

Diff Folders
XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Diff Folders dialog box to select two folders you want to compare using the
Stylus Studio Differencing calculation. You can also use this dialog box to launch a
diffing operation for XML documents you select from the source and target folders.

Fields
Source Folder

Displays the path and name of the folder you select using the Choose Source Folder
button.
Target Folder

Displays the path and name of the folder you select using the Choose Target Folder
button.
Show files of type

Allows you to filter the display of the Source folder and Target folder fields to only
XML documents (files with a .xml extension). This is the default. You can also choose
to display all files in a given directory.

For More Information

Diffing Folders on page 182
Diffing a Pair of XML Documents on page 193
Diffing Multiple Documents on page 195

Stylus Studio User Guide

1261

Stylus Studio GUI Reference

Document Wizards
To access the document wizards, from the Stylus Studio menu bar, select File > Document
Wizards. There are three categories of document wizards:

EDI to XQuery Document Wizard

XML Editor Document Wizards

Java Document Wizards

EDI to XQuery Document Wizard

The EDI to XQuery document wizard lets you generate an XQuery file for the EDI
message you specify.
See Generating XQuery and XML Schema from EDI for more information.

XML Editor Document Wizards

In the XML Editor tab, the following wizards are available:

JSP 1.2/2.0 automatically creates a valid schema for a JSP page in XML format.

User-Defined Catalog lets you create a new catalog based on one or more existing
catalogs and, optionally, save that catalog to the current Stylus Studio project.

EDI to XSD lets you createa XML Schema for any of the numerous EDI dialects and
versions supported by DataDirect XML Converters.

XML Schema to XML generates an XML document from an XML Schema document.

DTD to XML Schema (TRANG) generates a sample XML document from a DTD using
the TRANG processor.

DTD to XML Schema generates a sample XML Schema from a DTD.

DTD to XML generates an XML document from a DTD.

HTML to XML converts an HTML file to XML format.

Text Catalog to XML Catalog converts a catalog in OASIS text format to XML format.

XML to XML Schema converts an XML document to an XML Schema.

Double-click the wizard you want to use (or click the wizard and then click the OK
button). Stylus Studio displays a dialog box that prompts you for the information needed
to complete the wizard.

1262

Stylus Studio User Guide

Document Wizards

Java Document Wizards

To access the document wizards, from the Stylus Studio menu bar, select File > Document
Wizards. Click the Java tab.
In the Java tab, the following wizards are available:

Servlet creates a simple servlet.

Console creates a simple console application.

Double-click the wizard you want to use. Stylus Studio displays a dialog box that prompts
you for the information needed to generate the Java file.

For More Information

Editing and Querying XML on page 137

Stylus Studio User Guide

1263

Stylus Studio GUI Reference

DTD Schema Editor Text Tab

To display the DTD schema editor in Stylus Studio, select File > New > DTD Schema from
the Stylus Studio menu bar.
Alternative: In Stylus Studio, open a file with .dtd as the file name extension. Stylus
Studio automatically opens the file in the DTD schema editor.
Use the Text tab of the DTD editor to enter the text for a DTD schema. You must know
DTD syntax and keywords.

Buttons
Indent XML Tags indents the XML. This action cannot be undone.
Check well-formed checks whether the DTD consists of well-formed XML.
Validate Document validates the DTD using the XML parser you select.
IE Preview displays the document in the Internet Explorer Web browser.
Change Font changes the font of the text display in Stylus Studio. This change affects
only the Stylus Studio display. Beyond personal preference, this is useful for localization.
The fonts that are available are the fonts that can display the characters in your XML file.
Open Schema allows you to open an external DTD, if the DTD has one. This feature

is not yet supported.

Indent and Validate are not active when you are viewing the text for a DTD.

For More Information

Defining Document Type Definitions on page 665
What Is a DTD? on page 666
Defining Elements in DTDs on page 671
About Modifiers in Element Definitions in DTDs on page 668
Defining General Entities and Parameter Entities in DTDs on page 680
Adding Comments to DTDs on page 683

1264

Stylus Studio User Guide

DTD Schema Editor Tree Tab

To display the DTD schema editor in Stylus Studio, select File > New > DTD Schema from
the Stylus Studio menu bar. Click the Tree tab.
Alternative: In Stylus Studio, open a file with .dtd as the file name extension. Stylus
Studio automatically opens the file in the DTD schema editor.
The Tree tab is the recommended way to define a DTD schema. You need not know DTD
syntax. To add an element, entity, comment, or white space to your DTD, click the DTD
node at the top of the display. Next, click the appropriate button in the left tool bar of the
Tree tab.

Buttons
Change the font used to display text in the DTD schema editor.
Delete the selected node.
Change the name of the selected node.
Move the selected node up.
Move the selected node down.

Toggle the display of white space.

Toggle Display of Entity References toggles the display of entity references in the
tree. Stylus Studio displays either the entity symbols or the entity values.

Stylus Studio User Guide

1265

Stylus Studio GUI Reference

Left Tool Bar Buttons

Table 190 describes the buttons in the left tool bar of the Tree tab. These buttons allow you
to define elements, entities, and comments in your DTD.
Table 190. Node Button Descriptions
Button

Description of New Node

New Element Definition

Define an element name.

New Attribute

Define an attribute name. This attribute is associated with the element that was
selected when you clicked New Attribute.
New Modifier

Click an element node, and then click this button to specify a modifier for the
data or subelements that you want the selected element to contain. You can
specify the following modifiers:

Optional - It is optional whether the contained node appears in an instance

document. If the contained node does appear, there can be only one.

Zero or more - There can be zero, one, or multiple instances of the

contained node in an instance document.

One or more - This contained node is required. There must be at least one
instance, and there can be multiple instances, of this contained node in an
instance document.

Choice - The selected element can contain one of the subelements for

Sequence - This selected element can contain other elements. If the

which there are references after this modifier.

contained elements are present in an instance document, the sequence of
the contained elements must be the same sequence in which they are
defined.
New Reference to Element

Click a DTD Modifier node (Choice or Sequence) and then click this button to
specify an element that the parent element of the Choice or Sequence node can
contain.

1266

Stylus Studio User Guide

DTD Schema Editor Tree Tab

Table 190. Node Button Descriptions
Button

Description of New Node

Add #PCDATA

Click a DTD Modifier node, and then click this button to add character data to
the element node.
New Entity

Click the DTD node at the top of the document. Then click New Entity to
define a general entity.
New Parameter Entity

Click the DTD node at the top of the document. Then click New Parameter
Entity to define a parameter entity.
New Text

Click the DTD node at the top of the document. Then click New Text to add
white space between elements, entities, or comments. Click the up arrow to
move the white space.
New Comment

Click the DTD node at the top of the document. Then click New Comment to
add a comment. Use the up arrow to move the comment. It can be between
elements or entities. You cannot insert it among the nodes that define an
element.

For More Information

What Is a DTD? on page 666
Defining Elements in DTDs on page 671
About Modifiers in Element Definitions in DTDs on page 668
Defining General Entities and Parameter Entities in DTDs on page 680
Adding Comments to DTDs on page 683

Stylus Studio User Guide

1267

Stylus Studio GUI Reference

DTD to XML Schema (Trang)

The Stylus Studio custom document wizard allows you to register user-defined wizards
that convert external files into formats that can be opened by Stylus Studio. The XSD from
DTD (Trang) is an example of a custom document wizard.
The XSD from DTD (Trang) document wizard takes a DTD file as its source and converts
it to an XML Schema document (XSD) using the Trang schema converter from Thai Open
Source Software Center (www.thaiopensource.com).

Fields
There are two types of fields in the XSD from DTD (Trang) document wizard:

Input fields (displayed in the wizard as [input]) control how the source file will be
interpreted and converted into XML Schema.

Output fields (displayed in the wizard as [output]) control formatting and other
characteristics of the generated XSD file.
Input file (required)

The name and location of the DTD file you want to convert to XSD. You can type the
file name or use the Browse button to browse a file system for the source DTD file.
[input] xmlns=<uri>

The default namespace; used for unqualified element names.

[input] xmlns:<prefix=uri>

The namespace for the element and autoboot names using prefix.
[input] colon-replacement=<chars>

The character that is used to replace colons in element names. Used when
constructing the names of definitions used to represent the element and attribute list
declarations in the DTD. Trang generates a definition for each element declaration
and attlist declaration in the DTD. The definition name is based on the element name.
In RELAX NG, the definition names cannot contain colons; colons are allowed in
element names in DTDs. Trang first tries to use the element names without prefixes.
If this results in a conflict, Trang replaces the colon with the chars specified. If no
chars is specified, a period is used.
[input] element-define=<name-pattern>

Specifies how to construct the name of the definition representing an element

declaration from the name of the element. The name-pattern must contain exactly one

1268

Stylus Studio User Guide

DTD to XML Schema (Trang)

percent character (%). This character is replaced by the name of the element, after
colon replacement, and the result is used as the name of the definition.
[input] inline-attlist / no-inline-attlist
inline-attlist specifies not to generate definitions for attribute list declarations.
Instead, attributes in attribute list declarations are moved into the definitions
generated for element list declarations.
no-inline-attlist generates a distinct definition (with combine=interleave) for
each attribute list declaration in the DTD; each element declaration definition
references the definition for the corresponding attribute list declaration.

[input] attlist-define=<name-pattern>

Specifies how to construct the name of the definition representing an attribute list
declaration from the name of the element. The name-pattern must contain exactly one
percent character (%). This character is replaced by the element name, after colon
replacement, and the result is used as the name of the definition.
[input] any-name=<name>

Specifies the name of the definition generated for the content of elements declared in
the DTD as having a content model of ANY.
[input] strict-any

Preserves the exact semantics of ANY content models by using an explicit choice of
references to all declared elements. By default, Trang uses a wildcard that allows any
element.
[input] annotation-prefix=<prefix>

Default values are represented using an annotation attribute prefix:defaultValue

where prefix is bound to http://relaxng.org/ns/compatibility/annotations/1.0 as
defined by the RELAX NG DTD Compatibility Committee Specification. By default,
Trang uses a for prefix unless that conflicts with a prefix used in the DTD.
[input] generate-start / no-generate-start

Specifies whether or not Trang should generate a start element. DTDs do not
indicate what elements are allowed as document elements. Trang assumes that all
elements that are defined but never referenced are allowed as document elements.
[output] encoding=<name>

Uses name as the encoding for output files.

[output] indent=<n>

Indents each indent level in the output file by n spaces.

[output] disable-abstract-elements

Stylus Studio User Guide

1269

Stylus Studio GUI Reference

Disables the use of abstract elements and substitution groups in the generated XML
schema.
[output] any-process-contents=strict|lax|skip

Specifies the value for the processContents attribute of any elements. The default is
strict, which corresponds to DTD semantics.
[output] any-attribute-process-contents=strict|lax|skip

Specifies the value for the processContents attribute of anyAttribute elements. The
default is skip, which corresponds to RELAX NG semantics.

1270

Stylus Studio User Guide

EDI Document Pane

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
The EDI document pane displays the content of the EDI document you are using to model
your EDI to XML Conversion. It provides a number of tools to help you understand how
your EDI differs from the EDI standard on which it is based and how to address any errors
it contains:

Yellow background indicates that the EDI version specified in the version drop-down
list does not match the EDI version in the document

Red background indicates that the EDI dialect specified in the dialect drop-down list
does not match the EDI dialect in the document

Red squiggles indicate that there is an error for a particular segment. Prev and Next
buttons help you locate errors

The status bar indicates the number of errors (if any) in the document

Tool tips appear when you hover the pointer on an error

Quick Fixes on the short-cut menu (right-click on an error) let you modify the XML
Converters properties or the EDI structure to resolve the error

Locate choices on the short-cut menu (right-click any line in the EDI document pane)
let you jump to the related node in the EDI Structure pane

For More Information

The EDI to XML Editor on page 317
Resolving EDI Document Errors on page 332
What is the EDI to XML Module? on page 316
Creating an EDI to XML Conversion on page 320

Stylus Studio User Guide

1271

Stylus Studio GUI Reference

EDI Structure Tree

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
The EDI Structure tree displays the structure of the current EDI standard as shown in the
Select Dialect and Select Version fields, including any extensions or modifications you
have made to it. By default, the dialect and version are inferred from the source EDI
document (if you used one to create the EDI to XML Conversion), but you can change
them at any time.
Definitions displayed in bold indicate some change to the EDI standard. Only changes to
the EDI standard are saved with the EDI to XML Conversions SEF file.
Short-cut (right-click any node) and the main EDI menu allow you to

Modify EDI standard definitions

Create new definitions

Explicitly import a standard definition to save with the SEF file

Navigate the EDI structure tree

For More Information

Views of the EDI Structure on page 342
The EDI to XML Editor on page 317
Importing EDI Standard Definitions on page 356
Customizing an EDI Standard on page 340
Creating an EDI to XML Conversion on page 320

1272

Stylus Studio User Guide

EDI to XML Editor

The EDI to XML editor is a visual editor that helps you create a file that can be used to
convert EDI files with the same structure and to preview the XML that results from that
conversion.
You can use the EDI to XML editor to:

Customize EDI standard definitions to accommodate proprietary or non-conforming

EDI. By default, the EDI Structure pane displays the structure of the EDI standard
associated with the EDI document displayed in the EDI document pane, but you can
change both the dialect and version to display the structure for any of the numerous
standards supported by DataDirect XML Converter ATIS, EDIFACT, EANCOM,
Edig@s, HIPAA, HL7, IATA, NCPDP, TRADACOMS, X12, and others.
You can import a local copy of EDI standard definitions and modify them in
numerous ways adding new values to a code list, changing a segments Requirement
property from Mandatory to Optional, and so on. See Customizing an EDI Standard
for more information on this topic.

Specify properties for the DataDirect XML Converter. The EDI to XML module uses
the DataDirect XML Converter engine to convert EDI to XML. See Specifying
XML Converter Properties for more information on this topic.

Preview the EDI to XML Conversion. When you click the Preview Result button
( ), Stylus Studio opens the Preview window and displays the XML that results
from converting the source EDI document using the parameters specified for the
XML Converter engine as well as changes made to the EDI standard, if any.

For More Information

EDI Document Pane on page 1271
EDI Structure Tree on page 1272
Properties for EDI to XML Conversions on page 1382
Creating an EDI to XML Conversion on page 320

Stylus Studio User Guide

1273

Stylus Studio GUI Reference

Element Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Element Definition dialog box to add an element definition to the EDI
structure associated with your EDI to XML Conversion. The element definition resides in
the SEF file for your EDI to XML Conversion.

Fields
Element Name

The name you want to give to the element. Names are always created in upper case.
Datatype

Choose the datatype for this element from the drop-down list.
Length

Specify the minimum and maximum lengths for this element in the Minimum and
Maximum fields.
Description

The description associated with this element. This field is optional.

For More Information

Adding an Element on page 346
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1274

Stylus Studio User Guide

Find

Find
Use the Find dialog box to search for text in a document. To display the Find dialog box,
from the Stylus Studio menu bar, click Find
.

Fields
Find what

Type the text you want to search for.

Match whole word only

For example, if you specify that you want to search for style, the search engine does
not find instances of stylesheet.
Match case

Finds instances that exactly match the lowercase and uppercase of the letters you
enter.
Regular expression

Interprets the text in the Find what field as a regular expression and conducts the
search based on that.
Search only inside

Indicate whether you want to restrict the search to element tags, element values,
attribute names, and/or attribute values.
Find Next

Jumps to the next instance of the string you are searching for.
Mark All

Marks each line that contains the text you are looking for. The mark is the light blue
rectangle that is the Bookmark symbol. Click in a line with a mark and then click
Toggle Bookmark
to toggle the display of that flag. Click Previous Bookmark
and Next Bookmark to move from mark to mark. Click Clear All Bookmarks
to remove all marks.

For More Information

Using Standard Editing Tools on page 429
Replace

Stylus Studio User Guide

1275

Stylus Studio GUI Reference

Find (Mapper)
You use the Find dialog box in the XQuery and XSLT Mappers to search for nodes in
source and target document trees. To display the Find dialog box, right-click in the source
or target document pane, and select Find from the shortcut menu.

Fields
Find what

Type the name of the node you want to search for.

Match whole word only

For example, if you specify that you want to search for author, the search engine does
not find instances of authors.
Match case

Finds instances that exactly match the lowercase and uppercase of the letters you
enter.
Regular expression

Interprets the text in the Find what field as a regular expression and conducts the
search based on that.
Search in

Indicate whether you want to restrict the search to element names and/or attribute
names.
Find Next

Jumps to the next instance of the string you are searching for.

For More Information

Building an XQuery Using the Mapper
Overview of the XSLT Mapper

1276

Stylus Studio User Guide

File Explorer

File Explorer
You use the File Explorer window to perform basic operations on the files in your Stylus
Studio applications and projects, such as opening a file in Stylus Studio, deleting a file
from a file system, renaming a file, and so on. Rather than selecting File > Open to open
an XML document, for example, you can simply select the document from the File
Explorer window and double-click it or drag it onto the Stylus Studio desktop.
You can also use the File Explorer window to define connections to relational databases
and other file systems (like WebDAV and FTP, for example).
Tip The File Explorer is a docking window, which means you can drag and drop it anywhere

in Stylus Studio or on your desktop.

For More Information

Using the File Explorer
Opening Files in Stylus Studio

Stylus Studio User Guide

1277

Stylus Studio GUI Reference

Generate C# .NET Code for XML Pipeline

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the Generate C# .NET Code for XML Pipeline dialog box to specify the properties
you want to use when generating C# code for your XML pipeline.

Fields
Target directory

The target directory in which you want the C# code created.

Whether or not you want the resulting .cs file to contain a static
[ ] args) method.

void Main(String

Execution log

Specifies the argument for the setExecutionLog method in the generated application.
Choices are Console.out (the default), Console.err, and Quiet. Set to Quiet to turn off
the log.
Open the generated file

1278

Stylus Studio User Guide

Generate C# .NET Code for XML Pipeline

Whether or not you want to open the generated code file. If selected, the generated C#
file is opened in whatever application is registered to open .cs files.
Embed the XQuery source in the generated program

Whether or not you want to embed the XQuery source in the generated C# code. This
option is available when using either the Saxon XQuery or DataDirect XQuery
processors. This option is available only if the Generate inline code check box is
selected.
Add the class to a Visual Studio 2005 project

For More Information

Generating Code for an XML Pipeline
Execution Framework and Code Generation
Specifying an Execution Framework
Deployment Considerations

Stylus Studio User Guide

1279

Stylus Studio GUI Reference

Generate Java Code for XML Pipeline

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the Generate Java Code for XML Pipeline dialog box to specify the properties
you want to use when generating Java code for your XML pipeline.

Fields
Target directory

Stylus Studio uses the package name to create a folder in the target directory you
specify. If you specify myPackage as the package name, for example, the generated
code is written to c:\temp\myPipelineJavaCode\myPackage. (Though optional, it is
considered good practice to create a package name.)
Class name

Stylus Studio uses the class name for the .java file created by the Java Code
Generation wizard. For example, if you provide the name myClass, Stylus Studio
creates c:\temp\myPipelineJavaCode\myPackage\myClass.java. Stylus Studio uses the
XML pipeline name as the default class name.
Add to generated to the current project

Whether or not you want to add the generated code to the current project. If you select
this option (it is on by default), the package structure (com.mycompany.payroll, for
example) is used to create a series of project folders at the current projects root
(com\mycompany\payroll, for example). If you use the default package (none), the
name.java file is added under the projects root.
Execution log

Specifies the argument for the setExecutionLog method in the generated application.
Choices are System.out (the default), System.err, and Quiet.
Generate inline code

1280

Stylus Studio User Guide

Generate Java Code for XML Pipeline

Whether or not you want to embed the XQuery source in the generated Java code.
This option is available when using either the Saxon XQuery or DataDirect XQuery
processors. This option is available only if the Generate inline code check box is
selected.

For More Information

Generating Code for an XML Pipeline
Execution Framework and Code Generation
Specifying an Execution Framework
Deployment Considerations

Stylus Studio User Guide

1281

Stylus Studio GUI Reference

Generate Transformation
XML Publisher is available only in Stylus Studio XML Enterprise Suite.
You use the Generate Transformation dialog box to specify the desired transformation
language (XSLT or XQuery) you want Stylus Studio to use when generating code for your
XML Publisher report.

Fields
Transformation Language

Whether you want Stylus Studio to generate the XML transformation using XQuery
1.0, XSLT 1.0, or XSLT 2.0.
Save Into

The URL to which you want to write the generated XQuery or XSLT. Stylus Studio
uses the .report file name as the default for the generated file.

For More Information

How to Generate Code
Generating Code for an XML Publisher Report
Building an XML Publisher Report

1282

Stylus Studio User Guide

Generate XML Schema from EDI Standards

You use the Generate XML Schema from EDI Standards dialog box to specify the settings
you want Stylus Studio to use to generate XML Schema from an EDI message.

Fields
Message

You use the fields in the Message group box to specify information about the EDI
standard for which you want to generate an XML Schema.

Dialect Drop-down list that lets you specify the EDI dialect for which you want
to generate an XML Schema.

Version Drop-down list that lets you specify the version for the EDI dialect you
selected.

Mode Certain EDI messages have alternate batch and interactive forms,
depending upon whether they are used between systems that have real-time
connections. The Interactive setting causes the interactive form to be used, if
available. For example, in EDIFACT, this would cause the normal envelope of
UNB/UNH/UNT/UNZ to be replaced by UIB/UIH/UIT/UIZ. Valid for
EANCOM, EDIFACT, and IATA only.

Message/Description The specific EDI message for which you want to generate
XML Schema.
XML Structure

You use the fields of the XML Structure group box to specify the structure of the XML

Use long element names Whether or not you want to use the long element
name as part of the XML tag UNB01-SyntaxIdentifier versus UNB01, for
example.

Prefix GROUP_N tags with the message name Adds the message name to the
GROUP_n prefix in the XML element tag. For example, <TS_831_GROUP_1>.

1283

Stylus Studio GUI Reference

Put decoded data values in decode= attributes Places decoded code list data

values in a decode= string in the element tag. For example, <ISA15

decode=Production Data>. By default, the decoded value is not output to XML.

XML Schema Options

The fields in this group box allow you to specify the settings that are used to generate
the XML Schema for the selected EDI message.

Write annotations describing each element Whether or not you want the
generated XML Schema to include annotations that are part of the EDI message.

Enumerations for elements that have codelists Whether or not you want the
generated XML Schema to include enumerations for fields that have lists of
values.

Use unbounded for maxOccurs when loop value is 99 or higher) Replaces

when generating XML Schema. The SEF file can augment information that Stylus Studio
uses to generate XML Schema customized EDI definitions are stored in the SEF file,
for example. If the same setting is specified by both the document wizard and the SEF file,
the SEF file value is used.

For More Information

Generating XQuery and XML Schema from EDI
The SEF File
Customizing an EDI Standard
Creating XML Schema from EDI
Working with XML Schema in Stylus Studio

1284

Stylus Studio User Guide

Generate XQuery from EDI Standards

You use the Generate XQuery from EDI Standards dialog box to specify the settings you
want Stylus Studio to use to generate an XQuery file from an EDI message.

Fields
Message

You use the fields in the Message group box to specify information about the EDI
standard for which you want to generate XQuery.

Dialect Drop-down list that lets you specify the EDI dialect for which you want
to generate XQuery.

Version Drop-down list that lets you specify the version for the EDI dialect you
selected.

Mode Whether the EDI is processed in batch or interactive mode. Valid for
EANCOM, EDIFACT, and IATA only.

Message/Description The specific EDI message for which you want to generate
the XQuery.
XML Structure

You use the fields of the XML Structure group box to specify the structure of the XML

Use long names for Whether or not you want to use the long element and/or
segment names as part of the XML tag UNB01-SyntaxIdentifier versus UNB01,
for example.

Prefix GROUP_N tags with the message name Adds the message name to the
GROUP_n prefix in the XML element tag. For example, <TS_831_GROUP_1>.

Stylus Studio User Guide

1285

Stylus Studio GUI Reference

XQuery Generate Options

Mandatory segments and elements only Generates only those segments whose
Requirement property is mandatory and, for them, only the mandatory element
and composite references.

All segments but only mandatory elements Generates all segments, but, for
each of them, only the mandatory element and composite references.

All segments and elements Generates all segments, and all element and
composite references specified for them.
Create XML Schema for this EDI Message

XSD File The URI for the XML Schema (.xsd) file that is output by the
document wizard.

Write annotations describing each element Whether or not you want the
generated XML Schema to include annotations that are part of the EDI message.

Enumerations for elements that have codelists Whether or not you want the
generated XML Schema to include enumerations for fields that have lists of
values.

Use unbounded for maxOccurs when loop value is 99 or higher) Replaces

For More Information

Generating XQuery and XML Schema from EDI

1286

Stylus Studio User Guide

Generate XQuery from EDI Standards

The SEF File

Customizing an EDI Standard

Stylus Studio User Guide

1287

Stylus Studio GUI Reference

Generate XQuery/XML Schema

You use the Generate XQuery/XML Schema dialog box to specify the settings you want
Stylus Studio to use to generate an XQuery file and/or an XML Schema from an EDI
message.

Fields
Message

Displays the name of the message; based on the message that was active in the EDI
Structure pane of the EDI to XML editor when you selected EDI > Generate
XQuery/XML Schema from the menu.
Mode

generate XQuery for the EDI message.

XQ File The URI for the file to which the generated XQuery is written. By
default, this is Untitledn_name.xquery file, where n is a unique number and name
is the EDI message name abbreviation.

Mandatory segments and elements only Generates only those segments whose
Requirement property is mandatory and, for them, only the mandatory element
and composite references.

All segments but only mandatory elements Generates all segments, but, for
each of them, only the mandatory element and composite references.

All segments and elements Generates all segments, and all element and
composite references specified for them.
Create XML Schema for this EDI Message A check box you use to indicate that you
want to generate XML Schema for the EDI message.

XSD File The URI for the file to which the generated XML Schema is written.
By default, this is Untitledn_name.xsd file, where n is a unique number and name
is the EDI message name abbreviation.

Write annotations describing each element Whether or not you want the
generated XML Schema to include annotations that are part of the EDI message.

1288

Stylus Studio User Guide

Generate XQuery/XML Schema

Enumerations for elements that have codelists Whether or not you want the

generated XML Schema to include enumerations for fields that have lists of
values.
Use unbounded for maxOccurs when loop value is 99 or higher) Replaces
maxOccurs values of 100 or greater with unbounded. This option ensures that
the generated XML Schema can be successfully validated by most processors.

For More Information

Generating XQuery and XML Schema from EDI
The SEF File
Customizing an EDI Standard

Stylus Studio User Guide

1289

Stylus Studio GUI Reference

Go To (Custom XML Conversion)

The Custom XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
You use the Go To dialog box in the Custom XML Conversion Editor to jump to a specific
location in the file you are using to create your custom XML conversion. Use this feature
to move the cursor to a specific position in

The file

A region

A row

Fields
Cursor Position in File
Go To Displays the cursors current position in the file, and allows you to specify

the position to which you want to move the cursor.

Maximum The total number of characters in the file read into Stylus Studio. Read
only.
Current Region Number
Go To Displays the cursors current region, and allows you to specify the region to

which you want to move the cursor. This field is grayed out if the file has only one
region.
Maximum The total number of regions in the file. Read only.
Cursor Position in Region
Go To Displays the cursors current position in the region, and allows you to specify
the position to which you want to move the cursor.
Maximum The total number of characters in the current region. Read only.
Row in Current Region
Go To Displays the cursors current row, and allows you to specify the row to which

you want to move the cursor.

Maximum The total number of rows in the current region. Read only.
Column in Current Row
Go To Displays the cursors current column, and allows you to specify the column

to which you want to move the cursor.

1290

Stylus Studio User Guide

Go To (Custom XML Conversion)

Maximum The total number of columns in the current row. Read only.

For More Information

Moving Around the Document on page 232
The Custom XML Conversion Definition Editor on page 225
Converting Non-XML Files to XML on page 213

Stylus Studio User Guide

1291

Stylus Studio GUI Reference

Go To
Use the Go To dialog box to specify the number of a line you want to jump to. To display
the Go To dialog box, in the Stylus Studio tool bar, click Go to a specified location
.

Fields
Enter the line number

Type the number of the line you want to jump to.

Stylus Studio displays line and column numbers in the lower right corner of the Stylus
Studio window.
You can set an option that displays line numbers to the left of each line in the editor
you are using. To do this, from the Stylus Studio menu bar, select Tools > Options,
and click Editor General. In the Editor field, select the editor in which you want to
display line numbers. Select the Show Line Numbers check box.

For More Information

Specifying Stylus Studio Options on page 120

1292

Stylus Studio User Guide

Group Definition

Group Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Group Definition dialog box to add a group definition to a message or another
group. The group definition, as well as the modified message or group definition, resides
in the SEF file for your EDI to XML Conversion.

Fields
Choose a loop trigger

The first segment in a group is referred to as the loop trigger. You can choose an
existing segment from the Choose a loop trigger drop-down list, or create a new one
by clicking the New Segment button. Clicking the New Segment button displays the
Segment Definition dialog box, which you use to create the new segment.
Group label (optional)

Use this field to provide a group label (GROUP_9, for example). If you leave it blank,
Stylus Studio assigns a unique group label.
Modifier

Indicates whether the group is used in your customized EDI structure. For new
groups, you can leave this field empty. If you are modifying an existing group because
you want to indicate that it is not used in your customized EDI structure, set Modifier
to Not Used instead of removing the group from the EDI structure.
Valid values for this property are Dependent, Must be used, Not recommended, Not
used, Recommended.
Requirement

Whether the group is Optional, Mandatory, Conditional, or Facultatif. The default is

Optional.
Maximum Use

The number of times the group can appear in the associated message or group.
Ordinal

The groups place within the associated message or group. This field is grayed out
unless you have set the EDI Structure Loop Sequence Enabled property to True.
Default value if present, has been calculated not to interfere with other segments or
groups in the message.

Stylus Studio User Guide

1293

Stylus Studio GUI Reference

Position

The position within the associated message or group at which the group starts. This
field is grayed out unless you have set the EDI Structure Loop Sequence Enabled
property to True. Default value if present, has been calculated not to interfere with
other segments or groups in the message.

For More Information

Creating a Group on page 350
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1294

Stylus Studio User Guide

Illegal Character Found

Stylus Studio displays the Illegal Character Found dialog box when it detects a character
in the file you are opening that is illegal for the type of editor in which you are trying to
open it. This can happen, for example, when you try to open an HTML file in the XML
Editor.

Fields
Skip it

Stylus Studio skips the illegal character and opens the file.
Preserve it

Stylus Studio preserves the illegal character, rendering it in the editor using whatever
means possible when the file is opened.
Escape it

Stylus Studio escapes the illegal character using Unicode when the file is opened.
Report the error

Stylus Studio displays an error concerning the illegal character like this:
Byte 0x92 found in file file://\\my_server\XqueryRoot\connectionpooling\index.html at offset 5547 is invalid for encoding utf-8

Stylus Studio does not open the file if you choose to report the error.

For More Information

Opening a Sample XML Document on page 10
Updating an XML Document Getting Started on page 10

Stylus Studio User Guide

1295

Stylus Studio GUI Reference

Import File
You use the Import File dialog box to select the WSDL document that you want to import
into the current WSDL document.

Fields
Document Location

The URL of the WSDL document you want to import into the current WSDL
document. You can use the browse button ( ) to navigate file systems, or you can
type the complete path yourself.

For More Information

Importing WSDL Documents
Making Imported WSDL Elements Available
Working with WSDL Documents

1296

Stylus Studio User Guide

Imported Files

Imported Files
You use the Imported Files dialog box to add (wsdl:import) external WSDL documents
to the current WSDL document. You might want to use this feature if you have a library
of messages, for example, defined in another WSDL document that you want to use in the
current WSDL document.

Fields
Files imported by this document

The URL and namespace of any WSDL documents referenced by the current WSDL
document. By default, this list box shows any imported WSDL documents already
defined in the current WSDL document.

Buttons
Add

Displays the Import File dialog box, which allows you to specify the WSDL
document you want to import in the current WSDL document. When you add a
WSDL document, Stylus Studio adds an <import> element whose location= attribute
is taken from the URL you selected when adding the WSDL document via the Import
File dialog box.
Remove

Removes the reference to the selected WSDL document from the current WSDL
document.

For More Information

Importing WSDL Documents
Making Imported WSDL Elements Available
Working with WSDL Documents

Stylus Studio User Guide

1297

Stylus Studio GUI Reference

Imported Modules
You use the Imported Modules dialog box to manage imported modules in an XQuery.
The Imported Modules dialog box

Displays any modules that have already been imported into the XQuery

Lets you import modules

Lets you remove imported modules

Fields
Namespace

The namespace associated with the imported module.

Location

The physical location of the XQuery in which the module is defined.

Buttons
Add

Displays the Open dialog box, which allows you select a module to import.
Remove

Removes the selected module from the XQuery.

For More Information

Importing a Library Module
Creating a Library Module
Removing a Library Module
Working with XQuery Library Modules

1298

Stylus Studio User Guide

Java Class Browser

You use the Java Class Browser dialog box:

In XQuery, to register the Java class associated with a custom URI resolver

In XSLT, to register a Java extension class. This dialog box can also appear during
stylesheet debugging when processing reaches the invocation, Stylus Studio
displays this dialog box and prompts you to indicate where it can find the Java file.

Fields
Class Name

Navigate to the desired file and double-click it.

For More Information

For XQuery
Registering a Custom URI Resolver on page 905
Registering a Default Custom URI Resolver on page 907
Using Custom URI Resolvers on page 904

For XSLT
Defining Java Functions in the XSLT Mapper on page 540
Overview of the XSLT Mapper on page 508
Debugging Stylesheets on page 551

Stylus Studio User Guide

1299

Stylus Studio GUI Reference

Java Code Generation

The Java Code Generation wizard is available only in Stylus Studio XML
Enterprise Suite.
You use the Java Code Generation dialog box to specify the package and class names and
other options for generating Java code from XQuery and XSLT.

Fields
Target directory

The directory to which you want to write the generated code. You can

Use the default the Windows Application Directory (C:\Documents and

Settings\dfoster\My Documents\Stylus Studio\sources, for example). The \Stylus
Studio folder is created when you install Stylus Studio; the \sources folder is
created for the generated code.

Type a directory path by hand.

Use the browse button (

) to select a file system directory.
Package name

The name you want to use for the Java package generated from the XQuery or XSLT.
Left blank by default.
Class name

The name you want to use for the Java class generated from the XQuery or XSLT. By
default, this is the name of the XQuery or XSLT document for which you are
generating Java code.
Add generated code to the current project

Whether or not you want to embed the XQuery source in the generated Java code.
This option is available when using either the Saxon XQuery or DataDirect XQuery
processors.
Note: This option appears only if you are generating XQuery code.
1300

Stylus Studio User Guide

Java Code Generation

For More Information

Generating Java Code for XQuery
Generating Java Code for XSLT

Stylus Studio User Guide

1301

Stylus Studio GUI Reference

Java Editor
To display the Java editor in Stylus Studio, select File > New > Java: Text Editor from the
Stylus Studio menu bar.
Alternative: In Stylus Studio, open a file with .java as the file name extension. Stylus
Studio automatically opens the file in the Java editor.
Use the Java source editor to write, update, and compile Java source files.

Fields
Compile the Java source file.
Change the font used to display text in the Java editor.

For More Information

Debugging Stylesheets on page 551

1302

Stylus Studio User Guide

Java Method Browser

You use the Java Method Browser dialog box to select the method you want to include in
your XQuery.

Fields
Class Name

Navigate to the desired file and double-click it.

For More Information

Building an XQuery Using the Mapper on page 813
Working with XQuery in Stylus Studio on page 781

Stylus Studio User Guide

1303

Stylus Studio GUI Reference

Keyboard Accelerators
This section lists and describes Stylus Studio keyboard accelerators and function keys for
the following:

File Commands on page 1304

General Commands on page 1304

Editing Commands on page 1305

Debugging Commands on page 1305

File Commands
Table 191. File Commands
Accelerator

Operation

Ctrl+N

Opens the Scenario Properties dialog box so that you can define
a new scenario.

Ctrl+O

Displays the Open dialog box. You can open any kind of document
that Stylus Studio handles.

Ctrl+S

Saves the active document.

General Commands
Table 192. General Commands

1304

Accelerator

Operation

Displays Stylus Studio Help.

Moves the cursor to the next bookmark.

Invokes the XSLT debugger and initiates XSLT processing. If there

are breakpoints, Stylus Studio suspends processing when it reaches
a breakpoint. If there are no breakpoints, and no errors, processing
completes.

F12

Displays the XSLT source pane.

Ctrl+F2

Inserts a bookmark.

Stylus Studio User Guide

Keyboard Accelerators
Table 192. General Commands
Accelerator

Operation

Shift+F2

Moves the cursor to the previous bookmark.

Ctrl+Shift+F2

Clears all bookmarks.

Editing Commands
Table 193. Editing Commands
Accelerator

Operation

Ctrl+A

Selects all text in the XML source view.

Ctrl+C

Copies selected text in the edit window and places it on the

Clipboard.

Ctrl+F

Displays the Find dialog box.

Ctrl+H

Replaces text.

Ctrl+V

Inserts the contents of the Clipboard at the cursor.

Ctrl+X

Removes selected text from the window in which you are editing
and places it on the Clipboard.

Ctrl+Y

Redoes the most recently undone action.

Ctrl+Z

Undoes the most recent action.

Finds the next occurrence of specified text.

Debugging Commands
Table 194. Debugging Commands
Accelerator

Operation

Inserts a breakpoint.

F10

Step over.

F11

Step into.

Stylus Studio User Guide

1305

Stylus Studio GUI Reference

Table 194. Debugging Commands

1306

Accelerator

Operation

Shift+F5

Stop debugging.

Shift+F11

Step out.

Stylus Studio User Guide

Lookup List

Lookup List
The Custom XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
You use the Lookup List dialog box to enter name:value pairs. When files are converted
to XML, Stylus Studio uses the information in the lookup list to translate a name (or code)
to a corresponding value. For example, you might have a lookup list that contains state
abbreviations and their full names, or error codes and the corresponding descriptions. You
can enter lookup list values manually, or by copy/pasting tab- and comma-separated text
files into the Lookup Value table in the Lookup List dialog box.

Fields
Lookup

The code used to look up the corresponding value.

Value

The value associated with the corresponding lookup.

Buttons
OK

Commits the lookup list to the custom XML conversion.

Cancel

Closes the Lookup List dialog box without committing any changes.
Copy

Copies the lookup list.

Paste

Pastes comma- and tab-separated text into the lookup list. Replaces existing content,
regardless of which row you have selected.
Append

Adds comma- and tab-separated text to the end of the lookup list. Existing lookup list
content is preserved.
Insert

Adds a new row to the lookup list.

Delete

Stylus Studio User Guide

1307

Stylus Studio GUI Reference

Removes the selected row from the lookup list.

For More Information

Using Lookup Lists on page 262
Controlling XML Output on page 255
The Custom XML Conversion Definition Editor on page 225
Converting Non-XML Files to XML on page 213

1308

Stylus Studio User Guide

Message Definition

Message Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Message Definition dialog box to add a message definition to the EDI
structure associated with your EDI to XML Conversion. The message definition resides
in the SEF file for your EDI to XML Conversion.

Fields
Message Name

The name you want to give to the message. Names are always created in upper case.
Description

The description associated with this message. This field is optional.

For More Information

Adding a Message on page 345
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

Stylus Studio User Guide

1309

Stylus Studio GUI Reference

Name
XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Name dialog box to specify the name of one of the following in a target
structure in the XQuery mapper:

Root element name

Element name

Attribute name
This dialog box appears when you

Add a new element or attribute directly to the target structure

Create a new element or attribute by mapping a source document element or attribute

to the target structure

Fields
Name

The Name field is empty if you are adding a new element or attribute to the target
structure. It contains the source document element or attribute name if you are
mapping a source document element or attribute to the target.

For More Information

Building an XQuery Using the Mapper on page 813
Modifying the Target Structure on page 823
Mapping Source and Target Document Nodes on page 824

1310

Stylus Studio User Guide

Named Template

Named Template
The Named Template dialog box displays the name and mode of the template you have
selected from the mapper canvas in the XSLT mapper.

Fields
Name

The template name.

Mode

The template mode. You can use a mode to define the conditions under which a
template will be applied by a stylesheet.

For More Information

Creating XSLT Using the XSLT Mapper on page 507

Stylus Studio User Guide

1311

Stylus Studio GUI Reference

Named/Matched Template
Use the Named Template or the Matched Template dialog box to create a new named or
matched template in an XSLT stylesheet. In addition to specifying the templates name
and mode, you can also define template parameters and their default values.

Fields
Name

The template name.

Mode

The template mode. You can use a mode to define the conditions under which a
template will be applied by a stylesheet.
Parameter List

A list box that displays the parameters, and their default values, associated with this
template.

How to Create a Parameter

To create a parameter
1.

Click the Add button.

The Name column becomes editable.

Type a parameter name and press Enter.

The Default Value field becomes editable.

Type a default value.

If you want to define another parameter, click ADD; otherwise, click OK to finish
creating the template.

For More Information

Creating XSLT Using the XSLT Mapper on page 507

1312

Stylus Studio User Guide

New Custom XML Conversion Definition

The Custom XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
You use the New Custom XML Conversion Definition dialog box to define a custom XML
conversion to convert non-XML files to XML. You can use the custom XML conversion
you define to convert a particular file (the file you use to define it), or to convert other files
that have the same properties as the input file.

Fields
1. Select an input file to be converted to XML

The file you want to use to convert to XML.

2. Specify the encoding

The type of encoding used by the input file. You can specify this manually, if you
know it, using The encoding is field, or you can let Stylus Studio determine the
encoding when it reads the file (this is the default).
3. Specify the general layout of the file

Whether the input file is line-oriented or fixed-width. You can choose one of these
settings, or you can let Stylus Studio determine the file layout when it reads the file
(this is the default).

For More Information

Choosing an Input File on page 222
Parts of an Input File on page 236
Converting Non-XML Files to XML on page 213

Stylus Studio User Guide

1313

Stylus Studio GUI Reference

New EDI to XML Conversion

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the New EDI to XML Conversion dialog box to create an EDI to XML Conversion
in Stylus Studio. To get started, you can

Use an existing EDI document and see how it differs from the EDI standard on which
it is based

Select an EDI standard and customize its definitions based on your organizations
proprietary EDI format
It is usually easier to start with an EDI document to understand where and how it differs
from the EDI standard on which it is based.

Fields
Select a sample EDI document

Use this field to specify the EDI document you want to use as the model for
customizing the EDI standard.
Select the dialect and version you need to customize

Use this field specify the dialect and version of the EDI standard you want to modify.
Dialect

The dialect of the EDI standard whose definitions you want to modify. This field is
grayed out if you choose to create the EDI to XML conversion using an EDI
document.
Version

The version of the EDI dialect whose definitions you want to modify. This field is
grayed out if you choose to create the EDI to XML conversion using an EDI
document.

For More Information

Creating an EDI to XML Conversion on page 320
Example: Converting a Conforming EDI File on page 323
Example: Converting a Non-conforming EDI File on page 326

1314

Stylus Studio User Guide

New EDI to XML Conversion

What is the EDI to XML Module? on page 316

Stylus Studio User Guide

1315

Stylus Studio GUI Reference

New Function
XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the New Function dialog box to create a user-defined function based on code that
you have selected in the XQuery text editor. This command prompt for a function name
and then copies the selection into the newly created local function, and replaces the
selection with the function call.

Fields
Enter the name for the new function

The Enter the name for the new function field contains a default name, udFunctionN,
where ud stands for user-defined and N is a unique number.
You can specify any valid name you choose.

For More Information

Creating a User-Defined Function on page 845
User-Defined Functions on page 844

1316

Stylus Studio User Guide

Notes

Notes
The Custom XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
You use the Notes dialog box in the Custom XML Conversion XML Editor to create notes
and comments for a given row. Notes are stored with the XML conversion and do not
affect converted XML.

For More Information

Data Type Properties (by data type) on page 290
The Custom XML Conversion Definition Editor on page 225
Converting Non-XML Files to XML on page 213

Stylus Studio User Guide

1317

Stylus Studio GUI Reference

Open and Save As

You use the Open dialog box to select the file you want to open, and to specify the Stylus
Studio editor in which you want to open it. You can also use this dialog box to open a nonXML file as an XML document using an XML converter, such as an XML converter
created using Stylus Studios Custom XML Conversion module.
Tip Click the down arrow on the Open button (

) to select an alternative editor when

opening a file.
Use the Save As dialog box to

Save a document that is the result of applying a stylesheet to an XML source

document.

Save a document under a new name.

Fields
Look in

Specifies the directory whose contents are currently displayed in the main field of the
dialog box. Click the down arrow to navigate to a different directory.
URL:

Displays the name of the file you select, or you can type the name.
Files of type:

Specifies which file types can appear in the main field of the dialog box. The default
is that Stylus Studio displays files with file name extensions of .dtd, .java, .xml, .xsd,
and .xsl. To change the file types Stylus Studio displays, click the down arrow and
select the filter you want. To allow display of any type of file, select All Files (*.*).
Open using XML Converter

Check if you want to open a non-XML file (such as a text, binary, or EDI file) using
an XML conversion, such as one you have created using Stylus Studios Custom
XML Conversion module. When you click the Open button, Stylus Studio displays a
dialog box from which you can select the XML conversion you want to use. See
Converting Non-XML Files to XML for more information on this topic.

Buttons
Click My Computer to open a file in your local file system or on a networked file
system.
1318

Stylus Studio User Guide

Open and Save As

Click WebDAV Server to open a file that is stored on a WebDAV server. WebDAV is
a protocol that allows programs to access a repository of files using HTTP commands,
enabling a web server to act as a file distribution and sharing point. You can use WebDAV
to read any file from any HTTP or HTTPS source, or to save a file to a web server that is
properly configured for write access.
Click FTP Server to open a file that is stored on an FTP server. FTP is a protocol that
allows two computers connected over the Internet to share files. In an FTP configuration,
one computer is configured as a server; the other is configured as a client.
Click TigerLogic XDMS to open a file that is stored on a TigerLogic XDMS database.
You will be prompted for authentication information.
Click Up to move up one level in the directory structure.
Click New Folder create a new directory in the directory you are viewing.
Click these buttons to toggle the display of the Name and Size headings in the main
field of the Open dialog box.

For More Information

Opening Files in Stylus Studio on page 92
Using Custom XML Conversion Definitions in Stylus Studio on page 266

Stylus Studio User Guide

1319

Stylus Studio GUI Reference

Options
The Options dialog box contains general and module-specific settings that allow you to
customize Stylus Studio defaults. Categories are organized by general application settings
and module-specific settings.
To get help on a specific category, select that category and press F1.

For More Information

Setting Module Options

1320

Stylus Studio User Guide

Options - Application Settings

The first page of the Options dialog box allows you to specify general options that apply
to all Stylus Studio applications.
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Fields
Automatically check for externally modified files

If there are files that are part of your XML application and they are modified outside
Stylus Studio while you are working on the application in Stylus Studio, Stylus Studio
prompts you to indicate whether you want to update the file in Stylus Studio.
Disable check on hidden files

Hidden files are files that are in the Stylus Studio project or the Other Documents
folder but not open in Stylus Studio windows. In some situations, it is useful to refresh
your open files after hidden files have been updated. In other situations, doing this is
unnecessary.
Automatically save modified files every nnn minutes

You can specify whether and how often you want Stylus Studio to automatically save
your open files.
Automatically create backup copy (*.bak) on save

Whether or not you want Stylus Studio to create a backup copy of your documents
when they are saved. Files saved to the Stylus Studio file system are saved with a
*.bak extension. Backup file names for files saved to other file systems (like Tiger
Logic XDMS, for example) are managed by the file system. The option to create
backup files is on by default.
Automatically add the Base Catalog to new projects

The Stylus Studio Base Catalog, which is bundled with every Stylus Studio
installation, is a collection of over one dozen popular catalogs that conform to the
OASIS catalog standard. By adding the Base Catalog to a project, any XML file in
the project that are associated with files inside the catalog (a schema or DTD, for
example) is validated against that catalog file.
Recent file lists

Specifies the number of files you want to display on File and Project menus. Changes
to these settings take effect the next time you start Stylus Studio.
Stylus Studio User Guide

1321

Stylus Studio GUI Reference

On File menu

The default is 4 files.

On Project menu

The default is 4 files.

Upon startup

Specifies the actions Stylus Studio takes when it is started:

Open last project

Stylus Studio automatically opens the project that was open the last time you
closed Stylus Studio.

Open last documents

Stylus Studio automatically opens any files that were open the last time you
closed Stylus Studio.
Check for newer versions

Specifies whether Stylus Studio automatically checks the Stylus Studio Web site to
determine if a newer version of Stylus Studio is available. If a newer version is
detected, Stylus Studio displays an animated button in its status bar. Click the button
to download the new version.

Check for final versions

Check for beta versions

User interface

User interface settings for Stylus Studio:

Use standard MDI windows

Displays multiple documents as individual windows which you can tile, cascade,
and so on.

Use tabbed MDI windows

Displays multiple documents as tabs that are displayed at the top of the editor
window. This is the default.

Display Help window always on top

Whether or not to display the Stylus Studio help window on top of the Stylus
Studio application.

For More Information

Specifying Stylus Studio Options on page 120

1322

Stylus Studio User Guide

Options General Back-mapping

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
Back-mapping allows you to click a line or an area of a document generated by applying
an XSLT stylesheet or XQuery and view the instruction responsible for generating that
part of the document. XSLT back-mapping also provides the ability to backmap from the
XSLT code stack. You can optionally backmap to the XML document to which the XSLT
or XQuery was applied.
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Fields
Back-mapping to the language (XSLT/XQuery) source on left mouse click

Indicates whether or not you want enable back-mapping to the XSLT/XQuery source
and, optionally, whether or not you want to require that the Shift, Ctrl, or both keys
be used with the mouse click action in order to invoke back-mapping:

Shift key must be pressed

The Shift key must be used with the left mouse click to invoke back-mapping.

Ctrl key must be pressed

The Ctrl key must be used with the left mouse click to invoke back-mapping.
Back-mapping to the data (XML) source on left mouse click

Indicates whether or not you want enable back-mapping to the XML source and,
optionally, whether or not you want to require that the Shift, Ctrl, or both keys be used
with the mouse click action in order to invoke back-mapping:

Shift key must be pressed

The Shift key must be used with the left mouse click to invoke back-mapping to
the XML source.

Ctrl key must be pressed

The Ctrl key must be used with the left mouse click to invoke back-mapping to
the XML source.

Stylus Studio User Guide

1323

Stylus Studio GUI Reference

Options General Components XML Converters

for Java
You use the Components page of the Options dialog box to manage licenses for
DataDirect XML Converters for Java. A copy of XML Converters is installed with
Stylus Studio, but you can use this feature to manage standalone installations of XML
Converters as well.

Fields
DataDirect XML Converters for Java Folder

This field displays the path of the folder in which XML Converters is installed. By
default, it points to the copy of XML Converters installed with Stylus Studio, but
you can use it to point to a standalone installation.
License Manager

This group box lists the existing licenses for the copy of XML Converters identified
in the DataDirect XML Converters for Java Folder field.

For More Information

How to Extend an Evaluation
How to Add a License
How to Remove a License
Managing Component Licenses
Integrated Components

1324

Stylus Studio User Guide

Options General Components XML Converters for .NET

Options General Components XML Converters

for .NET
You use the Components page of the Options dialog box to manage licenses for
DataDirect XML Converters for .NET. A copy of XML Converters is installed with
Stylus Studio, but you can use this feature to manage standalone installations of XML
Converters as well.

Fields
DataDirect XML Converters for .NET Folder

This group box lists the existing licenses for the copy of XML Converters identified
in the DataDirect XML Converters for .NET Folder field.

For More Information

How to Extend an Evaluation
How to Add a License
How to Remove a License
Managing Component Licenses
Integrated Components

Stylus Studio User Guide

1325

Stylus Studio GUI Reference

Options General Components DataDirect XQuery

You use the Components page of the Options dialog box to manage licenses for
DataDirect XQuery. A copy of DataDirect XQuery is installed with Stylus Studio, but you
can use this feature to manage standalone installations of DataDirect XQuery as well.

Fields
DataDirect XML Converters for XQuery Folder

This field displays the path of the folder in which DataDirect XQuery is installed. By
default, it points to the copy of DataDirect XQuery installed with Stylus Studio, but
you can use it to point to a standalone installation.
License Manager

This group box lists the existing licenses for the copy of DataDirect XQuery
identified in the DataDirect XML Converters for XQuery Folder field.

For More Information

How to Extend an Evaluation
How to Add a License
How to Remove a License
Managing Component Licenses
Integrated Components

1326

Stylus Studio User Guide

Options - General - Custom Document Wizards

Use the Custom Document Wizards page to specify information about a document wizard
that you define. After you define a custom document wizard here, Stylus Studio adds an
entry for your wizard to its Document Wizards dialog box. You can select your document
wizard from the Stylus Studio menu bar. Select File > Document Wizards and then your
wizard.
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Fields
Document type

From the drop-down menu, select the type of document that will be imported by
Stylus Studio. This is the output of your document wizard and it can be any of the
types listed in the Stylus Studio File > New menu. Required.
The value you specify here determines the Document Wizards tab on which the icon
for your application appears and the editor Stylus Studio uses to open the output file.
Icon bitmap

Specify the path for the file that contains the bitmap to be used as the icon in the
Document Wizards dialog box. If you do not specify a location, Stylus Studio
displays a default bitmap for your wizard. Click
to browse for the file you want
to specify or to insert the ${StylusDir} macro. This macro indicates that the path you
specify is relative to the Stylus Studio installation directory.
Command

Specify a command line template that Stylus Studio can use to generate the command
that starts your application. This should be the same as the command that starts your
application except that it has variables in place of actual arguments.
Click
to display a menu that provides shortcuts that help you specify the
command line. From this menu you can

Click Edit Arguments to specify arguments and their properties. After you define
an argument, its macro appears in this shortcut menu and you can select it.

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro to indicate that a path you specify is relative to the
Stylus Studio installation directory.

Insert the macro for an argument you already defined.

Stylus Studio User Guide

1327

Stylus Studio GUI Reference

It is often easier to define arguments and then specify the command line.
The variables must be in the form ${name}. For example:
${InputFile}
${OutputFile}
${LoggingOption}
${SomeArgument}

The variables can appear anywhere in the command. There must be a one-to-one
correspondence between these variables and the list of arguments that you specify for
the executable when you click Arguments.
This property is required. You must at least specify ${OutputFile} even if the
command line has no arguments. Stylus Studio generates the value for the
${OutputFile} argument, which is the name of the file that is opened in Stylus Studio.
For example:
java -cp my.jar com.exln.stylus.Import ${QuoteChar} ${InputFile} ${OutputFile}

This starts the specified Java class with a command line that includes the QuoteChar,
InputFile, and then OutputFile arguments. To specify properties for the QuoteChar
and InputFile arguments, click Arguments.
Initial directory

Specify the directory that you want Stylus Studio to set as the current directory when
starting your application. Click
to browse for the file you want to specify or to
insert the ${StylusDir} macro. This macro indicates that the path you specify is
relative to the Stylus Studio installation directory.
Path

Define any paths required to execute your application. You do not need to specify
paths that are already in your PATH environment variable. If you specify more than one
path, separate them with semicolons. Click
to display a menu that provides
shortcuts that help you specify the PATH field. From this menu you can

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro to indicate that a path you specify is relative to the
Stylus Studio installation directory.

Insert the ${PATH} macro to specify your PATH environment variable.

Trace execution

Boolean value that indicates whether you want Stylus Studio to display tracing
information about the selection and execution of the document wizard in the Output
Window. This is meant to be used during the development of the custom document

1328

Stylus Studio User Guide

Options - General - Custom Document Wizards

wizard and not during normal use of the wizard. This is an optional property. By
default, it is false.

Buttons
Arguments

Specify any arguments required by your document wizard.

Define a new custom document wizard. Stylus Studio displays a field for the new
wizards name. Specify the text that you want to appear below the custom document
wizards icon in Stylus Studios Document Wizards dialog box. For example, Proprietary
to XML.
Delete the selected custom document wizard.
Move the selected custom document wizard one place up in the list of custom
document wizards. The order of the wizards here determines the order of the selections in
the Stylus Studio Document Wizards dialog box.
Move the selected custom document wizard one place down in the list of custom
tools.
Displays a pop-up list of alternatives that help you specify the corresponding field.

For More Information

Custom Document Wizards on page 1176

Stylus Studio User Guide

1329

Stylus Studio GUI Reference

Options - General - Custom Tools

Use the Custom Tools page to register alternative editors, processors, preprocessors, or
postprocessors. For example, you can register a custom tool that configures Internet
Explorer to display the document you are working on.
After you register a tool here, Stylus Studio adds an entry for it to the Stylus Studio Tools
menu.
Tip You can also register custom tools from the command line. See Registering Custom Tools

on page 122.

Fields
Command

Specify or select the absolute path of the command that starts your tool. This can be
a .exe, .bat, or .cmd file.
Arguments

Specify any arguments required by your tool. For typical arguments, such as path,
directory, name, extension, or classpath, click .
Initial directory

Specify the directory that you want Stylus Studio to use to find any files needed to
start your process.
Path

Define any paths required to execute your tool. You do not need to specify paths that
are already in your PATH environment variable.
Prompt for arguments

If you specify any arguments here, then after you select your custom tool from the
Stylus Studio Tools menu, Stylus Studio displays a dialog box that prompts for the
arguments.
Use Output Window

When selected, Stylus Studio displays output from your custom tool in the Stylus
Studio Output Window.
Save All documents before execution

Prompts Stylus Studio to save all open documents before running this tool.

1330

Stylus Studio User Guide

Options - General - Custom Tools

Buttons
Define a new custom tool.
Delete the selected custom tool.
Move the selected custom tool one place up in the list of custom tools. The order of
the tools here determines the order of the selections in the Stylus Studio Tools menu.
Move the selected custom tool one place down in the list of custom tools.
Browse the file system.
Display a pop-up list of variables.

For More Information

Specifying Stylus Studio Options on page 120

Stylus Studio User Guide

1331

Stylus Studio GUI Reference

Options - General - Custom Validation Engines

You use this page of the Options dialog box to specify settings for validation engines you
want Stylus Studio to use. You can also use this page to create a custom validation engine.
Custom validation engines that you add to Stylus Studio are displayed on the Validate
Document drop-down list in the XML Schema editor.

Fields
Command

Specify or select the absolute path of the command that starts the validation engine.
This can be a .exe, .bat, or .cmd file.
Arguments

Specify any arguments required by your validation engine. For typical arguments,
such as path, directory, name, extension, or classpath, click
.
Initial directory

Specify the directory that you want Stylus Studio to use to find any files needed to
start your process.
Path

Define any paths required to execute the validation engine. You do not need to specify
paths that are already in your PATH environment variable.
Classpath

You use the Classpath field to specify the required classpath for the custom validation
engine.
To enter a classpath, type the value or click Browse to the right of the field.
Prompt for arguments

If you specify any arguments here, then after you select the validation engine from the
Validate Document drop-down list, Stylus Studio displays a dialog box that prompts
for the arguments.
Supports Validation of XML

Whether or not the custom validation engine supports validation of XML.

Supports Validation of XML Schema

Whether or not the custom validation engine supports validation of XML Schema.

1332

Stylus Studio User Guide

Options - General - Custom Validation Engines

Buttons
Define a new custom validation engine.
Delete the selected validation engine.
Move the selected validation engine one place up in the list of custom validation
engines. The order of the validation engines here determines the order of the selections in
the Validate Document drop-down list.
Move the selected validation engine one place down in the list of validation engines.
Browse the file system.
Display a pop-up list of variables.

For More Information

Custom XML Validation Engines on page 1170
Registering a Custom Validation Engine on page 1170
Configuring a Custom Validation Engine on page 1171

Stylus Studio User Guide

1333

Stylus Studio GUI Reference

Options - General - Editor Format

Specify the editor for which you want to set options. Options take effect as soon as you
click OK.
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Fields
Editor

Click the down arrow to select the editor for which you want to specify options (Java,
XML, or XSLT).
Default Font

Click the down arrow to display a list of fonts. Stylus Studio uses the font you select
to display text in the specified editor.
Size

Click the down arrow and click the font size you want for the selected editor.
Colors

Click a component in the left field, and then click the color you want it to have in the
selected editor display.
Sample

Shows you how the selected font, size, and color appear.

Buttons
Other

Displays an expanded palette of colors and allows you to define custom colors.
Reset All

Returns the options for the specified editor back to their default values.

For More Information

Specifying Stylus Studio Options on page 120

1334

Stylus Studio User Guide

Options - General - Editor General

Specify the editor for which you want to set options. Options take effect as soon as you
click OK.
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Fields
Editor

Click the down arrow to determine whether you are specifying options for the Java,
XML, or XSLT editor.
Newline format

Allows you to choose the newline format for documents you open in Stylus Studio:

Preserve Original (the default)

Windows

UNIX

MacIntosh
Show line numbers

Displays line numbers at the beginning of every line in the editor display.
Line wrap

Stylus Studio automatically wraps lines whose length exceeds 16k characters. You
can turn off this option by selecting Disabled from the Line wrap drop-down list. You
can override this option for individual documents by selecting Edit > Wrap Lines from
the Stylus Studio menu, or by clicking the wrap lines button on the tool bar ( ).
Enable spell checking

Whether or not you want the Spell Checker enabled for this editor. This option is off
by default. The Spell Checker can be run manually from the menu (Tools > Check
Spelling), regardless of how the Enable spell checking option is set.
Word delimiters

Characters you want the Stylus Studio editor to recognize as word delimiters.
Indenter Settings
Preserve trailing/leading whitespace

Stylus Studio User Guide

1335

Stylus Studio GUI Reference

When checked, this indicates that Stylus Studio preserves (does not trim) white space
that is at the beginning or end of a text node.
Preserve newlines between elements

When checked, this indicates that Stylus Studio preserves (does not remove) new line
characters that are in white space.
Wrap attributes if they exceed column

Instructs Stylus Studio to display the attribute on a new line if it starts after the
specified column. The default column is 256.
Tab Settings
Keep Tabs

Whether you want to keep the tabs in a document or replace tabs with the number of
spaces indicated in the Tab Size field.
Insert Spaces

Whether you want to use spaces instead of tabs. (The number of spaces is specified
using the Tab Size field.)
Tab Size

Indicates the number of spaces in a tab.

Do not add "Created with Stylus Studio" comment at the end of a document

Check this box if you want the comment at the end of documents created with the
selected editor.

For More Information

Specifying Stylus Studio Options on page 120
Using the Spell Checker on page 151
Text Editing Features on page 144

1336

Stylus Studio User Guide

Options - General - Editor Sense:X

You use this page of the Options dialog box to control settings for Sense:X, the Stylus
Studio context-sensitive edit control. Most Sense:X features require that an XML Schema
be associated with the XML document you are editing.

Fields
Sense:X
Sense:X enabled

Click the check box to determine whether Sense:X completion is enabled. If this is
not checked, Stylus Studio does not display pop-up menus that list the possible
elements or attributes that you can create at particular locations.
Automatically insert attribute value

Click the check box to determine whether Stylus Studio automatically inserts
attribute values. Stylus Studio uses this setting when you choose an attribute from the
Sense:X list. When this is checked, Stylus Studio inserts attribute_name=". When
this is not checked, Stylus Studio inserts attribute_name.
Auto-close open tag when typing '</'

As soon as you type </, Stylus Studio completes the tag with the nearest previous
open tag name.
Add closing tag when creating new tag

As soon as you type a new tag, Stylus Studio inserts its closing tag. For example, if
you type <newtag>, Stylus Studio immediately inserts </newtag>.
Dropdown Delay

Specify how long Stylus Studio waits before it displays drop-down lists.
XML Generations

In addition to auto-complete for element names, Sense:X can generate an entire XML
subtree based for a given element. As you type, Stylus Studio displays a drop-down
list with valid choices based on the current context.

Stylus Studio User Guide

1337

Stylus Studio GUI Reference

The first item for a given element (authors, for example) represents the element tag;
the second item for the same element represents the entire subtree for that element.
You use this option to choose whether

To display the generated XML in the drop-down. If generated XML is displayed,

you can add it to you XML document by simply selecting it from the list and
pressing Enter. As suggested by the previous illustration, including generated
XML in the drop-down list can create dense lists. Omitting their display can make
it easier to edit your XML.

To omit the generated XML from the drop-down. You can still add generated
XML to your document when this option is selected by pressing the Ctrl key
when selecting the element from the drop-down list.
Maximum XML Depth

The depth of an XML elements subtrees you want to include when using automatic
XML generation.
Repeating Elements

The number of repeating elements you want to include when using automatic XML
generation.

Preferred This value is used if it is between the minOccurs and maxOccurs values
defined in the associated XML Schema. The default preferred recursion value is

Maximum This value is used when Preferred is less than minOccurs or greater
than maxOccurs and Maximum is less than maxOccurs.
Number of Repeating Elements

You use the Number of Repeating Elements fields to control the number of repeating
elements Stylus Studio generates in an XML document based on an XML Schema.
Preferred The number of repeating elements you would like Stylus Studio to
generate. This number is used when its value falls between the minOccurs and
maxOccurs values defined for the element in the XML Schema. If this number is less
than the minOccurs value, the minOccurs number of elements is generated, ensuring
that the resulting document is valid. If this number is greater than the maxcOccurs
value, the maxOccurs number of elements.
Maximum This value is used when the Preferred value is out of the range of the
minOccurs and maxOccurs values (less than minOccurs or greater than maxOccurs), and
Maximum is less than maxOccurs.
Optional Elements and Attributes

Whether or not you want to generate optional elements and attributes specified in the
XML Schema, and whether or not you want to generate comments.
1338

Stylus Studio User Guide

Options - General - Editor Sense:X

Choices and Substitution Groups

By default, Stylus Studio generates all choices and substitutions specified in the XML
Schema, commenting (//) all but the first one to ensure that the generated XML
document is valid. If you prefer, you can generate

All choices and substitutions, without comments. This will result in an invalid
XML document

Only the first choice and substitution specified in a group

For More Information

Using the Text Editor
Updating an XML Document Getting Started
Creating XML Documents
Specifying Stylus Studio Options

Stylus Studio User Guide

1339

Stylus Studio GUI Reference

Options - General - File Types

You use the File Types page of the Options dialog box to

Change the setting that makes Stylus Studio the default editor for Stylus Studio file
types (.xml, .conv, .prj, and so on) opened outside of Stylus Studio (as from a file
browser like Windows Explorer, for example)

Associate new file types with Stylus Studio and, optionally, make Stylus Studio the
default editor
To display the Options dialog box, select Tools > Options from the Stylus Studio menu
bar.

Buttons
Add

Click the Add button to make the Type field editable. You can also double-click the
Type field to make it editable.
Delete

Click the Delete button to delete a file type from the File Type page.

Fields
Type

The extension of the type of file associated with Stylus Studio.

Whether or not you want the Spell Checker to skip capitalized words like Boston Red
Sox and Moto Guzzi.
Mixed-Case words?

Whether or not you want the Spell Checker to skip mixed-case words like DataDirect.
Uppercase words?

Whether or not you want the Spell Checker to skip upper case words like BMW and
USDA.
Words with embedded digits?

Whether or not you want the Spell Checker to skip words with embedded digits like
W3C and R1150RS.
E-mail and URIs?

Whether or not you want the Spell Checker to skip e-mail addresses and URIs like
[email protected].
Words with n or fewer characters?

Whether or not you want the Spell Checker to skip words that have the same or fewer
characters as the value you specify.
Ignore case?

Whether or not you want the Spell Checker to ignore case for spelling purposes. If
this field is checked, BMW and bmw are considered equivalent, for example.
Ignore accents?

Whether or not you want the Spell Checker to ignore accents for spelling purposes. If
this field is checked, mme and meme are considered equivalent, for example.
Highlight repeated words?

Stylus Studio User Guide

1343

Stylus Studio GUI Reference

Whether or not you want the Spell Checker to highlight doubled (repeated) words. If
this field is checked, the second word in the pair of repeated words is highlighted.
Performance

Allows you to adjust the Spell Checker for speed versus quantity of suggested
alternatives to misspellings.
Keyboard Layout

The type of keyboard you are using. Stylus Studio uses this setting to check for
typographical errors as you type.

For More Information

Using the Spell Checker

1344

Stylus Studio User Guide

Options - Module Settings - EDI to XML - EDI Viewer Settings

Options - Module Settings - EDI to XML - EDI Viewer

Settings
The EDI to XML module is available only in Stylus Studio XML Enterprise Suite.
You use the EDI Viewer page of the Options dialog box to modify the default settings
Stylus Studio uses to manage display and refresh characteristics of the EDI document
pane.

Fields
Delay before refreshing the EDI viewer after a change

When you make a change to either the converter:EDI URI or the EDI structure, Stylus
Studio refreshes and reparses the EDI source document specified in the EDI to XML
scenario. This field controls the number of seconds to wait after the last detected
change before refreshing the document.
Background color for mismatched dialect

The background color to use when the EDI dialect specified in the document does not
agree with the dialect specified in the EDI to XML Conversions editor.
Background color for mismatched version

The background color to use when the EDI version specified in the document does
not agree with the version specified in the EDI to XML Conversions editor.

For More Information

Correcting Dialect and Version Errors on page 335
Displaying Information about Errors on page 334
Quick Fixes on page 335
Resolving EDI Document Errors on page 332
The EDI to XML Editor on page 317

Stylus Studio User Guide

1345

Stylus Studio GUI Reference

Options - Module Settings - Java - Debugger

You use this page of the Options dialog box to modify settings that determine how Stylus
Studio debugs your Java files.
To display the Debugger page of the Options dialog box, select Tools > Options from the
Stylus Studio menu, then select Module Settings > Java > Debugger.

Fields
Source Path

Location for the source files you want to debug.

Prompt user for source file path confirmation

If Stylus Studio cannot find the source files, indicate if you want to be prompted to
specify the source file location.
Never step into classes starting with one of the following strings of characters

List of classes, one on each line, that you do not want to step into.
JVM communication time out

Number of seconds Stylus Studio waits for a response from the JVM. The default is 5.
Show JDWP Events in the Output Window

Displays communication events in the Stylus Studio Output Window.

1346

Stylus Studio User Guide

Options - Module Settings - WSDL Editor - WSDL Details

Options - Module Settings - WSDL Editor - WSDL

Details
The WSDL Editor is available only in Stylus Studio XML Enterprise Suite.
You use the WSDL Details page of the Options dialog box to specify which properties of
a WSDLs nodes you want to display in the WSDL Editor diagram. Settings you choose
here affect every instance of the WSDL Editor, though you can override these settings for
individual WSDL documents (Diagram > Properties).
For each type of node (message, binding, and so on) and for a nodes individual properties
(name, type, and so on), you use the Inline visibility in diagram settings to

Show the property and its value

Show the property only if it is not empty (that is, undefined)

Hide the nodes properties

In order to streamline presentation of the WSDL in the diagram, most properties are
hidden by default.
Note You set node display properties for any XML Schema included in the WSDL definition
separately, using the Schema Details page.

Figure 594. Show all properties

Stylus Studio User Guide

1347

Stylus Studio GUI Reference

Show if not empty setting. Only those values for the port element that have been explicitly

set are displayed in the diagram. (In this example, notice that the Address property is no
longer displayed.)

Figure 595. Show if not empty setting

Hide setting. If you choose this setting, none of the elements properties is displayed in

the diagram.

Figure 596. Hide setting

Fields
Category/Property

The node and, optionally, properties whose inline visibility settings you want to
change.
Inline visibility in diagram

The conditions under which you want to display a property and its values in the
WSDL diagram. Inline visibility options are:

Hide The property and its value are always hidden. This is the default for most
elements.

Show The property and its value are always displayed, even if the property does
not have a value.

have different show/hide settings.

1348

Stylus Studio User Guide

Options - Module Settings - WSDL Editor - WSDL Details

For More Information

Working with WSDL Elements
Using the WSDL Editor

Stylus Studio User Guide

1349

Stylus Studio GUI Reference

Options - Module Settings - XML Diff - Engine

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Engine page of the Options dialog box to change default settings that affect
how Stylus Studio diffs XML files.
Note The settings on this page do not affect how Stylus Studio diffs folders.

Fields
General

The fields in the General group box affect when the Stylus Studio diffing engine runs
and basic document handling behavior.

Automatically expand all diffs By default, Stylus Studio collapses the display
of the diffed documents. If you select this option, all nodes containing diffs are
expanded automatically when the diff is run.

Collapse unchanged blocks By default, Stylus Studio collapses any block that
does not contain any changes to save space in the XML Diff Viewer window. You
might prefer to have the entire document structure visible, to provide context for
changed nodes, for example.

Autorun diff By default, Stylus Studio runs the diff operation if you make a
change to one of the settings on the Engine page of the Options dialog box, or if
you add a new source document or change the current target document. You can
also specify that the diff should be calculated automatically whenever a source or
target file changes if you select If files modified, Stylus Studio runs the diff
operation when it detects changes to a source or target document.
Engine Options

The fields in the Engine Options group box affect how Stylus Studio diffs files.

Use URI to compare namespaces Controls whether or not URIs are used when
comparing namespaces in source and target documents.

Expand entity references Controls whether or not entity references, which in

some cases can include files external to the source or target document, are
expanded by the Stylus Studio diff engine.

Ignore text formatting characters Controls whether or not text formatting

characters are used when comparing source and target documents. This option is
off by default.
1350

Stylus Studio User Guide

Options - Module Settings - XML Diff - Engine

Show differences in Provides granular control of what components of an XML

document are diffed. There are separate controls for comments, text, entities,
attributes, entity references, and processing instructions.
Performance

Diffing large, numerous, or complex documents can be time-consuming. Stylus Studio

provides controls that let you choose between algorithm tunings that have been optimized
for time and thoroughness.

Autodetect Stylus Studio determines which algorithm tuning to use based on

the number, content, complexity, and size of the source and target documents.
Stylus Studio first tries to use the tuning that is optimized for change description;
if it determines that processing resources are limited, it reverts to the algorithm
tuning optimized for speed. This setting is on by default.

Optimize change description Provides the most economical set of changes

possible. This calculation, though it yields the best results, can be costly in terms
of time and processing resources.

Optimize calculation time Provides the set of changes in the shortest time
possible.

Optimize for large documents with few changes Helps speed the diffing of
large (greater than 1MB) documents by folding similar blocks before comparing
nodes. This setting can be used in conjunction with any of the algorithm tuning
settings and is on by default.

How Options are Related to the Menu and the Tool Bar
Settings on the Engine Options page of the Options dialog box affect the default settings
for both the XML Diff menu and tool bar in the XML Diff editor. You can override settings
on the Engine Options page using the menu or the tool bar. To permanently change a
setting, however, make the change on the Engine Options page.

For More Information

Specifying Stylus Studio Options on page 120
Diffing Folders and XML Documents on page 176

Stylus Studio User Guide

1351

Stylus Studio GUI Reference

Options - Module Settings - XML Diff - Presentation

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Presentation page of the Options dialog box to modify the default settings
Stylus Studio uses for the background color to display added, removed, changed, and
collapsed items in the XML Diff editor and the Diff Folders dialog box.

Fields
Added items

Items that appear in the target document but not in the source document.
Removed items

Items that appear in the source document but are not present in the target document.
Changed items

Items that differ in the source and target documents (the text of a node differs, for
example).
Collapsed items with changes

Indicates that there are changes within an item (such as a folder or a node) that is
currently displayed as collapsed. The precise nature of the change becomes visible
once the item is expanded.

Default Colors
Stylus Studio uses these colors by default:
Table 195. Default Colors Used for Diffing Files and Folders

1352

Color

Identifies

Light green

Added items

Light red

Removed items

Light yellow

Change items

Light gray

Collapsed items with now changes

Stylus Studio User Guide

Options - Module Settings - XML Diff - Presentation

Changing Colors
To change the default colors:
1.

Click the button to the right of the Background Color field (

want to change.
Stylus Studio displays the Color dialog box.

Select a color from the Basic colors grid.

Alternative:
a.

Click in the spectrum.

Use the mouse and slide bar to select a different color.

) for the color you

When the color you want appears in the Color|Solid field, click the Add to
Custom Colors button.

The color appears in the Custom Colors grid.

Select the color from the Custom Colors grid.

Click OK to close the Color dialog box.

Click OK to close the Options dialog box.

For More Information

Specifying Stylus Studio Options on page 120
Diffing Folders and XML Documents on page 176

Stylus Studio User Guide

1353

Stylus Studio GUI Reference

Options - Module Settings - XML Editor - XML Settings

To display the Options dialog box, select Tools > Options from the Stylus Studio menu,
then select Module Settings > XML Editor > XML Settings.

Fields
Sense:X Refresh Interval

Use this dialog box to specify the refresh interval for Sense:X. The default is 10
seconds.
As you edit an XML document, Stylus Studio displays a pop-up menu that lists the
elements and element attributes you can create. Stylus Studio retrieves this
information from the documents schema. The schema can be either at the beginning
of the document, or it can be an external file.
If your document does not have a schema, Stylus Studio does not display the pop-up
list of suggestions.
The information needed for the pop-up menu can change because you edit the internal
DTD or because someone has modified the external schema. When this information
changes, you want to refresh the set of elements and attributes that Stylus Studio
suggests.
The refresh interval is how often you want Stylus Studio to reparse schema data. A
smaller interval means that the data used is more accurate and up to date, but it
requires more CPU processing time. A longer interval means data might be less
accurate and less up to date, but it requires less CPU processing time.
Halt Validation After nnn Errors

Specify the maximum number of errors Stylus Studio can find before it stops trying
to validate an XML document. The default is 50.
Display message box after validation

Whether or not to display a message box after validation is complete. Validation

information is also displayed in the output window.

For More Information

Specifying Stylus Studio Options on page 120

1354

Stylus Studio User Guide

Options - Module Settings - XML Schema Editor - Schema Details

Options - Module Settings - XML Schema Editor Schema Details

You use the Schema Details page of the Options dialog box to specify which properties
of an XML Schemas nodes you want to display in the Diagram tab of the XML Schema
Editor. Settings you choose here affect every instance of the XML Schema Editor, though
you can override these settings for individual XML Schema documents (Diagram >
Properties).
For each type of node (elements, complexTypes, and so on) and for a nodes individual
properties (name, type, and so on), you use the Inline visibility in diagram settings to

Show the property and its value

Show the property only if it is not empty

Hide the nodes properties

In order to streamline presentation of the XML Schema in the diagram, most properties
are hidden by default.
Note You set node display properties for WSDL elements separately, using the WSDL Details

page.

Figure 597. Hide setting

Stylus Studio User Guide

1355

Stylus Studio GUI Reference

Show setting. Notice that even properties that do not have a value defined for them are

displayed:

Figure 598. Show setting

Show if not empty setting. Only those values for the Mode element that have been
explicitly set are displayed in the diagram:

Figure 599. Show if not empty setting

Fields
Category/Property

The node and, optionally, properties whose inline visibility settings you want to
change.
Inline visibility in diagram

The conditions under which you want to display a property and its values in the XML
Schema diagram. Inline visibility options are:

Hide The property and its value is always hidden. This is the default.

Show The property and its value is always displayed, even if the property does
not have a value.

1356

Stylus Studio User Guide

Options - Module Settings - XML Schema Editor - Schema Details

have different show/hide settings.

For More Information

Introduction to the XML Schema Editor Diagram Tab
Defining an XML Schema Using the Diagram Tab Getting Started

Stylus Studio User Guide

1357

Stylus Studio GUI Reference

Options - Module Settings - XML Schema Editor Documentation

The XSD Documentation tab is available only in Stylus Studio XML Enterprise
Suite and Stylus Studio XML Professional Suite.
You use the Documentation page of the Options dialog box to specify the layout and
contents of the XML Schema documentation displayed on the Documentation tab of the
XML Schema Editor.

Fields
XML Schema Documentation Options
Settings that control display and print content and format:
baseURL

The base URL used to resolve links in the XML Schema.

base_IMG_URL

The base URL used to resolve diagrams in the XML Schema documentation.
DEFAULT_DOCUMENT_EXT

The extension you want to use for the saved XML Schema documentation. The
default is .html.
externalCSSURL

The external CSS stylesheet used to render the XML Schema documentation. If no
value is specified, Stylus Studio uses internally-declared CSS properties.
linksFile

URL of an XML document that maps the XML Schema's URL to the related
documentation URL for imported and included schemas.
printAllSubTypes

Controls which sub-types are displayed in the XML Schema documentation.

True All sub-types that appear in the XML Instance Representation tables in the
XML Schema documentation are displayed.

False Only direct sub-types are displayed.

printAllSuperTypes

Controls which super-types are displayed in the XML Schema documentation.

1358

Stylus Studio User Guide

Options - Module Settings - XML Schema Editor - Documentation

True All super-types that appear in the XML Instance Representation tables in

the XML Schema report are displayed.

False Only direct super-types are displayed.

printDiagram

True Displays/ schema diagrams in the XML Schema documentation.

False Does not display schema diagrams in the XML Schema documentation.

print Glossary

True Displays the XML Schema documentations Glossary.

False Does not display the XML Schema documentations Glossary.

You can hide the Glossary by clicking the Printer-friendly Version check box.

Tip

printLegend

True Displays the XML Schema documentations Legend.

False Does not display the XML Schema documentations Legend.

You can hide the Legend by clicking the Printer-friendly Version check box.

Tip

printNSPrefixes

True Displays the prefix that matches the namespace of schema components in
XML Instance Representation tables.
False Prefixes of matching namespaces are not displayed.

searchImportedSchemas

True imported schemas are searched for schema components when generating
links and XML Instance Representation tables.
False imported schemas are not searched.

searchIncludedSchemas

True included schemas are searched for schema components when generating

links and XML Instance Representation tables.

False included schemas are not searched.

sortByComponent

Determines how report content is sorted:

True Sorts the top-level schema components by type, then name.

False Displays the components in the order in which they appear in the schema.
title

Stylus Studio User Guide

1359

Stylus Studio GUI Reference

The title of the XML Schema documentation. The default, which is not displayed in
the Options dialog box, is XML Schema Documentation.
useJavaScript

Some Internet browsers do not support JavaScript. This option allows you to specify
whether you want Stylus Studio to generate the XML Schema documentation as plain
HTML or as HTML plus JavaScript.

Description
Displays a description of the currently selected option.

For More Information

Generating Documentation for XML Schema
Printing XML Schema Documentation

1360

Stylus Studio User Guide

Options - Module Settings - XML Schema Editor - XML Schema to XML

Options - Module Settings - XML Schema Editor - XML

Schema to XML
You use the XML Schema to XML page of the Options dialog box specify settings that
affect how Stylus Studio creates an XML document from an XML Schema. Stylus Studio
uses these settings when you

Run the XML Schema to XML document wizard

View an XML Schema node in the XML Schema diagram as XML

Fields
Preferred recursion depth

The level to which you want self-referencing elements in the XML document to
recurse.
Number of elements that triggers a warning

Use this field to set a soft limit on the number of elements Stylus Studio generates.
When this limit is reached, Stylus Studio displays a warning message. You can
continue generating XML, or cancel the generation operation at this time.
Number of Repeating Elements

Whether or not you want to generate optional elements and attributes specified in the
XML Schema, and whether or not you want to generate comments.
Choices and Substitution Groups

Stylus Studio User Guide

1361

Stylus Studio GUI Reference

All choices and substitutions, without comments. This will result in an invalid
XML document

Only the first choice and substitution specified in a group

1362

Stylus Studio User Guide

Options - Module Settings - XQuery - Mapper

To display the Options dialog box, select Tools > Options from the Stylus Studio menu,
then select Module Settings > XQuery > Mapper.

Fields
Display predicates in XPath expressions in the canvas

This option allows you to display XQuery predicates in XPath expressions as blocks
on the XQuery canvas. This allows you to manage predicate expressions graphically.

For More Information

Predicate Blocks
Building an XQuery Using the Mapper

Stylus Studio User Guide

1363

Stylus Studio GUI Reference

Options - Module Settings - XQuery - XQuery Settings

You use the XQuery Settings page of the Options dialog box to indicate whether or not
you want to save XQuery scenario meta-information with the XQuery.

For More Information

Creating an XQuery Scenario
Getting Started with XQuery in Stylus Studio

1364

Stylus Studio User Guide

Options - Module Settings - XSLT Editor - Mapper

To display the Options dialog box, select Tools > Options from the Stylus Studio menu,
then select Module Settings > XSLT Editor > Mapper.

Fields
Render xsl:for-each as a line instead of as a block

This option allows you to render xsl:for-each statements as lines instead of as blocks
to simplify your XSLT diagrams appearance.
Create an empty element for each unlinked node that is required by the associated
schema

Check this box if you want Stylus Studio to create empty elements for nodes in the
source document that are not mapped to nodes in the destination document. Stylus
Studio does this only for nodes that are specified as required by the schema associated
with the source document.

For More Information

Overview of the XSLT Mapper on page 508
Steps for Mapping XML to XML on page 515

Stylus Studio User Guide

1365

Stylus Studio GUI Reference

Options - Module Settings - XSLT Editor - XSLT Settings

You use the XSLT Settings page of the Options dialog box to specify general preferences
for working with XSLT scenarios and settings for XSLT debugging.
To display the XSLT Settings page of the Options dialog box, select Tools > Options from
the Stylus Studio menu, then select Module Settings > XSLT Editor > XSLT Settings.

Fields
General
Show Scenario Dialog When On New Document

Check this box if you want Stylus Studio to automatically display the Scenarios
Properties dialog box when you create a new XSLT document.
Save Scenario Meta-Information In The Stylesheet

If you do not save metainformation in the stylesheet, Stylus Studio saves it in the .prj
file for the project the scenario belongs to. If a stylesheet does not belong to a project
and you do not save metainformation in the stylesheet, the information is not saved.
If this is a mapping stylesheet, and you set this option, Stylus Studio also saves
mapping metainformation in the stylesheet. If this option is not set, and the mapping
stylesheet belongs to a project, Stylus Studio saves the mapping metainformation in
the project. If this option is not set, and if the mapping stylesheet does not belong to
a project, Stylus Studio does not save mapping metainformation.
Saving metainformation in a stylesheet is useful because it frees you from having to
re-enter information when you open the stylesheet. However, you might not want a
block of metainformation in your stylesheet, or you might not want to expose path
information in your stylesheet.
Do Not Add Created with Stylus Studio comment at the end of a document

Check this box if you want Stylus Studio to automatically add the Create with Stylus
Studio signature at the end of each new XSLT document.
Debugging
Truncate summaries of debug variable values in Watch and Variables windows to:

The number of characters to which you want to truncate summaries of debug variable
values in Watch and Variable windows that are displayed during debugging. The
default value is 100 characters.

1366

Stylus Studio User Guide

Options - Module Settings - XSLT Editor - XSLT Settings

For More Information

Specifying Stylus Studio Options on page 120

Stylus Studio User Guide

1367

Stylus Studio GUI Reference

Output Window
The Output Window displays any output from the Java virtual machine. To display the
Output Window, click Output Window
in the Stylus Studio tool bar.

For More Information

Debugging Stylesheets

1368

Stylus Studio User Guide

Personal Dictionary Editor

The Spell Checker is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Personal Dictionary Editor dialog box to maintain the personal dictionary
used by the Stylus Studio Spell Checker. The personal dictionary consists of words you
add to the standard Spell Checker dictionary, and it is associated with all documents you
edit in Stylus Studio.
You can use the Personal Dictionary Editor dialog box to

Add words to the personal dictionary

Import word lists

Export the words you have added to the dictionary

Fields
New Word

Entry field in which you enter the word you want to add to the personal dictionary.
Words in Personal Dictionary

List box that displays the words in the personal dictionary.

Buttons
Add

Adds the word in the entry field to the personal dictionary.

Import

Imports words from the .txt file you specify.

Note

Words in the file you wish to import into the personal dictionary must be in a single
column they cannot be tab- or comma-separated.
Export

Exports the words in the personal dictionary to a .txt file.

Closes the Personal Dictionary Editor dialog box.

Stylus Studio User Guide

1369

Stylus Studio GUI Reference

For More Information

Using the Spell Checker

1370

Stylus Studio User Guide

Preview Window

Preview Window
Stylus Studio uses the Preview window to display processing results for

XQuery

XSLT

XML Pipelines

XML Reports

EDI to XML Conversions

Web Service Call Composer

XML Converters and custom XML conversions

For example, if you use the EDI to XML Conversions editor to create an EDI to XML
conversion, when you click the Preview Result button ( ), the XML document created
by converting the source EDI document to XML is displayed here. The Preview window
opens automatically when you preview a result, but you can open it manually by selecting
View > Preview from the Stylus Studio menu.

Back-mapping
You can click output in the Preview window, and Stylus Studio places the cursor in the
line of code in the editor responsible for creating it. For example, if you click a node in an
XML document created using an XML conversion, Stylus Studio places the cursor in the
field and row of the input file displayed in the Custom XML Conversion Editors schema
pane. Back-mapping is supported in the Preview windows Tree and Text views.
The Preview window displays a tab at the bottom for each scenario in which you have
applied a stylesheet or XQuery. Click the tab to view the most recent result for that
scenario.

Buttons
Refresh Preview performs the processing again. You might want to use this button to
quickly see the effect of changes you make to the source document.
Preview in Tree displays the result using a tree representation. Tree view is available
for XML documents only. Back-mapping is available from the Tree view.
Preview in Browser displays the result as it would appear in a Web browser. Backmapping is available only for output in HTML (such as that which might result from
processing an XML document with XSLT, for example). For HTML results based on

Stylus Studio User Guide

1371

Stylus Studio GUI Reference

XSLT processing, if you click in the result document, Stylus Studio displays the Backmap
Stack window, which lists the XSLT instructions that generated the text or image you
clicked. Stylus Studio also flags the line in the stylesheet that contains the first instruction
in the Backmap Stack window.
Show Profiling Data displays the Stylus Studio Profiler report, if enabled, for XSLT
and XQuery processing. The Profiler report includes overview, call tree, node summary,
and event log statistics. You can backmap from the profiling report to the line of XSLT or
XQuery associated with the statistic. Settings for this report are displayed on the Profiling
Options page of the Scenario Properties dialog box for XSLT and XQuery.
Preview Text displays the raw text of the result. The Text view supports backmapping. You can select and copy text in the Preview Text view.
Export Preview allows you to save the result in a file. It displays the Save As dialog

box.

For More Information

Working with a Sample Result Document on page 41
Backmap Stack on page 1216

1372

Stylus Studio User Guide

Processor Mismatch

Processor Mismatch
XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
If the XQuery or XSLT file you add to an XML pipeline uses a different processor (as
specified in that XSLTs or XQuerys scenario properties) than the processor specified for
the XML pipeline in the execution framework, Stylus Studio displays the Processor
Mismatch dialog box. You can

Use the XML pipelines processor

Change the XML pipelines processor setting to the one used by the XQuery or XSLT
Note This dialog box appears only when you add an XQuery or XSLT document to an XML

pipeline by dragging it and dropping it on the XML Pipeline canvas. If you manually
specify the XQuery or XSLT file URL, Stylus Studio defaults to the processor settings
specified for the XML pipeline.

For More Information

Managing Processor Conflicts
XQuery and XSLT Nodes
Specifying an Execution Framework
Deployment Considerations
Debugging an XML Pipeline
Generating Code for an XML Pipeline

Stylus Studio User Guide

1373

Stylus Studio GUI Reference

Processor Settings (XQuery)

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Processor Settings page of the Options dialog box to specify default settings
for XQuery processors, and to specify which processor you want to use as the default
processor in your XQuery scenarios. You can always select a different processor and
override individual settings on the Processor tab of the Scenario Properties dialog box.
The default XQuery processor is the DataDirect XQuery processor.

Fields
Processor

Drop-down list that displays available processors for XQuery. The debugging symbol
changes based on whether or not the processor you have selected supports backmapping and debugging. The following table summarizes the available processors
and whether or not they support back-mapping and debugging.
Table 196. Available XQuery Processors
Processor

Supports Back-mapping
and Debugging

Requires Specifying
Server Settings

DataDirect XQuery

Saxon

Yes

TigerLogic XDMS

Yes*

Custom

Use Stylus Studio URI Resolver

Whether or not you want to enable the Stylus Studio URI Resolver, which allows the
processor to resolve URIs associated with file systems peculiar to Stylus Studio (like
the file system for XML conversions, for example). This setting is applicable only to
Java-based processors such as Saxon.
Use a default processor

Whether or not you want use the processor you are configuring as the default
processor for all XQuery scenarios. You can always override the default processor

1374

Stylus Studio User Guide

Processor Settings (XQuery)

and individual processor settings on the Processor tab of the Scenario Properties
dialog box when you create the scenario.
Custom Processor Settings

Command line, path, and classpath settings for a custom XQuery processor. These
fields are active only if you select Custom in the Processor drop-down list box.
Command line

The command line used to execute the custom XQuery processor. The command line
must show where to use the three arguments: %1 is the XML source file, %2 is the
XQuery, %3 is the result document. For example: myparser -style %2 -source %1 out %3, or myparser %1 %2 %3.
Path

Specifies any path information that is required to run your custom processor and that
is not already defined in your PATH environment variable.
Classpath

Specifies any directories that your processor must access and that are not already
defined in your CLASSPATH environment variable.

For More Information

Selecting an XQuery Processor
Creating an XQuery Scenario

Stylus Studio User Guide

1375

Stylus Studio GUI Reference

Processor Settings (XSLT)

You use the Processor Settings page of the Options dialog box to specify default settings
for XSLT processors, and to specify which processor you want to use as the default
processor in your XSLT scenarios. You can always select a different processor and
override individual settings on the Processor tab of the Scenario Properties dialog box.

Fields
Processor

Drop-down list that displays available processors for XSLT. The debugging symbol
changes based on whether or not the processor you have selected supports backmapping and debugging. The following table summarizes the available processors
and whether or not they support back-mapping and debugging.
Table 197. Available XSLT Processors
Processor

Supports Back-mapping and

Debugging

Saxon 9.x

Yes

Java built-in

.NET XslTransform

Yes

.NET XslCompiledTransform

Microsoft MSXML

Microsoft MSXML 4

Microsoft MSXML 6

Custom

Use Stylus Studio URI Resolver

1376

Stylus Studio User Guide

Processor Settings (XSLT)

Whether or not you want use the processor you are configuring as the default
processor for all XSLT scenarios. You can always override the default processor and
individual processor settings on the Processor tab of the Scenario Properties dialog
box when you create the scenario.
Custom Processor Settings

Command line, path, and pathname settings for the custom XSLT processor. These
fields are available only if you select Custom from the Processor drop-down list.
Command line

The command line used to execute the custom XSLT processor. The command line
must show where to use the three arguments: %1 is the XML source file, %2 is the
XSLT stylesheet, %3 is the result document. For example: myparser -style %2 -source
%1 -out %3, or myparser %1 %2 %3.
Path

Specifies any path information that is required to run your custom processor and that
is not already defined in your PATH environment variable.
Classpath

Specifies any directories that your processor must access and that are not already
defined in your CLASSPATH environment variable.

For More Information

Setting Module Options
Applying Stylesheets on page 419
Creating a Scenario on page 422

Stylus Studio User Guide

1377

Stylus Studio GUI Reference

Project Window
To display the Project window, select View > Project from the Stylus Studio menu bar.
Use the Project window to organize files in your XML applications.
You can display just the names of files, or you can display the full path. To toggle this,
right-click in the Project window and click Show Full URL Info in the pop-up menu.
In the Project window, the Other Documents folder contains all open files and documents
that are not included in the currently open project. If all open files and documents are in
the open project, the Other Documents folder does not appear. To close all documents that
are not in the open project, right-click Other Documents and click Close Other
Documents.

For More Information

Working with Projects on page 100

1378

Stylus Studio User Guide

Project Wizards

Project Wizards
Stylus Studio includes wizards that create projects from some applications if you have
those applications installed. For example, if you have a source code control application,
the Project from SCC wizard is available.
To display the Project Wizards dialog box, select File > Project > New Project Wizard
from the Stylus Studio menu bar. Click the wizard you want to use, and click OK.

For More Information

Using Stylus Studio with Source Control Applications on page 109

Stylus Studio User Guide

1379

Stylus Studio GUI Reference

Properties for Custom XML Conversions

The Custom XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
The Properties window for Custom XML conversions displays several types of
information about the input file and about the XML that will be output by the custom
XML conversion you create using the Custom XML Conversions editor.

Fields
Properties are organized in the following categories:

Input File read-only information gathered from the input file, and editable properties
that affect XML output. These fields affect the file as a whole when it is converted to
XML. See Input File Properties on page 281.

XML Output URL editable properties that affect XML output, specifically, high-level
XML document properties such as the root element name, namespace, and XML
Schema, if any. See XML Output URL Properties on page 282.

Region Type (fixed-width, line-oriented, or no-output) read only information

gathered from the input file, and editable properties that affect XML output. These
properties affect a contiguous portion of the file when it is converted to XML. See
Region Type Properties on page 284.

Row Element Name editable properties that affect XML output, specifically, the
name that will be used for each row element and the optional pattern that will be used
to control which rows are converted to XML. See Row Element Name Properties on
page 287.

Field Element Name read only information gathered from the input file, editable
properties that affect XML output, and navigational properties. These properties
affect only fields in a given region of the file when it is converted to XML. See Field
Element Name Properties on page 288.

For More Information

Input File Properties on page 281
XML Output URL Properties on page 282
Region Type Properties on page 284
Row Element Name Properties on page 287
1380

Stylus Studio User Guide

Properties for Custom XML Conversions

Field Element Name Properties on page 288

Data Type Properties (by data type) on page 290
Specifying Control Characters on page 311
Creating a Custom XML Conversion Definition on page 222
Converting Non-XML Files to XML on page 213

Stylus Studio User Guide

1381

Stylus Studio GUI Reference

Properties for EDI to XML Conversions

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
The Properties window in the EDI to XML Conversions editor displays properties for the
currently selected node in the EDI Structure tree.
For information on the properties for a specific definition, see EDI Structure Definitions
Properties Reference on page 365.

Fields
Name

The property name.

Value

The property value.

For More Information

Modifying Definition Properties on page 355
Modifying Existing Definitions on page 348
Customizing an EDI Standard on page 340
The EDI to XML Editor on page 317
Creating an EDI to XML Conversion on page 320

1382

Stylus Studio User Guide

Properties for XML Pipelines

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the Properties window of the XML Pipeline Editor to define the properties for
the operations, input ports, and output ports that comprise your XML pipeline. For
example, the ConvertToXML operation requires you to specify the XML conversion URL
for the type of conversion you want to perform.

Fields
Name

The name of the operations property.

Value

The value associated with the property. Some values are specified by default when
you add the operation to the XML pipeline. The default name, for example, is a
variation of the operation name as shown in the Toolbox pane.

For More Information

Adding Nodes to an XML Pipeline
XML Pipeline Node Properties Reference
Working with Nodes

Stylus Studio User Guide

1383

Stylus Studio GUI Reference

Properties for XML Publisher

XML Publisher is available only in Stylus Studio XML Enterprise Suite.
You use the Properties window of the XML Publisher Editor to specify properties that
control formatting and content of the components in your report its body, tables, lists,
and so on. Properties vary based on the component. (See Properties Reference for a
complete list.)

Context and XPath Sub-Properties

Each property has Context and XPath sub-properties that let you define the conditions
under which you want to, say, display a value or apply a given formatting characteristic.
You can use the Color propertys Context and XPath sub-properties to format text based
on the value returned by an XPath expression format all R rated movies in videos.xml
using the color red, for example. (See Example: Building an XML Publisher Report for
an illustration of this technique.)

Fields
Name

The name of the property.

Value

The value associated with the property.

For More Information

Properties Reference
Component Properties
Adding a Data Source
Working with Data Sources
Building an XML Publisher Report

1384

Stylus Studio User Guide

Properties for DTD Nodes

To display the Properties window for DTD nodes, open a DTD, click the Tree tab, and
select a node in the tree. If the Properties window is not visible, select View > Properties
from the Stylus Studio menu bar.
Use the Properties window to view and update properties for the nodes in a DTD. To
specify or change a property value, double-click in the field next to the property name.
To view the properties for a particular node, click that node in the tree view of the DTD.

For More Information

About Node Properties in DTDs on page 684

Stylus Studio User Guide

1385

Stylus Studio GUI Reference

Properties for XML Schema and WSDL Documents

The Properties window is shared by the XML Schema Editor and WSDL Editor. Its
content varies based on the current focus of the document in either the diagram or text
pane. For example, if the focus is on a Binding element in a WSDL document, the
Properties window displays information for that element; if the focus is on a
complexType in an XL Schema imported by the WSDL, the complexTypes information
is displayed.
Use the Properties window to view and update properties for the nodes in an XML
Schema. To specify or change a property value, double-click in the field next to the
property name.
To display the Properties window for XML Schema and WSDL documents, select View
> Properties from the Stylus Studio menu bar.

For More Information

About XML Schema Properties on page 648
Working with WSDL Elements on page 978

1386

Stylus Studio User Guide

Proxy Settings

Proxy Settings
Support for Web services is available only in Stylus Studio XML Enterprise Suite.
You use the Proxy Settings page of the Options dialog box to specify the proxy server
settings you want your Web service calls to use. Proxy server settings defined here are
used by each new Web service call you create, but they can be overridden.
Tip If you want to use your PCs default Internet Explorer proxy server settings, click the
Auto-detect button.

Fields
Address

The server name or IP address. If you need to specify a port, separate the port number
from the address with a colon 123.45.67.89:500, for example.
User

The user name associated with the proxy server.

Password

The password associated with the user.

Do not use proxy server for addresses beginning with

The domain names for which you do not wish to use the proxy server settings
(www.stylusstudio.com, for example). Separate multiple entries with semicolons.

Buttons
Auto-detect

Clicking this button populates the Proxy Settings page with the proxy settings defined
for your PC (Control Panel > Internet Options > Connections > Local Area Network
(LAN) Settings > Proxy Settings).

For More Information

Creating a Web Service Call Scenario
Testing a Web Service

Stylus Studio User Guide

1387

Stylus Studio GUI Reference

Redefine Schema Symbols

The Redefine Schema Symbols dialog box displays the complexTypes, simpleTypes,
groups, and attributeGroups from the referenced schema that you want to redefine. You
use it to select the node, or symbol, you want to redefine.

For More Information

Redefining Nodes on page 641
Referencing XML Schemas in the Diagram View on page 638
Referencing External XML Schemas on page 636
Defining an XML Schema Using the Diagram Tab Getting Started on page 66
Defining XML Schemas on page 567

1388

Stylus Studio User Guide

Referenced Schemas

Referenced Schemas
You use the Referenced Schemas dialog box to import or include external XML Schemas
to the current XML Schema including Schema elements in a WSDL document. You use
this feature if you have an externally defined library of complex types that you want to use
in your XML Schema, for example.

Fields
Schemas referenced by this document

The URL, type (import, include, redefine), and namespace of any XML Schemas
referenced by the current XML Schema.

Buttons
Add

Displays the Add References to Schema dialog box, which allows you to define
additional schema references for the current XML Schema.
Remove

Removes the reference to the external XML Schema from the current XML Schema.
Open

Opens the external XML Schema in Stylus Studio.

For More Information

Stylus Studio User Guide

1389

Stylus Studio GUI Reference

Register and Activate Stylus Studio

You use the Register and Activate Stylus Studio dialog box to register and activate
evaluation copies of Stylus Studio.
To register and activate your evaluation copy of Stylus Studio:
1.

Enter your e-mail address in the Email (required) field and your company name in the
Company field. Name and Phone number fields are optional.

Click the Get Free Key button.

An activation key is e-mailed to the address specified in Step 1.

Copy/Paste that activation key in the Enter your activation key here field. (The
Company field is pre-filled based on the value you provided in Step 1.

Click the Activate Registration button.

Replace
Use the Replace dialog box to search for text in a document and, optionally, replace it. To
display the Replace dialog box, from the Stylus Studio menu bar, click Replace
or
select Edit > Replace from the Stylus Studio menu.

Fields
Find what

Type the text you want to search for.

Replace with

Type the text you want to replace it with.

Match whole word only

For example, if you specify that you want to search for style, the search engine does
not find instances of stylesheet.
Match case

Finds instances that exactly match the lowercase and uppercase of the letters you
enter.
Regular expression

Finds the text you are looking for only in regular expressions.
Replace In

Specify whether you want to replace the text only a selected portion of the document,
or throughout the entire document.
Search only inside

Indicate whether you want to restrict the search to element tags, element values,
attribute names, and/or attribute values.

Buttons
Find Next

Jumps to the next instance of the string you are searching for.
Replace

Replaces only the current instance of the found text.

Replace All

Stylus Studio User Guide

1393

Stylus Studio GUI Reference

Replaces all occurrences of the found text (within the selection or document, as
defined by the Replace In field.

For More Information

Using Standard Editing Tools on page 429
Find

1394

Stylus Studio User Guide

Saxon XQuery Settings

Support for Saxon SA is available only in Stylus Studio XML Enterprise Suite.
You use the Saxon XQuery Settings dialog box to define settings that will be used by the
Saxon processor when executing XQuery in Stylus Studio. These settings are also
reflected in generated Java code.
For more information on using the Saxon processor, refer to the Saxon documentation:
http://www.saxonica.com/documentation/contents.html.

Fields
Command line equivalents for Saxon XQuery settings are shown in parentheses following
the field name where applicable.
Execution mode

Whether you want the Saxon processor to run in basic or schema-aware modes.
Note

The JMS protocol requires the Apache Axis client.

Tree model

Performance settings for document processing. Generally speaking, the Tiny Tree
setting provides superior performance in most cases. For more information on this
topic, see Choosing a Tree Model in the Saxon documentation.
Support XML 1.1

Whether or not to allow XML 1.1 and XML Namespaces 1.1 constructs. This option
must be set if source documents use XML 1.1, or if result documents are to be
serialized as XML 1.1.
Recognize Saxon file extensions and query parameters (-p)

Whether or not you want the Saxon processor to recognize Saxon-specific file
extensions and query parameters in URIs.
Validate source documents using DTD (-v)

Whether or not you want the source document and any documents referenced using
the document() function to be validated against a DTD.
Whitespace stripping

Whether or not whitespace-only text nodes are stripped from the source document.

Stylus Studio User Guide

1395

Stylus Studio GUI Reference

Ignorable (-signorable) All ignorable whitespace text nodes are stripped from

the source documents before any processing, regardless of any xsl:strip-space

declarations in the stylesheet, or any xml:space attributes in the source document.
Whitespace text nodes are ignorable if they appear in elements defined in the
DTD or XML Schema as having element-only content.
All (-sall) All whitespace text nodes are stripped from the source documents
before any processing, regardless of any xsl:strip-space declarations in the
stylesheet, or any xml:space attributes in the source document.
None (-snone) No whitespace is stripped before processing.

Schema-aware Settings

These settings are available only if you are using Saxon-SA to execute your XQuery.

Source document validation Whether or not an XML Schema is required to

validate the source document. Strict (-val) requires an XML Schema, and the
source document must validate against that XML Schema. Lax (-vlax) validates
the source document if an XML Schema is provided, and the source document
must validate against that XML Schema; but if no XML Schema is provided, the
source document passes validation.

Treat validation errors on result document as warnings (-vw) Whether or not

to treat validation errors in result documents as warnings only.

For More Information

Selecting an XQuery Processor
Setting Default Options for Processors
Creating an XQuery Scenario

1396

Stylus Studio User Guide

Saxon XSLT Settings

Support for Saxon schema-aware settings is available only in Stylus Studio XML
Enterprise Suite.
You use the Saxon XSLT Settings dialog box to define settings that will be used by the
Saxon processor when executing XSLT in Stylus Studio. These settings are also reflected
in generated Java code.
For more information on using the Saxon processor, refer to the Saxon documentation:
http://www.saxonica.com/documentation/contents.html.

Fields
Command line equivalents for Saxon XQuery settings are shown in parentheses following
the field name where applicable.
Execution mode

Whether you want the Saxon processor to run in basic or schema-aware modes.
Tree model

Allows you to specify the named template and mode in which you wish to start the
XSLT transformation.

by calling named template (-it) The value of the name= attribute of the
xsl:template element.

in specified mode (-im) The value of the mode= attribute of the xsl:template
element.
Support XML 1.1

Whether or not to allow XML 1.1 and XML Namespaces 1.1 constructs. This option
must be set if source documents use XML 1.1, or if result documents are to be
serialized as XML 1.1.
Suppress warning when running with an XSLT 1.0 stylesheet (-novw)

Suppresses warnings issued when running an XSLT 2.0 processor against an XSLT
1.0 stylesheet.
Stylus Studio User Guide

1397

Stylus Studio GUI Reference

Recognize Saxon file extensions and query parameters (-p)

Whether or not you want the Saxon processor to recognize Saxon-specific file
extensions and query parameters in URIs.
Validate source documents using DTD (-v)

Whether or not you want the source document and any documents referenced using
the document() function to be validated against a DTD.
Treat non-fatal errors as

How you want Stylus Studio to manage non-fatal errors encountered while processing
the XSLT stylesheet:

silent warnings (-w0) Stylus Studio writes error messages to the Output
window, but does not open it automatically. Processing continues.

warnings (-w) Stylus Studio writes error messages to the Output window and
opens the window automatically. Processing continues.

fatal errors (-w2) Stylus Studio writes error messages to the Output window and
opens the window automatically. Processing is interrupted.
Whitespace stripping

Whether or not whitespace-only text nodes are stripped from the source document.

Ignorable (-signorable) All ignorable whitespace text nodes are stripped from
the source documents before any processing, regardless of any xsl:strip-space
declarations in the stylesheet, or any xml:space attributes in the source document.
Whitespace text nodes are ignorable if they appear in elements defined in the
DTD or XML Schema as having element-only content.

All (-sall) All whitespace text nodes are stripped from the source documents
before any processing, regardless of any xsl:strip-space declarations in the
stylesheet, or any xml:space attributes in the source document.

None (-snone) No whitespace is stripped before processing.

Schema-aware Settings

These settings are available only if you are using Saxon-SA to execute your XSLT.

Source document validation Whether or not an XML Schema is required to

1398

Stylus Studio User Guide

Saxon XSLT Settings

Treat validation errors on result document as warnings (-vw) Whether or not

to treat validation errors in result documents as warnings only.

For More Information

XSLT Processors
Overview of Scenario Features
Creating an XSLT Scenario

Stylus Studio User Guide

1399

Stylus Studio GUI Reference

Scenario Properties Bindings Tab (Web Services)

Web services support is available only in Stylus Studio XML Enterprise Suite.
You use the Binding tab of the Scenario Properties dialog box to specify the transport
protocol and related properties you want to use when specifying a Web service call
scenario. Values you specify in the scenario override WSDL values when the scenario is
executed. The WSDL itself is not modified.

Fields
Protocol

The network protocol to use when sending the Web service call to the WSDL URL.
The default is HTTP.
Properties

You use the fields in the Properties table to specify values for parameters used by the
Web service call. Stylus Studio uses these values when you run the Web service call
scenario.
Table 198. Properties Settings
Name
end point*

Description
The destination of the Web service call
http://www.swanandmokashi.com/HomePage/WebServices/Stoc
kQuotes.asmx,

SOAPAction*

for example.

The requested action to be performed by the Web service

for example.

http://swanandmokashi.com/GetQuotes,

1400

user

The username, if any, required by the endpoint.

password

The password, if any, associated with the user.

time out*

The connection timeout; the default is 30000 milliseconds.

Proxy server+

The server name or IP address. If you need to specify a port,

separate the port number from the address with a colon
123.45.67.89:500, for example.

Proxy user+

The user name associated with the proxy server.

Stylus Studio User Guide

Scenario Properties Bindings Tab (Web Services)

Table 198. Properties Settings
Name

Description

Proxy password+

The password associated with the user.

Proxy bypass list+

The domain names for which you do not wish to use the proxy
server settings (www.stylusstudio.com, for example). Separate
multiple entries with semicolons.

* This field is completed when you select a Web service (using the UDDI Browser,
for example).
+ This field uses default values, if any, provided by the Proxy Settings page of the
Options dialog box.
Client

You use the Client field to specify the type of client you want to use to send the SOAP
request to and receive the SOAP response from the Web service Microsoft .NET, or
Apache Axis.

For More Information

Creating a Web Service Call Scenario
Testing a Web Service

Stylus Studio User Guide

1401

Stylus Studio GUI Reference

Scenario Properties for EDI to XML Conversions

The EDI to XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
A scenario allows you to preview the results of an EDI to XML Conversion. You use the
General tab of the Scenario Properties dialog box to specify, optionally, the EDI
document you want to convert to XML and the URI to which you want to output the result
of the conversion.
You open the Scenario Properties dialog box by clicking Edit Scenario Properties (
next to the scenario name field in the EDI to XML Conversions editor.

Fields
Existing Scenarios

Lists the scenarios that have already been defined for the current EDI to XML
Conversion. To view the settings for a different scenario, click the name of that
scenario.

To add a new scenario, click Add. A new scenario is added to the Existing
scenarios list box with a default name.

To copy an existing scenario, click the scenario you want to copy and click Clone.
A new scenario is created with a default name. All other settings are the same as
those of the scenario on which you based the copy.

To delete a scenario, click the scenario and then click Delete.

To rename a scenario, click the scenario and click Rename. The existing name is
highlighted, allowing you to rename it. Press Enter when you are done.
EDI Input (optional)

The EDI document you want to convert to XML.

Output URI (optional)

The absolute path for the file that contains the result of the EDI to XML Conversion
preview. Each time you click Preview Result ( ) to run the EDI to XML
Conversion, Stylus Studio automatically updates the contents of this file (if specified),
and it also displays the result in the Preview window. If you specify an output a file
that does not exist, Stylus Studio creates it.
Use Relative Paths

1402

Stylus Studio User Guide

Scenario Properties for EDI to XML Conversions

Allows you to specify input and output files using paths that are relative to the EDI to
XML Conversion. If you plan to move the EDI to XML Conversion to a different
directory than the one to which you save it during development, consider disregarding
this option and using absolute paths to specify input and output files.
Preview Result in an External Application

By default, EDI to XML Conversion results are displayed in the Preview window. You
can use this option to also display the result in the application you specify.

Buttons
Add creates a new scenario.
Clone copies the selected scenario with a new name.
Delete removes the selected scenario.
Rename renames the selected scenario.

Browse the file system to select the source XML document.

For More Information

Previewing an EDI to XML Conversion on page 322
Creating an EDI to XML Conversion on page 320

Stylus Studio User Guide

1403

Stylus Studio GUI Reference

Scenario Properties Execution Framework

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the Execution Framework page of the Scenario Properties dialog box to specify
the processors you want to use for debugging and XML pipeline processing in Stylus
Studio. Note that these settings also affect code generation for your XML pipeline.

Fields
Execution Framework

Drop-down list that displays available execution frameworks. An execution

framework is a set of compatible processors for XQuery, XSLT, FO processing, and
validation.
Processors

Separate fields for

Validation engine

FO processor

XQuery processor

XSLT processor
When you select an execution framework, Stylus Studio displays default choices for
these fields. You can override them manually if you choose, though the choices you
make can affect Stylus Studios ability to generate code for your XML Pipeline.

For More Information

Specifying an Execution Framework
Execution Framework and Code Generation
Deployment Considerations
Debugging an XML Pipeline
Generating Code for an XML Pipeline

1404

Stylus Studio User Guide

Scenario Properties General Tab (XSLT)

By default, Stylus Studio displays the Scenario Properties dialog box when you create a
new stylesheet using File > New > XSLT Stylesheet. You can display the Scenario
Properties dialog box from the XSLT editor XSLT Source tab or Mapper tab by clicking
Browse
next to the down arrow in the scenario name field.
A scenario allows you to preview the results of applying a stylesheet. Each scenario is for
a particular group of settings. These settings include the name of an XML source
document, the values of any parameters in the stylesheet, the values of any encoding
settings, and the type of performance metrics you want Stylus Studio to capture, if any.
A scenario can be associated with only one stylesheet and only one XML source
document. However, you can associate any number of scenarios with a stylesheet, and you
can associate any number of scenarios with an XML source document.

Fields
Existing Scenarios

Lists the scenarios that have already been defined for the current stylesheet. To view
the settings for a scenario, click the name of the scenario. Stylus Studio displays the
settings in the General tab.
To add a new scenario, click Add. If Add is not active, type information in the fields
in the General tab and click OK.
To copy an existing scenario, click the scenario you want to copy and click Clone. A
new scenario is created with a default name in the Scenario Name field. All other
settings are the same as those of the scenario on which you based the copy.
To delete a scenario, click it and then click Delete.
Scenario Name

The name of the new scenario. You can use the default name, or create one of your
own. You can specify any characters that are allowed in Windows file names.
Source XML URL

Specify the absolute path for the source XML document you want to apply the
stylesheet to in this scenario. If you want, click Browse
to the right of the field
to select to the path.
Output URL

Stylus Studio User Guide

1405

Stylus Studio GUI Reference

Optionally specify or select an absolute path for the file that contains the result of
applying the stylesheet. Each time you click Preview XSLT Result, Stylus Studio
automatically updates the contents of this file, as well as displaying the result in the
XSLT Preview window. If you specify a file that does not exist, Stylus Studio creates
it.
Base URL For HTML Links Resolution

Specify the absolute path that Stylus Studio must use to resolve any links in your
XML source document.
Store Paths Relative to XSLT Document Path

Select this option when you want all paths related to this scenario to be relative to the
XSLT document. This is often convenient; however, you might want to always keep,
for example, your XML source files in a particular location. In such a situation, do not
select this option. This allows you to reference your XML files with an absolute path.
You can move your stylesheet to a different directory and the absolute path for the
source file is still correct.
Preview result in an external application

Displays the result in the default application for the output method specified for the
stylesheet. For example, if the output method for the scenario is HTML and if Internet
Explorer is the default application for displaying HTML files, Stylus Studio displays
the resulting HTML in Internet Explorer, as well as in the XSLT Preview window.

Buttons
Add creates a new scenario.
Clone copies the selected scenario except for the scenario name.
Delete removes the selected scenario.

Browse the file system to select the source XML document.

For More Information

Applying Stylesheets on page 419
Creating a Scenario on page 422
Cloning Scenarios on page 424

1406

Stylus Studio User Guide

Scenario Properties Parameter Values Tab (XSLT)

Fields
Existing Scenarios

Lists the scenarios that are defined for the current stylesheet. To view the parameters
for a scenario, click the name of the scenario. Stylus Studio displays the parameters
in the Parameter Values tab.
Name

Parameter name.
Parameter default value

Default value of the parameter.

Parameter value to be used when processing

Value of the parameter when you apply the stylesheet in this scenario.
Parameter value is an XPath expression (not a string)

Check box that indicates whether the parameter value is an XPath expression or a
string. The default, which is unchecked, is that the parameter is a string.

For More Information

Applying Stylesheets on page 419
Creating a Scenario on page 422

Stylus Studio User Guide

1407

Stylus Studio GUI Reference

Scenario Properties Post-process Tab (XQuery)

You use the the Post-process tab to instruct Stylus Studio to initiate a process that
operates on the result of an XQuery transformation.

Fields
Existing Scenarios

Lists the scenarios that are defined for the current XQuery. To view the post-process
settings for a scenario, click the name of the scenario. Stylus Studio displays the
postprocess settings in the Post-process tab.
Do Not Perform Any Post-processing

This is the default. Stylus Studio does not perform any postprocessing.
Post Process With RenderX XEP

Stylus Studio initiates RenderX XEP.

Post Process With Apache FOP

Stylus Studio initiates the Apache FOP.

Custom Post-process

Stylus Studio executes a postprocess you specify.

Command line

Command line for executing your postprocess. %1 is the input file, which is the result
of applying the stylesheet. %2 is the file that the postprocess generates.
Generated File Extension

File extension you want the postprocessed file to have. For example, .pdf.
Additional Path

Any path information that needs to be defined for postprocess execution and that is
not already defined in your PATH environment variable.

For More Information

Post-processing Result Documents on page 446

1408

Stylus Studio User Guide

Scenario Properties Post-process Tab (XSLT)

Fields
Existing Scenarios

Lists the scenarios that are defined for the current stylesheet. To view the postprocess
settings for a scenario, click the name of the scenario. Stylus Studio displays the
postprocess settings in the Post-process tab.
Do Not Perform Any Post-processing

This is the default. Stylus Studio does not perform any postprocessing.
Post Process With Apache FOP

Stylus Studio initiates the Apache FOP.

Custom Post-process

Stylus Studio executes a postprocess you specify.

Command line

Command line for executing your postprocess. %1 is the input file, which is the result
of applying the stylesheet. %2 is the file that the postprocess generates.
Generated File Extension

File extension you want the postprocessed file to have. For example, .pdf.
Additional Path

Any path information that needs to be defined for postprocess execution and that is
not already defined in your PATH environment variable.

For More Information

Post-processing Result Documents on page 446

Stylus Studio User Guide

1409

Stylus Studio GUI Reference

Scenario Properties Profiling Options Tab (XSLT)

XSLT Profiling is available only in Stylus Studio XML Enterprise Suite.
By default, Stylus Studio displays the Scenario Properties dialog box when you create a
new stylesheet using File > New > XSLT Stylesheet. You can display the Scenario
Properties dialog box from the XSLT editor XSLT Source tab or Mapper tab. Click
Browse
next to the down arrow in the scenario name field.
Click the Profiling Options tab to turn on the Profiler and to specify the type of
information you want to capture in the Profilers report.

Fields
Show Call Tree of Execution Times

Displays the Call Tree section of the Profiler report, which lists the call tree of XSLT
instructions. Duplicate instructions within individual call tree paths are not repeated.
The reports Call column identifies the number of times a given instruction is called
within each call tree.
Show Execution Time by XSL Element

Displays the Node Summary section of the Profiler report, which lists every
instruction that is called by the XSLT code. Instructions are listed only once,
regardless of the number of times they are called. The reports Call column identifies
the number of times an instruction is called.
Show Log of Step-by-Step Execution

Displays the Event Log section of the Profiler report, which lists every instruction that
is executed in every call tree, regardless of the number of times it is called. Displaying
the report with this option selected can, therefore, take a long time. The XSLT
processing time itself is not affected by this report option.
Limit Trace To

Displaying a Profiler report can often take much longer than the time required to
evaluate the XSLT itself. You can use the Instructions and Levels field in the Limit
Trace To group box to limit the number of instructions and/or the depth of the levels
displayed.
Save Raw XML Profiling Data To:

1410

Stylus Studio User Guide

Scenario Properties Profiling Options Tab (XSLT)

Saves the raw performance data captured by the Profiler to an XML file. Use this
option if you want to create your own reports.

Stylus Studio User Guide

1411

Stylus Studio GUI Reference

Scenario Properties Processor Tab (XQuery)

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
By default, Stylus Studio uses its own processor to process XQuery. You use the
Processor tab of the Scenario Properties dialog box to specify the XQuery processor you
want to use. Default values for these fields come from the values specified in the
Processor Settings page in the Options dialog box. See Processor Settings (XQuery) on
page 1374.
You can display the Scenario Properties dialog box from the XQuery Editor (XQuery
Source tab or Mapper tab). Click the Browse button (
) at the top of the editor, or
select Create Scenario from the scenario drop-down list.

Fields
Existing Scenarios

Lists the scenarios that are defined for the current XQuery. To view the processor
settings for a given scenario, click the name of the scenario.
Processor

Supports Back-mapping
and Debugging

Requires Specifying
Server Settings

Saxon 9.x

Yes

DataDirect XQuery

Saxon

Yes

TigerLogic XDMS

Yes

Custom

Use Stylus Studio URI Resolver

1412

Stylus Studio User Guide

Scenario Properties Processor Tab (XQuery)

Whether or not you want to enable the Stylus Studio URI Resolver, which allows the
processor to resolve URIs associated with file systems peculiar to Stylus Studio (like
the file system for XMl conversions, for example). This setting is applicable only to
Java-based processors such as Saxon.
Custom Processor Settings

Command line, path, and pathname settings for the custom XQuery processor. These
fields are available only if you select Custom from the Processor drop-down list.
Command line

Command line for executing an external XQuery processor you define. The command
line must show where to use the three arguments: %1 is the XML source file, %2 is the
XQuery, %3 is the result document. For example: myXQprocessor -style %2 -source
%1 -out %3, or myXQprocessor %1 %2 %3.
Path

Specifies any path information that is required to run your custom processor and that
is not already defined in your PATH environment variable.
Classpath

Specifies any directories that your processor must access and that are not already
defined in your CLASSPATH environment variable.

For More Information

Creating an XQuery Scenario on page 900

Stylus Studio User Guide

1413

Stylus Studio GUI Reference

Scenario Properties Processor Tab (XSLT)

By default, Stylus Studio uses its own processor to process XSLT. You use the Processor
tab of the Scenario Properties dialog box to specify the XSLT processor you want to use.
Default values for these fields come from the values specified in the Processor Settings
page in the Options dialog box. See Processor Settings (XSLT) on page 1376.
You can display the Scenario Properties dialog box from the XSLT Editor (XSLT Source
tab or Mapper tab). Click Browse
next to the down arrow in the scenario name field.

Fields
Existing Scenarios

Lists the scenarios that are defined for the current stylesheet. To view the processor
settings for a scenario, click the name of the scenario. Stylus Studio displays the
processor settings in the Processor tab.
Processor

Drop-down list that displays available processors for XSLT. The debugging symbol
changes based on whether or not the processor you have selected supports back-

1414

Stylus Studio User Guide

Scenario Properties Processor Tab (XSLT)

mapping and debugging. The following table summarizes the available processors
and whether or not they support back-mapping and debugging.
Table 200. Available XSLT Processors

Note

Processor

Supports Back-mapping and

Debugging

Saxon 9.x

Yes

Microsoft .NET XslTransform

Yes

Microsoft .NET XslCompiledTransform

Yes

Microsoft MSXML

Microsoft MSXML 4

Microsoft MSXML 6

Custom

Stylus Studio requires Microsoft .NET Framework 1.1 or 2.0 in order to use the .NET
or MSXML processors.
Use Stylus Studio URI Resolver

Whether or not you want to enable the Stylus Studio URI Resolver, which allows the
processor to resolve URIs associated with file systems peculiar to Stylus Studio (like
the file system for XML conversions, for example). This setting is optional only with
Java-based processors such as Saxon.
Custom Processor Settings

Command line, path, and pathname settings for the custom XSLT processor. These
fields are available only if you select Custom from the Processor drop-down list.
Command line

Specifies any path information that is required to run your custom processor and that
is not already defined in your PATH environment variable or in the default Path in the
External XSLT options page.
Stylus Studio User Guide

1415

Stylus Studio GUI Reference

Classpath

Specifies any directories that your processor must access and that are not already
defined in your CLASSPATH environment variable or in the default Classpath in the
Custom Processor options page.

For More Information

Setting Module Options on page 120
Applying Stylesheets on page 419
Creating a Scenario on page 422

1416

Stylus Studio User Guide

Scenario Properties General Tab (XQuery)

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite. Support for collections and DataDirect
XQuery is available only in Stylus Studio XML Enterprise Suite.
A scenario allows you to preview the results of an XQuery. You use the General tab of the
Scenario Properties dialog box to specify, optionally, the XML you want to query (you
can write an XQuery that does not perform any operations on an XML document) and the
URL to which you want to output the query result.
You can choose as input existing XML documents, or XML documents that Stylus Studio
creates on-the-fly, based on a table in a relational database or a flat file (like EDI)
converted to XML, for example.
You can display the XQuery Scenario Properties dialog box by clicking Browse
next
to the scenario name field in the XQuery Editor (in either XQuery Source or Mapper tabs).

Fields
Existing Scenarios

Lists the scenarios that have already been defined for the current XQuery. To view the
settings for a different scenario, click the name of that scenario.

To add a new scenario, click Add. A new scenario is added to the Existing
scenarios list box with a default name.

To delete a scenario, click the scenario and then click Delete.

To rename a scenario, click the scenario and click Rename. The existing name is
highlighted, allowing you to rename it. Press Enter when you are done.
Main Input (optional)

The XML against which you want to run the XQuery. This can be an existing XML
document, or an XML document Stylus Studio creates on the fly using an XMl
conversion to convert a text file, like EDI, to XML. See Other Ways to Convert Files
to XML on page 216 for more information.
Output URL (optional)

Stylus Studio User Guide

1417

Stylus Studio GUI Reference

Optionally specify or select an absolute path for the file that contains the result of the
XQuery preview. Each time you click Preview Result to run the XQuery, Stylus
Studio automatically updates the contents of this file, and it also displays the result in
the Preview window. If you specify an output a file that does not exist, Stylus Studio
creates it.
Use Relative Paths

Allows you to specify input and output files using paths that are relative to the
XQuery. If you plan to move the XQuery to a different directory than the one to which
you save it during development, consider disregarding this option and using absolute
paths to specify input and output files.
Preview Result in an External Application

By default, XQuery results are displayed in the Preview window. You can use this
option to also display the result in the default application for the output method
specified for the XQuery. For example, if the output method for the scenario is HTML
Stylus Studio displays the resulting HTML in a web browser like Internet Explorer,
as well as in the Preview window.

Buttons
Add creates a new scenario.
Clone copies the selected scenario with a new name.
Delete removes the selected scenario.
Rename renames the selected scenario.

Browse the file system to select the source XML document.

For More Information

Creating an XQuery Scenario on page 900
Getting Started with XQuery in Stylus Studio on page 782
Building an XQuery Using the Mapper on page 813

1418

Stylus Studio User Guide

Scenario Properties Parameter Values Tab (XQuery)

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You can display the Scenario Properties dialog box for an XQuery by clicking Browse
next to the scenario name field. Although a scenario is not required in order to create
an XQuery, it is quite common to apply an XQuery to a source XML document in order
to perform some processing on the XML. Scenarios help you facilitate this operation.
A scenario allows you to preview the results of applying an XQuery. Scenario settings
include the name of an XML source document, the values of any parameters in the
XQuery, and the type of performance metrics you want Stylus Studio to capture, if any.
A scenario can be associated with only one XQuery and only one XML source document.
However, you can associate any number of scenarios with an XQuery, and you can
associate any number of scenarios with an XML source document.
Click the Parameter Values tab to view or modify information about the XQuerys
parameters. You can modify existing parameters on this page of the Scenario Properties
dialog box, but you cannot create new ones. New parameters can be created in the XQuery
source only.

Fields
Variable Name

Lists the variables defined in the current XQuery.

Expression

The expression associated with the variable. You can enter a value in this field.

For More Information

Creating an XQuery Scenario on page 900
Getting Started with XQuery in Stylus Studio on page 782
Building an XQuery Using the Mapper on page 813

Stylus Studio User Guide

1419

Stylus Studio GUI Reference

Scenario Properties Profiling Options Tab (XQuery)

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You can display the Scenario Properties dialog box from the XQuery editor XQuery
next to the down arrow in the scenario name
Source tab or Mapper tab. Click Browse
field.
Click the Profiling Options tab to turn on the Profiler and to specify the type of
information you want to capture in the Profilers report.

Fields
Show Call Tree of Execution Times

Displays the Call Tree section of the Profiler report, which lists the call tree of
XQuery instructions. Duplicate instructions within individual call tree paths are not
repeated. The reports Call column identifies the number of times a given instruction
is called within each call tree.
Show Execution Time by XQuery Instruction

Displays the Node Summary section of the Profiler report, which lists every
instruction that is called by the XQuery code. Instructions are listed only once,
regardless of the number of times they are called. The reports Call column identifies
the number of times an instruction is called.
Show Log of Step-by-Step Execution

Displays the Event Log section of the Profiler report, which lists every instruction that
is executed in every call tree, regardless of the number of times it is called. Displaying
the report with this option selected can, therefore, take a long time. The XQuery
processing time itself is not affected by this report option.
Limit Trace To

Displaying a Profiler report can often take much longer than the time required to
evaluate the XQuery itself. You can use the Instructions and Levels field in the Limit
Trace To group box to limit the number of instructions and/or the depth of the levels
displayed.
Save Raw XML Profiling Data To:

Saves the raw performance data captured by the Profiler to an XML file. Use this
option if you want to create your own reports.
1420

Stylus Studio User Guide

Scenario Properties Profiling Options Tab (XQuery)

For More Information

Profiling XQuery on page 892
Creating an XQuery Scenario on page 900
Getting Started with XQuery in Stylus Studio on page 782
Building an XQuery Using the Mapper on page 813

Stylus Studio User Guide

1421

Stylus Studio GUI Reference

Scenario Properties Validation Tab (XQuery)

You use the Validation tab of the Scenario Properties dialog box to specify whether or
not you want to validate the XML document resulting from XQuery processing. If you
choose to validate the XML document, you can use

Stylus Studios built-in XML validation engine (Xerces C++)

Any third-party validation engine supported by Stylus Studio (XSV, for example)

Any custom validation engine specified in the Custom Validation Engines page of the
Options dialog box
If you use the built-in validation engine, you can also specify the XML Schema against
which you want the XML document to be validated.

Fields
Validate the query result

Whether or not you want to validate the result of the XQuery processing.
Use built-in validator

Whether or not you want to use Stylus Studios built-in validation engine.
Validate against these schemas

The XML Schema against which you want the XML document to be validated. You
can specify XML Schema for validation only if you use the Stylus Studio built-in
validation engine.
Use custom validation engine

Whether or not you want to use a third-party or other custom validation engine to
validate the result of the XQuery processing. You can choose a third-party validation
engine supported by Stylus Studio or any custom validation engine defined on the
Custom Validation Engines page of the Options dialog box.

For More Information

Creating an XQuery Scenario on page 900
Getting Started with XQuery in Stylus Studio on page 782

1422

Stylus Studio User Guide

Scenario Properties Validation Tab (XSLT)

You use the Validation tab of the Scenario Properties dialog box to specify whether or
not you want to validate the XML document resulting from XSLT processing. If you
choose to validate the XML document, you can use

Stylus Studios built-in XMLvalidation engine (Xerces C++)

Any third-party validation engine supported by Stylus Studio (XSV, for example)

Fields
Validate the stylesheet result

Whether or not you want to validate the result of the XSLT processing.
Use internal validator

Whether or not you want to use Stylus Studios built-in validation engine.
Validate against these schemas

Whether or not you want to use a third-party or other custom validation engine to
validate the result of the XSLT processing. You can choose a third-party validation
engine supported by Stylus Studio or any custom validation engine defined on the
Custom Validation Engines page of the Options dialog box.

For More Information

Creating an XSLT Scenario on page 543
Working with Stylesheets on page 413

Stylus Studio User Guide

1423

Stylus Studio GUI Reference

Segment Definition
The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
You use the Segment Definition dialog box to add a segment definition to the EDI
structure associated with your EDI to XML Conversion. The segment definition resides
in the SEF file for your EDI to XML Conversion.

Fields
Segment Name

The name you want to give to the segment. Names are always created in upper case.
Description

The description associated with this segment. This field is optional.

For More Information

Adding a Segment on page 345
Modifying Existing Definitions on page 348
Creating New Structure Definitions on page 344
Customizing an EDI Standard on page 340

1424

Stylus Studio User Guide

Select Multiple URLs

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
A Validate node can represent multiple XML Schemas. You can add additional XML
Schemas by simply dragging and dropping the XML Schema document (.xsd) on the
Validate node, or you can use the Select Multiple URLs dialog box to specify them.

Buttons
Use the Add New button to display the Open dialog box, from which you can navigate
to the file system where the XML Schema you want to use is written.
Use the Remove button to remove the association of the XML Schema with the
Validate node.

For More Information

Validate Nodes
Adding Nodes to an XML Pipeline
XML Pipeline Node Properties Reference
Working with Nodes

Stylus Studio User Guide

1425

Stylus Studio GUI Reference

Select Source/Target Folder

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Select Source Folder dialog box to select the source folder you want to diff
using the Stylus Studio Diff Folders tool. You use the same dialog box to select the target
folder for the diffing operation.

For More Information

Diffing Folders on page 182

1426

Stylus Studio User Guide

Select XML Converter

DataDirect XML Converters and the Custom XML Conversion module are
available only in Stylus Studio XML Enterprise Suite.
You use the Select XML Converter dialog box to select the DataDirect XML Converter or
custom XML conversion definition you want to use to convert a file.

Fields
Property

The configuration property to be used with the selected DataDirect XML Converter.
Custom XML conversion definitions do not display configuration properties.
See Chapter 4, XML Converters Properties, in the DataDirect XML Converters
Users Guide and Reference for complete properties reference information for all
DataDirect XML Converters. information. Documentation for DataDirect XML
Converters is available:

In the \doc folder for DataDirect XML Converters where you installed Stylus
Studio \components\XML Converters for .NET\doc, for example

On the DataDirect Technologies web site:

http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp

Value

The current value of the DataDirect XML Converter configuration property.

URL

The converter URL for the DataDirect XML Converter or custom XML conversion
definition you selected.

For More Information

Using XML Converters to Open a Non-XML File as XML on page 219
How to Open a File Using a Custom XML Conversion Definition on page 266
How XML Converters are Used in Stylus Studio on page 214
Custom XML Conversions on page 221
Using Custom XML Conversion Definitions in Stylus Studio on page 266
Creating a Custom XML Conversion Definition on page 222

Stylus Studio User Guide

1427

Stylus Studio GUI Reference

Converting Non-XML Files to XML on page 213

1428

Stylus Studio User Guide

Select XML Converter Properties

The EDI to XML Conversions module is available only in Stylus Studio XML
Enterprise Suite.
EDI to XML conversions use the DataDirect XML Converters engine to convert EDI
to XML. The properties you specify in the Select XML Converter Properties dialog box
are used by the DataDirect XML Converters engine to tune the conversion process and
manage the XML output.
Changes you make to default property settings are displayed in the URI field, which shows
the converter:EDI URI that is consumed by the DataDirect XML Converters engine.

Fields
Property

The full name of the XML Converters property, followed by the name as it appears
in the converter:EDI URI scheme.
See Chapter 4, XML Converters Properties, in the DataDirect XML Converters
Users Guide and Reference for complete properties reference information for all
DataDirect XML Converters. information. Documentation for DataDirect XML
Converters is available:

In the \doc folder for DataDirect XML Converters where you installed Stylus
Studio \components\XML Converters for .NET\doc, for example

On the DataDirect Technologies web site:

http://www.datadirect.com/techres/xmlconvertersproddoc/index.ssp

Value

The value for the XML Converters property.

URI

The URI that is used by the DataDirect XML Converters engine when you preview
an EDI to XML Conversion. This field is read-only; changes to it are made using the
Value field in the Property table.

For More Information

XML Converter Properties on page 271
About the Converter URI on page 339

Stylus Studio User Guide

1429

Stylus Studio GUI Reference

Specifying XML Converter Properties on page 339

1430

Stylus Studio User Guide

Set Classpath

Set Classpath
You use the Set Classpath dialog box to specify a classpath for various Stylus Studio
modules. Examples include the classpath for:

JDBC drivers for relational databases

the Stylus Studio project

Custom validation engines

Note The title of this dialog box varies based on the context in which it appears. The

functionality, however, is the same.

Fields
Locations

Classpath entries added using the browse folders (

) button.

Adding a Classpath Entry

To add a classpath entry:
1.

Click the browse folders (

) button above the Locations field.
A new entry field appears in the Location list box. Two buttons appear to the right of
the entry field.

To search for JAR files, click the browse JAR files button (

Stylus Studio User Guide

1431

Stylus Studio GUI Reference

Stylus Studio displays the Browse for JAR Files dialog box.

Figure 600. Browse for JAR Files Dialog Box

To search for folders, click the browser folders button (

Stylus Studio displays the Browse for Files dialog box.

Figure 601. Browse for Folder Dialog Box

1432

Choose the JAR file or folder you want to add to the classpath and click OK.
The file or folder is added to the end of the list. Stylus Studio searches the classpaths
in the order they appear in the Locations list box.

Stylus Studio User Guide

Set Classpath
4.

To change the order of a particular file or folder, select it and use the up and down
arrows to change its order.

Click OK to set the classpath.

For More Information

Creating a Database Connection
Setting a Project Classpath
Custom XML Validation Engines

Stylus Studio User Guide

1433

Stylus Studio GUI Reference

Set Node and Match Pattern

The Custom XML Conversion module is available only in Stylus Studio XML
Enterprise Suite.
You use the Set Node and Match Pattern dialog box to work with nodes (row element
name/match pattern pairs) in the custom XML conversions you define. When you define
a node, only those rows in the input file that match the pattern you specify using a regular
expression in the Match Pattern field are converted to XML (using the row element name
you specify in the Row Element Name field).

Fields
Row Element Name

Specifies the name you want to use for rows in the file to be converted to XML that
match the pattern you specify in the Match Pattern field.
Match Pattern

The regular expression you want to use to match rows from the non-XML file you are
converting to XML. To learn more about regular expression syntax, visit
http://www.boost.org/libs/regex/doc/syntax.html.

For More Information

Pattern Matching on page 257
The Custom XML Conversion Definition Editor on page 225
Converting Non-XML Files to XML on page 213

1434

Stylus Studio User Guide

Shortcut Keys

Shortcut Keys
To specify keyboard shortcuts, select Tools > Keyboard from the Stylus Studio menu bar.
The Shortcut Keys dialog box allows you to specify a keyboard shortcut for a Stylus
Studio task.

Fields
Select a macro:

Displays a list of over 100 actions you might perform while using Stylus Studio.
Some are menu selections and others are item and button selections. For example:
File > Project > Add Document to Project
XML : Tree Editing : Add Attribute

Click the macro for which you want to specify a keyboard shortcut.
Description

Displays a description of the selected macro.

Assigned shortcuts

Displays the keyboard shortcut, if any, defined for the selected macro.

Buttons
Create Shortcut

Click a macro and then click Create Shortcut to define the keyboard shortcut. The
Assign Shortcut dialog box appears. See Assign Shortcut on page 1209.
Remove

To delete a shortcut, click the macro for which the shortcut is defined. In the Assigned
shortcuts field, click the shortcut you want to delete. Click Remove.
Reset All

Deletes all shortcuts.

Stylus Studio User Guide

1435

Stylus Studio GUI Reference

Source Code Control Properties

The Source Code Control Properties dialog box displays the current values of properties.
While you can change the properties in this dialog box, you should do so only because a
connection is not working, and only when you are certain of all the implications of a
change.
To display this dialog box, select SourceControl > Source Control Properties from the
Stylus Studio menu bar.

Fields
Provider

Name of the source code control application you are using.

Version

Version of the installed source code control application.

User

User name for connecting to the source control server.

ClearCase Attache

Name of the ClearCase view.

Auxiliary Path

Information required for Stylus Studio to connect to your source control server.
Local Project Path

Local directory to which you copied the files that are under source control. If you
move these files, you must specify the new directory here.

For More Information

Using Stylus Studio with Source Control Applications on page 109

1436

Stylus Studio User Guide

Spelling

Spelling
You use the Spelling dialog box actively spell check an XML document. This dialog box
appears when you select Tools > Check Spelling from the menu, even if the Spell Checker
is disabled for the current editor type (Tools > Options > General).
In addition to checking the spelling in the current document, you use the Spelling dialog
box to

Replace words

Add words to your personal dictionary

Edit your personal dictionary

Fields
Misspelled Word

Displays the misspelled word identified by the Spell Checker. (The misspelled word
is also selected in the document editor.)
Replace With

Allows you to specify an alternative for the misspelled word. Type your own word, or
select a work from the Suggestions field.
When you type your own word, the Add button becomes active, allowing you to add
the new word to your personal dictionary.

Tip

Alternatives

Alternative suggestions to the misspelled word. The words in this field are from a
merged version of the Spell Checkers standard dictionary and your personal
dictionary entries.

Buttons
Ignore

Ignores the word currently identified as misspelled and continues spell checking the
document.
Ignore All

Ignores all occurrences of the word currently identified as misspelled and continues
spell checking the document.
Replace

Stylus Studio User Guide

1437

Stylus Studio GUI Reference

Replaces the word currently identified as misspelled with the word displayed in the
Replace With field and continues spell checking the document.
Replace All

Replaces all occurrences of the word currently identified as misspelled with the word
displayed in the Replace With field and continues spell checking the document.
Personal Dictionary
Add Adds words identified as misspellings to the personal dictionary and continues
spell-checking the document.
Edit Displays the Personal Dictionary Editor dialog box, which allows you to edit
the contents of the personal dictionary.

For More Information

Using the Spell Checker

1438

Stylus Studio User Guide

Start New Region

You use the Start New Region dialog box to specify a change in the files structure, such
as a file with a fixed-width header followed by a variable-width section; or when row
separators or field delimiters change from section to section.
Tip Consider using pattern matching to separate records of different types in the same file.

See Pattern Matching on page 257 for more information.

Fields
New Region Type

Used to specify the type of the region you are creating. Choices are:

Line-oriented (the default)

Fixed-width

No-output
Begin New Region

The point in the file at which you want to create the new region. Choices are relative
to the cursors current position in the file:

After the current row (the default)

After the current position in bytes

Tip

If the .conv file you are creating will be used with different input files, it is possible
that the line lengths could vary from file to file, changing the byte offset. Consider
using the row setting (the default) for the Begin New Region property in this case.

For More Information

Defining and Joining Regions on page 243
Adjusting Fixed-Width Regions on page 241
Working with Regions on page 238
Pattern Matching on page 257

Stylus Studio User Guide

1439

Stylus Studio GUI Reference

Stylus Studio
Use Stylus Studio to develop an XML application. To get an overview of the tool, see
Getting Started with Stylus Studio on page 1, or take a look at our online videos to get
a virtual view of Stylus Studio modules in action.
If you would rather just get started, the following shortcuts might get you pointed in the
right direction. To create a

XML document, select File > New > XML Document. To open an XML document,
select File > Open and navigate to the document you want to open.

Custom XML conversion, select File > New > Custom XML Conversion

Relational data source, right-click the Relational DB icon in the File Explorer window
and select New Server.

XQuery, select File > New > XQuery File.

XSLT stylesheet, select File > New > XSLT Stylesheet.

XML Pipeline, select File > New > XML PIpeline.

XML report, select File > New > XML Report.

Web Service call, select File > New > Web Service Call.
Support for relational databases and XQuery is available only in Stylus Studio
XML Enterprise Suite and Stylus Studio XML Professional Suite. Support for XML
Pipelines, XML reports, Web services, and the Custom XML Conversions
module is available only in Stylus Studio XML Enterprise Suite.
To debug an XQuery document, XSLT stylesheet, Java file, open the file you want to
debug.
If you want, you can create a project to help you organize the files in your application. In
the Project window, right-click to display the project management shortcut menu.

For More Information

Getting Started with Stylus Studio on page 1
Updating an XML Document Getting Started on page 10
Working with Stylesheets Getting Started on page 33
Using the XSLT Mapper Getting Started on page 44
Defining a DTD Getting Started on page 61

1440

Stylus Studio User Guide

Stylus Studio

Defining an XML Schema Using the Diagram Tab Getting Started on page 66
Composing Web Service Calls on page 943

Stylus Studio User Guide

1441

Stylus Studio GUI Reference

Stylus Studio Update

Indicates whether or not there is a more current version of Stylus Studio than the one you
are currently running. When you launch this dialog box (Help > Check for latest version),
the Stylus Studio server is checked for a more current version either a full release, or a
beta version.

Buttons
Latest Version

This button becomes active if a newer release version of Stylus Studio is available.
Latest Beta

This button becomes active if a newer beta version of Stylus Studio is available.
Close

Closes the Stylus Studio Update dialog box.

1442

Stylus Studio User Guide

Text Catalog to XML Catalog

Catalog support is available only in Stylus Studio XML Enterprise Suite.
The Text Catalog to XML Catalog document wizard allows you to convert a catalog in
plain text into XML format. Stylus Studio can read plain text catalogs in the OASIS
standard catalog file format, but you might want to use this document wizard to view the
catalog in XML.

Fields
Choose OASIS Text-mode Catalog File

The text catalog you want to convert to XML format. Type the name, or use the
Browse button.

Stylus Studio User Guide

1443

Stylus Studio GUI Reference

Toolbox Pane
XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
The Toolbox pane contains icons that represent the nodes you can add to an XML
pipeline. To use a tool from the Toolbox pane, simply drag the icon associated with the
node you want to add to your XML pipeline, and drop it on the XML pipeline canvas. The
node is added to the XML pipeline, and its properties are displayed in the Properties
window.
To specify properties for input ports and output ports, you must select the port explicitly.
Properties for ports are not displayed with the properties for the node with which they are
associated.

For More Information

Using the Toolbox
Using the Toolbox
Adding Nodes to an XML Pipeline
XML Pipeline Node Properties Reference
Parts of the XML Pipeline Editor
Steps for Building an XML Pipeline
Planning an XML Pipeline

1444

Stylus Studio User Guide

TigerLogic XDMS Server Login

Support for TigerLogic XDMS is available only in Stylus Studio XML Enterprise
Suite.
You use the TigerLogic XDMS Server Settings dialog box to specify the settings for the
server that hosts TigerLogic XDMS. Stylus Studio uses this information to access XML
documents from the TigerLogic XDMS file system when processing XQuery using the
TigerLogic XDMS processor.

Fields

Host

The URI of the machine on which the TigerLogic XDMS server is installed.

Port

The port through which you connect to the server.

User

The user name required to log on to the server.

Password

The password associated with that user name.

For More Information

Creating an XQuery Scenario
Using Stylus Studio with TigerLogic XDMS

Stylus Studio User Guide

1445

Stylus Studio GUI Reference

Type Derivation
You use the Type Derivation dialog box to specify the base type from which you want to
derive the type you are currently defining in the XML Schema Editor Diagram tab. You
can select from types defined by World Wide Web Consortium (W3C) XML Schema, as
well as from any types defined in the XML Schema you are redefining.

For More Information

Redefining Nodes on page 641
Defining simpleTypes in XML Schemas on page 599
Referencing XML Schemas in the Diagram View on page 638
Referencing External XML Schemas on page 636

1446

Stylus Studio User Guide

UDDI Registry Browser

Web services support is available only in Stylus Studio XML Enterprise Suite.
Use the UDDI Registry Browser dialog box to browse Universal Description, Discovery,
and Integration (UDDI) registries for Web services. Once you select the Web service you
want, Stylus Studio automatically composes a SOAP request based on the WSDL
associated with that Web service.

Fields
UDDI Registry

The name of the UDDI registry you want to search.

Query

The string you want to use to search the registry for available Web services (stocks
or weather, for example).
Max Rows

The maximum number of rows you want the query to return and display in the Result
field.
Search By

Whether you want to search the UDDI registry by the Web service provider name
(Provider), or by Web service name (Service). Web service name is the default.
Result

The result of the query entered in the Query field when the query is run.
WSDL URL

The WSDL URL exposed by the Web service you select from the Result field.

For More Information

Web Service Call Composer on page 1453

Stylus Studio User Guide

1447

Stylus Studio GUI Reference

Value
You use the Value dialog box in the XQuery and XSLT mapper to specify the text value
you want to associate with a target structure element or attribute. This dialog box appears
when you select Set Text Value from the element or attribute shortcut menu in the target
structure.
In addition, you use the Value dialog box in the XSLT mapper to specify the value you
want to associate with an input port in an XSLT operation block, XPath or Java function
block, or logical operator. For example, you might use the Value dialog box to specify the
value for an xsl:value-of operation.
XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.

For More Information

Building an XQuery Using the Mapper on page 813
Creating XSLT Using the XSLT Mapper on page 507

1448

Stylus Studio User Guide

Variables

Variables
During debugging, click Variables
in the Stylus Studio tool bar to display the
Variables window. This button is active only when processing has been suspended.
For Java classes, Stylus Studio displays

Local variables that are defined at that point in the processing and their values.

Function parameters and their values.

A special variable named this. The this variable represents the object being
processed. It allows you to drill down and obtain additional information.
For stylesheets, Stylus Studio displays a path that shows which node in the stylesheet was
being processed when processing was suspended.

For More Information

Viewing Processing Information on page 553

Stylus Studio User Guide

1449

Stylus Studio GUI Reference

View Sample XML

The View Sample XML dialog box displays the XML fragment that defines the currently
selected node in the Diagram tab of both the XML Schema Editor and WSDL Editor.
If you want, you can create a new XML document based on this fragment by clicking the
Open as New Document button.

About XML Schema Fragments

If the XML Schema contains an element defined using a built-in type, the instance of that
element in the XML document is created using the minimum value of the range specified
for that type. For example, if the XML Schema contains a <part> element defined as
type=xs:integer, the <part> element in the resulting XML document appears as
<part>-9223372036854775808</part>.

For More Information

For XML Schema users:

Viewing Sample XML

Defining an XML Schema Using the Diagram Tab Getting Started

Working with XML Schema in Stylus Studio

Creating an XML Schema in Stylus Studio

For WSDL users:

Working with WSDL Documents on page 967

1450

Stylus Studio User Guide

Watch

Watch
During debugging, click Watch
in the Stylus Studio tool bar to display the Watch
window. Use the Watch window to monitor particular variables.
Enter the names of the variables you want to watch. You can enter as many as you like. In
your Java program, you can double-click a symbol and drag it to the Watch window to
enter it as a variable you want to watch. When Stylus Studio suspends processing, it
displays the current values for any variables listed in the Watch window.
Another way to obtain the value for a variable is to hover over the symbol in your Java
program or stylesheet. Stylus Studio displays a pop-up box that contains the current value.
During XSLT debugging, you can enter XPath expressions in the Watch window fields.
Stylus Studio uses the current context to evaluate these expressions, and displays the
results with the same kind of interface Stylus Studio uses for nodeList and node variables.

For More Information

Viewing Processing Information on page 553

Stylus Studio User Guide

1451

Stylus Studio GUI Reference

Watch Video Demos of Stylus Studio Features

This splash screen describes some of the video demonstrations of Stylus Studios features.

For More Information

You can learn more about Stylus Studio video demonstrations here:
http://www.stylusstudio.com/xml_videos.html (select Products > XML Video
Demonstrations from the Stylus Studio Web site menu).

1452

Stylus Studio User Guide

Web Service Call Composer

Web services support is available only in Stylus Studio XML Enterprise Suite.
You use the Web service call composer to select an operation exposed by a Web service.
You can test the Web service you select and save the Web service call composed by Stylus
Studio for use in an XML application.

Fields
WSDL URL

The URL of the Web Service Description Language (WSDL) made available by a
given Web service. You can type a URL, use the Browse button, or use the UDDI...
button to search the Universal Discovery, Description, and Integration (UDDI)
registries.
Operations

The operations exposed by the WSDL identified in the WSDL URL field. When you
select an operation, the parameter names and types and the SOAP request associated
with that operation are displayed in the right side of the Web service call composer.
Name

The SOAP request parameter name.

Type

The SOAP request parameter type.

Value

The SOAP request parameter value. You can enter a value in this field, or directly in
the SOAP request XML.

For More Information

UDDI Registry Browser on page 1447

Stylus Studio User Guide

1453

Stylus Studio GUI Reference

WSDL Editor
The WSDL Editor is available only in Stylus Studio XML Enterprise Suite.
You use the WSDL (Web Services Description Language) Editor to review and edit
WSDL documents in Stylus Studio. The WSDL Editor consists of a Diagram tab, which
itself is made up of

A diagram pane

A text pane
A Properties window, which can be opened and closed using the View > Properties
choice on the Stylus Studio menu, displays properties for the selected WSDL or XML
Schema element.

For More Information

Diagram Pane
Text Pane
Properties Window
Symbols for WSDL Elements
Using the WSDL Editor on page 969
Working with WSDL Elements on page 978
Printing a WSDL Document on page 997
Saving the WSDL Diagram as an Image on page 997
Working with WSDL Documents on page 967
Similarities to the XML Schema Editor

1454

Stylus Studio User Guide

XML Diff Editor Merged View

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Merged View tab of the XML Diff Viewer to compare the changes in a pair
of source and target documents in a single window. Changed nodes are shown in pairs.

For More Information

Merged View on page 189
The XML Diff Viewer on page 186
Diffing a Pair of XML Documents on page 193
Diffing Multiple Documents on page 195

Stylus Studio User Guide

1455

Stylus Studio GUI Reference

XML Diff Editor Split View - Text

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Split View - Text tab of the XML Diff Viewer to compare the changes in a pair
of source and target documents in side-by-side windows. In text view, the source and
target documents are displayed in raw XML.

For More Information

Split View - Text on page 188
The XML Diff Viewer on page 186
Diffing a Pair of XML Documents on page 193
Diffing Multiple Documents on page 195

1456

Stylus Studio User Guide

XML Diff Editor Split View - Tree

XML Differencing is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the Split View - Tree tab of the XML Diff Viewer to compare the changes in a pair
of source and target documents in side-by-side windows. In tree view, the source and
target documents are displayed using node representation.

For More Information

Split View - Text on page 188
The XML Diff Viewer on page 186
Diffing a Pair of XML Documents on page 193
Diffing Multiple Documents on page 195

Stylus Studio User Guide

1457

Stylus Studio GUI Reference

XML Editor Grid Tab

The XML editor Grid tab is available only in Stylus Studio XML Enterprise Suite
and Stylus Studio XML Professional Suite.
The Grid tab of the XML Editor is a useful way to view and work with an XML document
that contains structured data multiple instances of the same type of element.
The Grid tab consists of a tool bar and a display area. The tool bar has buttons to perform
actions and operations on both the grid itself and on the underlying XML document
represented in the grid. An example of the former is the ability to show the child elements
of the documents root element; they are hidden by default. An example of the latter is the
ability to add a new instance of an element or to change a value. These operations are also
accessible from the XML > Grid Editing menu, as well as from the grid shortcut menu
(right-click on the grid).
The tool bar also includes a button ( ) that displays the XPath Query Editor window,
which allows you to enter an XPath expression to query the XML document. Results are
displayed in the Query Output window, which appears when you run the query if it is not
already displayed. See Querying XML Documents Using XPath for more information
on this feature.
The display area shows the XML document, both its structure and content, rendered in a
tabular, or grid format.

Buttons
Insert Row Before Inserts a new row before the current row.
Insert Row After Inserts a new row after the current row.
Delete Row Deletes the current row.
Move Up Moves the current row or table up in the diagram.
Move Down Moves the current row or table down in the diagram.
Add Nested Table Adds a nested table under the current row.
Add Attribute Column Adds an attribute column to the current row.
Add Element Column Adds an element column to the current row.
Rename Column Allows you to rename the current column.
Delete Column Deletes the current column.

1458

Stylus Studio User Guide

XML Editor Grid Tab

Sort Ascending Sorts the current column in ascending order.
Sort Descending Sorts the current column in descending order.
Simplified View Toggles the display of container nodes (nodes that have no content
of their own, such as the authors element in books.xml).
Toggle Row Tag Name Toggles the display of the rows tag name to preserve space

and simplify the display.

Use URIs to Compare Namespaces Whether or not you want Stylus Studio to use

URIs to compare namespaces.

For More Information

Using the Grid Tab on page 161

Stylus Studio User Guide

1459

Stylus Studio GUI Reference

XML Editor Schema Tab

To display the XML editor, open an XML document, or select File > New > XML
Document from the Stylus Studio menu bar. At the bottom of the XML editor window,
click the Schema tab.
The Schema tab of the XML editor displays a collapsible and expandable tree
representation of the schema for the current XML document. In this view, you can add
any kind of node allowed in a schema.

Buttons for Editing

The buttons along the top of the Schema tab allow you to edit the tree. Hover help is
available to determine what each button does.
Validate Document analyzes the document against the associated XML Schema or
DTD. You can use the drop-down list to select the validation engine you want to use.
IE Preview displays the XML document in the Preview window using the Internet
Explorer web browser.
Change Font allows you to choose the display font.
Open External Schema opens the schema, if there is one, for the XML document.
Delete Node deletes the selected node.
Change Name allows you to change the name of the selected node.
Move Up moves the selected node to be before its preceding sibling.
Move Down moves the selected node to be after its following sibling.
Toggle Display of White space toggles the display of white space in the tree.
Toggle Display of Entity References toggles the display of entity references in the
DTD associated with the document, if any.

Buttons for Adding Nodes

Buttons in the left tool bar of the Schema tab allow you to define elements, entities, and
comments in the schema. For a description of the buttons, see DTD Schema Editor Tree
Tab on page 1265 and XML Schema Editor Tree Tab on page 1478.

1460

Stylus Studio User Guide

XML Editor Schema Tab

To add a node, select a node that is already in the DOM tree, and then click the button for
the type of node you want to add. Stylus Studio adds the new node relative to the node
you selected.

For More Information

What Is a DTD? on page 666
Defining Elements in DTDs on page 671
About Modifiers in Element Definitions in DTDs on page 668
What Is an XML Schema? on page 568
Creating an XML Schema in Stylus Studio on page 568
About XML Schema Properties on page 648

Stylus Studio User Guide

1461

Stylus Studio GUI Reference

XML Editor Text Tab

To display the XML editor, open an XML document, or select File > New > XML
Document from the Stylus Studio menu bar.
Use the Text tab of the XML editor to enter new XML data or update existing data. The
usual editing tools are available to you. Right-click to display the editing shortcut menu.
Whenever Stylus Studio has enough information, it displays a shortcut menu of choices
for data you can input at that point. Double-click a value to enter it automatically. For
example, if you type an element end tag, Stylus Studio automatically displays the
appropriate element name.

Buttons
Indent XML Tags inserts tabs throughout the XML document if the document is wellformed XML. If it is not well formed, clicking this button does nothing.
Validate Document validates your XML document against its DTD.
Change Font changes the font of the text display in Stylus Studio. This change affects

only the Stylus Studio display. Beyond personal preference, this is useful for localization.
The fonts that are available are the fonts that can display the characters in your XML file.
Open Schema opens the schema, if there is one, for the XML document.

For More Information

Updating an XML Document Getting Started on page 10
Creating XML Documents on page 138
Validating XML Documents on page 208
Querying XML Documents Using XPath on page 210

1462

Stylus Studio User Guide

XML Editor Tree Tab

To display the XML editor, open an XML document, or select File > New > XML
Document from the Stylus Studio menu bar. At the bottom of the XML editor window,
click the Tree tab.
The Tree tab of the XML editor displays a collapsible and expandable DOM tree
representation of your XML document. In this view, you can add any kind of node and
specify values for nodes.
To expand a tree so that you can see all the nodes in the tree, click the root node and then
press the asterisk (*) key in the numeric key pad. To expand any particular node, click that
node and press * in the numeric key pad.

Buttons for Editing

The buttons along the top of the Tree tab allow you to edit the tree. Hover help is available
to determine what each button does.
If hover help is not enabled, you can turn it on as follows:
1.

Select Tools > Customize.

Click Show Tooltips and click OK.

The buttons are as follows:

Validate Document analyzes the document against the associated XML Schema or
DTD. You can use the drop-down list to select the validation engine you want to use.
IE Preview displays the XML document in the Preview window using the Internet
Explorer web browser.
Change Font allows you to choose the display font.
Open External Schema opens the schema, if there is one, for the XML document.
Delete Node deletes the selected node.
Change Name allows you to change the name of the selected node.
Move Up moves the selected node to be before its preceding sibling.
Move Down moves the selected node to be after its following sibling.
Toggle Display of White space toggles the display of white space in the tree.

Stylus Studio User Guide

1463

Stylus Studio GUI Reference

Toggle Display of Entity References toggles the display of entity references in the

DTD associated with the document, if any.

Show XPath Query Editor toggles the display of XPath Query Editor window.

Buttons for Adding Nodes

The buttons along the left side of the Tree tab allow you to add the various types of nodes.
Move the cursor over each button to determine which type of node it adds.
To add a node, select a node that is already in the DOM tree, and then click the button for
the type of node you want to add. Stylus Studio adds the new node relative to the node
you selected.
New Element adds a new element node. Specify the name, and the value if you want.
New Attribute add a new attribute node. Specify the name, and the value if you want.
New Text adds a new text node. Enter the data you want the text node to contain.
New CDATA adds a new CDATA node. Enter the data you want the CDATA node to

contain.
New Comment adds a new comment node. Enter the comment.
New Processing Instruction adds a new processing instruction. Specify a name for
the processing instruction, and then specify the instruction.
New Entity Reference adds a new reference to an entity defined in the schema for this

document.

For More Information

Updating DOM Tree Structures on page 157

1464

Stylus Studio User Guide

XML Pipeline Editor Canvas

XML Pipeline is available only in Stylus Studio XML Enterprise Suite.
You use the XML Pipeline Editor canvas to build an XML pipeline and work with the
resulting diagram of the XML pipeline. For example, you can use the canvas to

Start the process of adding the nodes that make up your XML pipeline. You can do
this by dragging an XQuery or XSLT document, for example, from the Project
window and dropping it onto the canvas, or by dragging an icon representing the
operation you want to add from the Toolbox pane and dropping it onto the canvas.

Link one XML pipeline node to another.

Modify the layout of the nodes representing XML pipeline operations.

Annotate XML pipeline operations or the XML pipeline itself.

Properties for the nodes you add, and for their input ports and output ports, are specified
in the Properties window.

For More Information

Working with the XML Pipeline Diagram
Parts of the XML Pipeline Editor
Steps for Building an XML Pipeline
Planning an XML Pipeline

Stylus Studio User Guide

1465

Stylus Studio GUI Reference

XML Pipeline Settings

You use the XML Pipeline Settings page of the Options dialog box to specify settings for
XML Pipelines you create.

Fields
Execution Framework

Drop-down list that displays available execution frameworks. An execution

framework is a set of compatible processors for XQuery, XSLT, FO processing, and
validation.
Zoom Factor

Slider that controls the default zoom setting for new XML Pipelines.
Edge Style

Drop-down list that displays available styles for XML Pipeline edges. The default is
Line.
Degubbing

The length at which you want to truncate summaries of debug variable values
displayed in the Watch and Variables debug windows.

For More Information

The XML Pipeline Editor
Working with the XML Pipeline Diagram
Debugging an XML Pipeline
Steps for Building an XML Pipeline

1466

Stylus Studio User Guide

XML Publisher Canvas

XML Publisher is available only in Stylus Studio XML Enterprise Suite.
You use the XML Publisher canvas to design XML reports. The data sources panel, which
appears to the right of the canvas, displays the data sources you have selected. You choose
the data you want to include in your report by dragging nodes from your data sources and
dropping them on the canvas. When you drop, Stylus Studio displays a short-cut menu
that includes components you can add based on the type of node (repeating or nonrepeating) you have chosen. This process lets you create tables, lists, and other report
components quickly and easily. Once you have incorporated data, you use the tools in the
XML Publisher toolbar or in the Properties window to specify formatting.

Navigation Bar
The navigation bar contains glyphs that identify the hierarchy of the component in your
report that currently has the editors focus. You can use the navigation bar to move the
focus from one area of the report to another; similarly, the glyphs in the navigation bar
change when you place the text cursor in a different part of the report.

Figure 602. XML Publisher Navigation Bar

Figure 602 shows that the dynamic value within a table cell currently has focus. All
components occur within the body component; the glyph for the body component always
appears first.

Stylus Studio User Guide

1467

Stylus Studio GUI Reference

Toolbar
The buttons in the XML Publisher toolbar let you specify formatting for the component
or piece of text in the canvas that has focus. It also lets you preview the report and generate
code for it.

Figure 603. XML Publisher Toolbar

For More Information

The XML Publisher Canvas
Parts of the XML Publisher Editor
Building an XML Publisher Report

1468

Stylus Studio User Guide

XML Publisher Data Sources Panel

XML Publisher is available only in Stylus Studio XML Enterprise Suite.
You use the data sources panel to identify the sources (relational tables and XML
documents, for example) whose data you want to include in your finished report. You
select the data you want in your report by dragging the nodes that represent the data from
the data sources panel and dropping them on the XML Publisher canvas.

Buttons
The buttons on the data sources panel let you add and remove data sources, choose the
data source you want to use as the default, create a relationship, and open a source
document in Stylus Studio.

Figure 604. Data Sources Panel Buttons

Fields
Namespace/URI

If the document you have selected as a source uses a namespace prefix, Stylus Studio
displays the prefix and the URI at the bottom of the data sources panel. You can
change the value in the Namespace field and use the renamed prefix in the XPath
expressions you define in the Properties window.

For More Information

Adding a Data Source
How Data Sources are Represented in XML Publisher
Stylus Studio User Guide

1469

Stylus Studio GUI Reference

Working with Data Sources

Parts of the XML Publisher Editor
Building an XML Publisher Report

1470

Stylus Studio User Guide

XML Publisher Namespaces Pane

XML Publisher is available only in Stylus Studio XML Enterprise Suite.
If the document you have selected as a data source uses a namespace prefix, Stylus Studio
displays the prefix and the URI at the bottom of the data sources panel. You can change
the value in the Namespace field and use the renamed prefix in the XPath expressions you
define in the Properties window.

Figure 605.

For More Information

Working with Namespaces
Adding a Data Source
How Data Sources are Represented in XML Publisher
Working with Data Sources
Parts of the XML Publisher Editor
Building an XML Publisher Report

Stylus Studio User Guide

1471

Stylus Studio GUI Reference

XML Report Format

You use the XML Report Format dialog box to choose the format for the XML report you
create using XML Publisher. You can choose

HTML (XHTML+CSS)

PDF (XSL-FO)

For More Information

Choosing a Report Format
Building an XML Publisher Report
Generating Code for an XML Publisher Report

1472

Stylus Studio User Guide

XML Schema Editor Diagram Tab

The Diagram tab displays a graphical view of an XML Schema. You can use the Diagram
tab to create a new XML Schema or to review and edit an existing XML Schema.
The Diagram tab contains a definition browser, above the diagram canvas, which allows
you to jump to a specific node definition within the XML Schema. See Definition
Browser on page 75 for more information on this topic.
Beneath the diagram canvas is the text pane. The text pane displays the XML Schema
code represented by the nodes you create in the diagram. Stylus Studio synchronizes these
two views of the XML Schema any changes you make in the diagram are reflected in
the text pane, and vice versa. See Text Pane on page 73 for more information on this topic.
When you display the Diagram tab, Stylus Studio also displays the Properties window by
default, which shows details about the selected node in the diagram. You can close the
Properties window to gain more space for the diagram itself.
Other views of your XML Schema are presented in the following tabs:

Tree Displays a tree representation of the XML Schema. XML Schema Editor Tree
Tab.

Documentation Provides documentation about the XML Schema. XML Schema

Editor Documentation Tab.

Fields
Properties

The Properties window displays the properties for the selected node in the diagram.
Click a node to view its properties. The properties that appear vary according to the
node you select. See About XML Schema Properties on page 648.

Buttons
Indent XML Tags inserts tabs throughout the XML document if the document is wellformed XML. If it is not well formed, clicking this button does nothing.
Check Well-formed verifies that the document is well-formed XML.

Stylus Studio User Guide

1473

Stylus Studio GUI Reference

Validate Document determines whether your schema document is valid XML. If it is

not, Stylus Studio displays a message that indicates the location and cause of each error.
Change Font changes the font of the text in the XML Schema Editor diagram pane.

Beyond personal preference, this is useful for localization. The fonts that are available are
the fonts that can display the characters in your XML file.
Back returns the XML Schema diagram to the previous page.
Forward reopens the previously viewed page.
Display Definition Displays the definition of the currently selected node on a new
page within the diagram.
Go to Definition Scrolls to the definition of the currently selected node within the
current view of the XML Schema.
Simplify Diagram Hides annotation, documentation, simpleContent,
complexContent, and anonymous complexTypes from the diagram.
Add Allows you to add a new node to the XML Schema.
Insert Before Allows you to add a new node to the XML Schema prior to the
currently selected node.
Insert After Allows you to add a new node to the XML Schema after the currently

selected node.
QuickEdit Automatically performs basic editing operations (changing a sequence

node to a choice or any node, for example); available operations change based on the
currently selected node.
Move Down Moves the selected node down one position on the current branch.
Move Up Moves the selected node up one position on the current branch.

1474

Stylus Studio User Guide

XML Schema Editor Diagram Tab

Delete Deletes the selected node and its children.

Zoom in and zoom out

For More Information

Introduction to the XML Schema Editor Diagram Tab on page 67
Defining an XML Schema Using the Diagram Tab Getting Started on page 66
What Is an XML Schema? on page 568
Creating an XML Schema in Stylus Studio on page 568

Stylus Studio User Guide

1475

Stylus Studio GUI Reference

XML Schema Editor Documentation Tab

The XML Schema editor Documentation tab is available only in Stylus Studio XML
Enterprise Suite and Stylus Studio XML Professional Suite.
The Documentation tab displays an HTML report that describes the currently active XML
Schema. Stylus Studio generates this report based on the contents of your XML Schema
though features are provided that allow you to modify the reports content. You can view
the report online, save the report, and print it.

Buttons
Save Documentation allows you to save the report in a file. By default, the report is
saved with a .html extension, but you can change the default in the Options dialog box.
(You can also change the extension at the time you save the report in the Save As dialog
box.) See Options - Module Settings - XML Schema Editor - Documentation on
page 1358 for more information.
Options displays a dialog box that allows you to set properties that determine some
of the contents and behavior of the HTML file. See Options - Module Settings - XML
Schema Editor - Documentation on page 1358 for more information.

As you click links in the report, Stylus Studio maintains a history of the links you
follow. Back returns the focus to the previously followed link.
Forward returns the focus to the link you followed from this link.
Stop allows you to halt Stylus Studio processing of the generated HTML report.

Report Contents
The report contains

A title, which you can customize (the default title is XML Schema Documentation).

A table of contents with hypertext links to sections in the report.

Information about the XML Schema document properties, such as its target
namespace and any declared namespaces.

Global declarations and global definitions, if any.

A legend that describes the graphical conventions used to display the XML Schema
document in the report. The legend uses a fictitious type declaration for example
purposes.

1476

Stylus Studio User Guide

XML Schema Editor Documentation Tab

Tip

A glossary that defines terminology used in the report.

You can hide the legend and the glossary for display and printing purposes by
clicking the Printer-friendly Version check box at the top of the report.

For More Information

Generating Documentation for XML Schema on page 643
Creating an XML Schema in Stylus Studio on page 568

Stylus Studio User Guide

1477

Stylus Studio GUI Reference

XML Schema Editor Tree Tab

To display the XML Schema editor, open an XML Schema document, or select File > New
> XML Schema from the Stylus Studio menu bar. At the bottom of the XML Schema
editor window, click the Tree tab.
The Tree tab displays a DOM tree representation of the schema. To expand a tree so that
you can see all the nodes in the tree, click the root node and then press the asterisk (*) key
in the numeric key pad. To expand any particular node, click that node and press * in the
numeric key pad.
When you display the Tree tab, Stylus Studio also displays the Properties window. You
can edit the list of properties or the tree. Any changes you make in one window are
immediately reflected in the other window.

Fields
Properties

The Properties window displays the properties for the selected DOM tree node. Click
a node in the DOM tree to view its properties. The properties that appear vary
according to the type of node you select. See About XML Schema Properties on
page 648.
To edit properties in the Properties window, double-click the value you want to
change. For some properties, Stylus Studio displays a shortcut menu of possible
values. Double-click the value you want. For other properties, you must type the new
value, and press Enter.

Buttons for Editing

Refresh the tree display.
Delete the selected node.
Change the name of the selected node.
Change the value of the selected node.
Move the selected node up.
Move the selected node down.

Toggle the display of white space.

Validate the XML Schema document.

1478

Stylus Studio User Guide

XML Schema Editor Tree Tab

Change the font used to display text in the XML Schema editor.
Open Schema opens the schema, if there is one, for the XML document.

Buttons for Adding Nodes

Table 201 describes the buttons in the left tool bar of the Tree tab. These buttons allow you
to define elements, attributes, model groups, attribute groups, complex types, simple
types, and documentation.
Table 201. Tree Tab Button Descriptions
Button

Description of New Node

New Element Definition

Click the Schema node or a model group node (all, any, choice, or sequence)
and then click this button to define a new element as a child of the selected node.
New Attribute Definition

Click the Schema node, a complex type node, or an attribute group node, and
then click this button to define an attribute name. This attribute is associated
with the node that was selected when you clicked New Attribute.
New Group

Click the Schema node, a complex type node, or a model group node, and then
click this button to define a new model group. The group can contain new
definitions of elements, references to previously defined elements, nested
definitions of groups of elements, or references to groups of elements.
New Attribute Group

Click the Schema node or a complex type node, and then click this button to
define a new attribute group. The group can contain new definitions of
attributes, references to previously defined attributes, definitions of new
attribute groups, or references to attribute groups.

Stylus Studio User Guide

1479

Stylus Studio GUI Reference

Table 201. Tree Tab Button Descriptions
Button

Description of New Node

New Model Group

Click a complex type node or a group node, and then click this button to specify
a model group. A model group specifies the occurrence rules for the elements
that you add as children of the model group node. Specify one of the following
values:

all specifies that each element must appear exactly zero or one time. The
elements can appear in any order. In an instance document, the children of
the group or complex type can include 0 or 1 instance of each element.

choice specifies that exactly one element can be present, and there must be

only one instance of that element. In an instance document, exactly one

element can be a child of the group or complex type.

sequence specifies there must be exactly one instance of each element and

the elements must appear in the order in which they are specified in the
schema. In an instance document, each element must appear once. They
must have the same order they have in the schema.
Another value you can specify is any. When you specify any, you do not
add any element definitions or references to elements. As the name
implies, any element can appear any number of times.
New Simple Type
Click the Schema node, an element node, an attribute node, a list node,
or a union node, and then click this button to define a simple type. An
element that contains only data is a simple type. Attributes are always
simple types.
New Complex Type
Click the Schema node or an element node, and then click this button to define
a complex type. An element that contains anything more than raw data is a
complex type.
New Restriction
Click a simple type node and then click this button to specify the base type for
the simple type.
New Extension
Click a content node and then click this button to specify the base type that this
complex type extends.

1480

Stylus Studio User Guide

XML Schema Editor Tree Tab

Table 201. Tree Tab Button Descriptions
Button

Description of New Node

New Content
Click a complex type node and then click this button to specify simpleContent
or complexContent. Specify simpleContent if the type contains only text.
Otherwise, specify complexContent.
New Aggregator
Click a simple type node and then click this button to specify list or union. A
list aggregator indicates that the contents of the simple type must all be of the
same type. A union aggregator indicates that the contents of the simple type
can be of different types.
New Facet
Click a restriction node and then click this button to specify a facet that
narrows the allowable set of values for the simple type.
New Notation
Click the Schema node and then click this button to define an unparsed entity.
New Include
Click the Schema node and then click this button to include another XML
Schema in this XML Schema. The included schema augments the including
schema. Both schemas must have the same target namespace.
New Import
Click the Schema node and then click this button to import another XML
Schema into this XML Schema. The importing schema can reference the
imported schema. The two schemas must have different target namespaces.
New Redefine
Click the Schema node and then click this button to include another XML
Schema but with some redefinitions. A Redefine node is a variation of an
Include node.
New Identity Constraint
Click an element node and then click this button to define an identity constraint.
The type of an identity constraint is unique, key, or keyref.

Stylus Studio User Guide

1481

Stylus Studio GUI Reference

Table 201. Tree Tab Button Descriptions
Button

Description of New Node

New Selector/Key
Click an identity constraint node and then click this button to define the selector
or key for the identity constraint.
New Reference to Element

Click a model group node (all, any, choice or sequence), and then click this
button to specify an element that the parent element of the model group node
can contain.
New Reference to Attribute
Click a complex type node, and then click this button to add a reference to an
attribute.
New Reference to Group
Click a complex type node or a model group node (all, any, choice,
sequence), and then click this button to add a reference to a group.
New Reference to Attribute Group
Click a complex type node or an attribute group node, and then click this button
to add a reference to an attribute group.
New Annotation
Click any node to add an annotation node. An annotation node indicates the
beginning of some documentation.
New Documentation
Click an annotation node to add documentation. You can include text, a URL, a
file path.
New Text

Click a documentation node to add a text node.

New Comment

Click any node to add a comment node.

For More Information

Creating an XML Schema in Stylus Studio on page 568
1482

Stylus Studio User Guide

XML Schema Editor Tree Tab

What Is an XML Schema? on page 568

Defining simpleTypes in XML Schemas on page 599
Defining complexTypes in XML Schemas on page 609
Defining Elements and Attributes in XML Schemas on page 619
Defining Groups of Elements and Attributes in XML Schemas on page 628
Adding Comments, Annotation, and Documentation Nodes to XML Schemas on
page 632

Stylus Studio User Guide

1483

Stylus Studio GUI Reference

XPath Editor
XML Publisher is available only in Stylus Studio XML Enterprise Suite.
You use the XPath Editor dialog box to write the XPath expressions you want to use for
the XPath sub-property. Together, the Context and XPath sub-properties let you define the
conditions under which you want to, say, display a value or apply a given formatting
characteristic. You can use the Color propertys Context and XPath sub-properties to
format text based on the value returned by an XPath expression format all R rated
movies in videos.xml using the color red, for example. (See Example: Using Context and
XPath Sub-Properties to Format Text for an illustration of this technique.)

For More Information

Entering XPath Expressions
Component Properties
Working with Report Components
Building an XML Publisher Report

1484

Stylus Studio User Guide

XPath Query Editor

You use the XPath Query Editor to compose and execute queries against the active XML
document. If the XPath Query Editor is not visible, select View > XPath Query Editor
from the Stylus Studio menu, or click the Show XPath Query Editor button on the XML
Editor tool bar (
).
The XPath Query Editor consists of

A query pane, in which you enter the XPath you want to execute against the current
document

A namespace pane, which allows you to redefine the namespace prefix to be used in
the query. The namespace pane is not displayed by default.
You can create up to sixty-four queries for a single XML document; each is saved on its
own tab, which appears at the top of the query pane. To see a different query, click the
appropriate tab. To delete a query, click the Delete Query button.

Tool Bar
New XPath Query creates a new query tab in the XPath Query Editor.
Execute Query executes the current query in the XPath Query Editor.
Open result in a new XML document creates a new XML document based on the

query result and displays it in the XML Editor.

Show Namespaces displays the namespace pane, which allows you to redefine the

namespace prefix to be used in the query.

Delete Query deletes the current query from the XPath Query Editor.

For More Information

Using the XPath Query Editor on page 694
Querying XML Documents Using XPath on page 210

Stylus Studio User Guide

1485

Stylus Studio GUI Reference

XPath for xsl: Elements

This dialog box displays the XPath expression used to define the select= statements in an
XSLT stylesheet. It available by selecting Properties from the shortcut menu for the
following xsl: element blocks in the XSLT mapper:

xsl:apply-template

xsl:choose
xsl:if

xsl:for-each

xsl:value-of

For More Information

Creating XSLT Using the XSLT Mapper on page 507

1486

Stylus Studio User Guide

XQuery Editor

XQuery Editor
XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You use the XQuery editor to work with XML files in Stylus Studio.

For More Information

Creating an XQuery Scenario on page 900
Getting Started with XQuery in Stylus Studio on page 782

Stylus Studio User Guide

1487

Stylus Studio GUI Reference

XQuery Editor XQuery Source Tab

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
You can use the XQuery editor XQuery Source tab to view, edit, and compose XQuery
code. You can edit the XQuery in the same way you can edit any other XML document.
The usual editing tools are available to you, and Stylus Studios Sense:X feature is
supported.
To display the XQuery editor, open an XQuery file, or select File > New > XQuery File
from the Stylus Studio menu bar. At the bottom of the XQuery editor window, click the
XQuery Source tab.

Fields
Create Scenario

A scenario allows you to preview the results of applying an XQuery. Scenario settings
include the name of an XML source document, the values of any parameters in the
XQuery script, and the type of performance metrics you want Stylus Studio to
capture, if any. XQuery scenarios are optional.
To create a scenario, click
to the right of the scenario name field. After you create
the first scenario, the name of the current scenario appears in this field.
Click the down arrow to select a previously defined scenario. Click Preview Result
to apply the XQuery in the context of the selected scenario. Stylus Studio
displays the results of applying the XQuery in the Preview window.

Buttons
Preview Result applies the XQuery in the context of the current scenario.
Change Font changes the font of the text display in Stylus Studio. This change affects
only the Stylus Studio display. Beyond personal preference, this is useful for localization.
The fonts that are available are the fonts that can display the characters in your XML file.

displays the Scenario Properties dialog box. Use this dialog box to define a new
scenario, update the settings for a scenario, or view information about a scenario.

1488

Stylus Studio User Guide

XQuery Editor XQuery Source Tab

For More Information

Building an XQuery Using the Mapper on page 813
Working with Relational Data Sources on page 850
Creating an XQuery Scenario on page 900
XQuery Editor Mapper Tab on page 1490

Stylus Studio User Guide

1489

Stylus Studio GUI Reference

XQuery Editor Mapper Tab

XQuery support is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio XML Professional Suite.
The XQuery mapper allows you to construct an XQuery graphically, without writing any
code, by mapping elements from one or more source documents to a target structure.
Stylus Studio uses these source/target mappings to define an XQuery that returns a
document that conforms to the target structure you build.
Nodes on the target structure can be inferred from an existing document, or you can create
them (either from scratch or by copying source document nodes to the target structure).

How to Map
To map a source document node to an existing target structure node, drag and drop the
source element using the left mouse button.
To use a source document node to create a new node on the target structure, drag and drop
the source element using the right mouse button and select one of the following operations
from the shortcut menu:

Add Attribute and Map It

Add Child Element and Map It
Insert Element After and Map It
Copy Node

Fields
Create Scenario

A scenario allows you to preview the results of applying an XQuery. Scenario settings
include the name of an XML source document, the values of any parameters in the
XQuery script, and the type of performance metrics you want Stylus Studio to
capture, if any. XQuery scenarios are optional.
To create a scenario, click
to the right of the scenario name field. After you create
the first scenario, the name of the current scenario appears in this field.
Click the down arrow to select a previously defined scenario. Click Preview Result
to apply the XQuery in the context of the selected scenario. Stylus Studio displays
the results of applying the stylesheet in the Preview window.
Source file name

1490

Stylus Studio User Guide

XQuery Editor Mapper Tab

Click here to change the name of the source XML document you want to use to
perform the mapping. When the mapping is complete, you will have a stylesheet that
you can apply to documents that have the same schema as this document.
Destination file name

Click here to change the name of the target XML document you want to use to
perform the mapping. When the mapping is complete, you will have a stylesheet that
generates XML documents that have the same schema as this document.

Buttons
Preview Result runs the XQuery. Information from the current scenario is used to run
the XQuery if a scenario has been created.
Change Font changes the font of the text display in Stylus Studio. This change affects
only the Stylus Studio display. Beyond personal preference, this is useful for localization.
The fonts that are available are the fonts that can display the characters in your XML file.

displays the Scenario Properties dialog box. Use this dialog box to define a new
scenario, update the settings for a scenario, or view information about a scenario.
Add Source Schema displays the Open dialog box and lets you select a source document

for the XQuery mapper. Stylus Studio uses the first document you select as the default
source XML for the scenario. You can use multiple sources in the XQuery mapper.
Set Target Schema displays the Open dialog box so you can select a target document for
the XQuery mapper. You can create a target document from scratch right click in the Set
Target Schema canvas and select Create Root Element.

For More Information

Building an XQuery Using the Mapper on page 813
Creating an XQuery Scenario on page 900
XQuery Editor XQuery Source Tab on page 1488

Stylus Studio User Guide

1491

Stylus Studio GUI Reference

XQuery Editor Plan Tab

The Plan tab is available only in Stylus Studio XML Enterprise Suite, and only if
you are using the DataDirect XQuery processor.
The Plan tab displays the graphic representation of a query plan. The query plan provides
details of how DataDirect XQuery will execute the query for which the plan was
generated. The query plan tree diagram is read-only, though it does provide navigation
and formatting features. You can also print and save the query plan as HTML

For More Information

Example of a Query Plan on page 895
Parts of a Query Plan on page 896
Using DataDirect XQuery Execution Plans on page 895

1492

Stylus Studio User Guide

xsl:choose

xsl:choose
You use the xsl:choose dialog box to

Add, edit, or remove test= attributes from xsl:choose instructions.

Edit the setting that generates the xsl:otherwise element.

Changes you make here are reflected in the mapper (and the XSLT source), and vice
versa.

Fields
xsl:when Conditions

List box that displays existing test= attributes of xsl:when conditions).

To add a new xsl:when condition, click the Add button and type a valid test= attribute
in the entry field.
Note

Just type the attributes value. For example, if you want this xsl:when expression,
<xsl:when test="books/book/authors/author">, you would just type
books/book/authors/author in the entry field. Note the absence of the quotation
marks.
Include xsl:otherwise

A check box used to indicate whether or not you want to include the xsl:otherwise
element in the xsl:choose instruction. The xsl:otherwise element is included in the
xsl:choose instruction by default when you create xsl:choose in the XSLT mapper.
If you deselect this check box, the xsl:otherwise port (the square port) is removed
from the xsl:choose block (and from the XSLT source).

For More Information

Creating XSLT Using the XSLT Mapper on page 507

Stylus Studio User Guide

1493

Stylus Studio GUI Reference

XSLT Editor Mapper Tab

The XSLT Mapper is available only in Stylus Studio XML Enterprise Suite and
Stylus Studio Professional Suite.
To display the XSLT mapper, open an XSLT stylesheet that was created by the XSLT
mapper, or select File > New > XSLT Stylesheet from the Stylus Studio menu bar and then
click the Mapper tab.
The XSLT mapper allows you to map the schema of an XML file to the schema of another
XML file. This is useful when you have more than one form for the same information. For
example, each vendor might organize an invoice in a different way. Mapping one XML
document to another XML document is for XML documents that share similar elements.
When you map one XML file to another XML file, one file is the source document and
one file is the destination document. Stylus Studio generates a stylesheet that you can
apply to XML documents that have the same schema as the source document. After you
apply the stylesheet, the result document has the same schema as the destination
document.

Fields
Create Scenario

To create a scenario, click Scenario Properties

to the right of the Create
Scenario field. You must define a scenario to be able to apply the stylesheet Stylus
Studio is creating. After you create the first scenario, the name of the current scenario
appears in this field.
Click the down arrow to select a previously defined scenario.
Source file name

1494

Stylus Studio User Guide

XSLT Editor Mapper Tab

Buttons
Preview Result applies the stylesheet in the context of the current scenario.
Scenario Properties displays the Scenario Properties dialog box. Use this dialog

box to define a new scenario, update the settings for a scenario, or view information about
a scenario.
Open XML From Scenario opens the XML document specified as the source
document in the current scenario. Stylus Studio displays the source document in the XML
editor.
Display Preview Window toggles the display of the XSLT Preview window.

For More Information

Overview of the XSLT Mapper on page 508
Steps for Mapping XML to XML on page 515

Stylus Studio User Guide

1495

Stylus Studio GUI Reference

XSLT Editor Params/Other Tab

The Params/Other tab is available in the XSLT editor and in the XSLT mapper. Use this
tab to specify the output method, stylesheet and result document encoding, and stylesheet
parameters.
To display the XSLT editor, open an XSLT stylesheet, or select File > New > XSLT
Stylesheet from the Stylus Studio menu bar. At the bottom of the XSLT editor window,
click the Params/Other tab.

Fields
XSLT Encoding

Specifies the encoding for the stylesheet. The default is UTF-8. Click the down arrow
to display a list of encodings that you can choose.
Output method

Specifies the format for a document that is the result of applying this stylesheet. The
default is HTML. Click the down arrow to select from html, xml, text, or unspecified.
When unspecified is selected, and there is no xsl:output instruction in the stylesheet,
the output method is XML.
When the output is XHTML, specify XML as the Output method. Stylus Studio
displays the result as rendered HTML in the Preview in Browser view of the XSLT
Preview window.
Output Encoding

Specifies the encoding for a document that is the result of applying this stylesheet.
The default is UTF-8. Click the down arrow to display a list of encodings that you can
choose.
Indent

When selected, Stylus Studio inserts indents in the result document.

Read-only list of global parameters

This read-only field displays the parameters in your stylesheet, and their default
values. You can right-click a parameter to jump to its definition in the stylesheet.
The parameter information also specifies the source file that defines the parameter.
This is especially helpful when you have a chain of included or imported stylesheets.
In this situation, the source file that defines a parameter might not be obvious.

1496

Stylus Studio User Guide

XSLT Editor Params/Other Tab

For More Information

Specifying Stylesheet Parameters and Options on page 416

Stylus Studio User Guide

1497

Stylus Studio GUI Reference

XSLT Editor XSLT Source Tab

The XSLT Source tab displays the entire stylesheet in the XSLT editor. You can edit the
stylesheet in the same way you can edit any other XML document. The usual editing tools
are available to you. As you type, Stylus Studio displays a pop-up menu from which you
can select the item you want to specify.
To display the XSLT editor, open an XSLT stylesheet, or select File > New > XSLT
Stylesheet from the Stylus Studio menu bar. At the bottom of the XSLT editor window,
click the XSLT Source tab.

Fields
Create Scenario

To create a scenario, click Scenario Properties

Buttons
Indent XML Tags inserts tabs throughout the XSLT stylesheet if the stylesheet is well-

formed XML. If it is not well formed, clicking this button does nothing.
Change Font changes the font of the text display in Stylus Studio. This change affects

only the Stylus Studio display. Beyond personal preference, this is useful for localization.
The fonts that are available are the fonts that can display the characters in your XML file.
Add a New Template creates a new template. Specify the match pattern in the Match

field.
Delete the Template deletes the selected template.
Preview XSLT Result applies the stylesheet in the context of the current scenario.
Scenario Properties displays the Scenario Properties dialog box. Use this dialog
box to define a new scenario, update the settings for a scenario, or view information about
a scenario.

1498

Stylus Studio User Guide

XSLT Editor XSLT Source Tab

Open XML From Scenario opens the XML document specified as the source

document in the current scenario. Stylus Studio displays the source document in the XML
editor.
Display Preview Window toggles the display of the XSLT Preview window.
Source Tree toggles the display of the tree representation of the XML source

document specified in the current scenario. Expand and collapse the tree as needed.
Double-click a node to create a template that matches that node. Stylus Studio displays a
check mark next to nodes that have matching templates.
Full Source mode displays the entire stylesheet.
Template mode displays the template you select. Click the down arrow in the upper
right corner of the XSLT editing pane to display a list of templates.

For More Information

Working with Stylesheets on page 413
What Is XSLT? on page 378
Overview of the XSLT Mapper on page 508
Steps for Mapping XML to XML on page 515

Custom XML Conversions module

EDI message types
creating custom message types 277
EDI to XML module
video demonstration 315
EDI to XML Schema document wizard
running 579
supported EDI dialects 577
EDI to XSD document wizard
running 579
supported EDI dialect 577
EDIFACT
creating XML Schema from 577
creating XML Schema from EDIFACT message types 579
message types supported in Stylus Studio 276
EDIFACT files
XML Converter properties for 375
EDIFACT to XML Schema document wizard
built-in EDI XML Converter and 280
uses for XML Schema 280
Edig@s
creating XML Schema from Edig@s message types 579
message types supported in Stylus Studio 276
Edig@s files
XML Converter properties for 375
editing XML
auto-completing tags and fragments 145
bookmarks 148
changing fonts 148
colors used in text display 149
commenting text 148
diffing 176
displaying line numbers 12
displaying white space in schema representations 25
features for 144
indenting text 146

Stylus Studio X14 User Guide

HL7
creating XML Schema from HL7 message types 579
HL7 files
XML Converter properties for 375
HMS Separator data type property 310
Home Edition
description 4
HTML
automatic tag completion 428
converting to XML 140
creating with XML Publisher 1092
creating XML documents from 139
creating XSLT 415
I
IATA
creating XML Schema from 577
creating XML Schema from IATA message types 579
message types supported in Stylus Studio 276
IATA files
XML Converter properties for 375
IBM DB2
XQuery support for 852
id() function 757
IDs
finding elements with 757
public IDs for XML Schemas 635
system IDs for XML Schemas 635
temporary 769
IF blocks
in XQuery Mapper 839
images
creating in XML Publisher reports 1125
including in XML Schema documentation 646
import module statement
custom URI resolvers for 904
importing WSDL documents 994

Stylus Studio X14 User Guide

1519

including XML pipelines in other XML pipelines 1048

indenting tags 16
indenting text 146
Informix
XQuery support for 852
Input element in WSDL documents 991
input ports
in XQuery Mapper symbols 837
in XSLT Mapper symbols 530
instantiating templates
process flow 408
integer data type properties 302
integration
with TigerLogic XDMS 1163
J
Java 133
compiling code generated from XQuery 459, 937, 1074
configuring the JVM 133
defining functions in XSLT Mapper 540
deploying code generated from XML pipelines 1075
deploying code generated from XQuery 459, 937
dowloading Java components 134
extension functions for stylesheets 434
generating code from XQuery 933
generating code from XSLT 454
generating Java code for an XML pipeline 1069
how to generate Java code for an XML pipeline 1073
Stylus Studio modules that require Java components 133
Java Code Generation wizard for XQuery
about 933
compiling code from 1074
Java Code Generation wizard for XSLT
about 454
JavaScript in stylesheet results 396
JDK
configuring 133

1520

Stylus Studio X14 User Guide

1524

Stylus Studio X14 User Guide

Port element in WSDL documents 983

Port Type element in WSDL documents 986
position() function 753
POST data
using POST.htm to test queries 707
PostgreSQL
XQuery support for 852
post-processing XSLT 446
preceding axis 731
preceding-sibling axis 730
predicates
creating in XQuery Mapper 840
printing
WSDL documents 997
XML Schema 587
XML Schema documentation 647
processing-instruction() function 758
processors
for XQuery 902, 907
for XSLT 440, 546
profiling
XQuery
Profiler report 892
stylesheet for Profiler report 892
XSLT
Profiler report 546
stylesheet for Profiler report 558
projects
adding files to
ClearCase and 111, 113
creating 103
definition 100
opening 103
placing under source control 109
saving 103
setting classpaths for 107

Stylus Studio X14 User Guide

1525

SourceSafe and 111

subprojects and 103
Visual SourceSafe and 111
Zeus CVS and 116
properties
XML Publisher report components 1132
public IDs for XML Schemas 635
publisher
see XML Publisher
Q
qualified names
wildcards 763
queries
axis syntax 727
document element 702
document structure 701
function available? 766
getting started 707
IDs 757
multiple documents 770
non-XML data 694
query language
attributes 712
Boolean expressions 741
comparisons 747
context flags 724
context nodes 721
context summary 726
count 764
filtering results 715
filters 713
getting a subscript 753
getting all marked-up text 708
id() function 757
namespaces 761
node names 761

1526

Stylus Studio X14 User Guide

obtaining all like-named elements 708

operators 748
path operators 724
quick reference for functions and methods 772
search context 721
searching by node type 758
selecting nodes to evaluate 720
subscripts 752
wildcards 716
wildcards in attributes 713
restrictions 694
root node 702
sorting attributes 694
subqueries 715
temporary IDs 769
tutorial 707
variables 765
where you can use 692
query explain. see query plan
query facility 691
query plan
changing font size of 898
description 895
displaying 899
example 895
how to display 899
in Stylus Studio 895
navigating 897
saving as HTML 898
toolbar 898
tree structure 896
query plans
DataDirect XQuery and 895
R
Raining Data
see also TigerLogic

Stylus Studio X14 User Guide

1527

integration with Stylus Studio 1163

refactoring
using existing code to create user-defined functions 845
refactoring XML Schema nodes 79
regular expressions
reference 156
using Search to find 156
using to filter output of converted documents 257
xsdpattern and 600
relational data
connecting to a relational database 852
deleting records 878
inserting new records 869
querying with the collection() function 850
updating records 874
updating with DataDirect XQuery 866
XQuery Mapper and 814
relational databases
connecting to 852
XQuery support for 852
removing templates 440
Rendering data type property 292
reports
creating XML reports with XML Publisher 1092
formatting decimal numbers in XML Publisher reports 1141
saving an XML pipeline diagram as an image 1063
restrictions
queries 694
result documents
getting started with 41
Right Padding data type property 294, 298, 306, 308, 310
root element 702
definition 721
root node
creating matching template 410
default template 438

1528

Stylus Studio X14 User Guide

definition 722
matching template 406
root/element default template
description 438
example 406
round() function 747
S
saving documents
automatic save 211
creating backup copies 211
options for 211
Saxon
processing XQuery with 902
using Saxon to process XSLT 442
Scaling Factor data type property 291, 295, 296, 300, 301, 302, 303, 305, 307, 311
scenarios
definition 39
for Web service calls 960
for XQuery 900
performance metrics reporting 892
for XSLT 39
choosing an XSLT processor 546
how to clone 549
how to create 547
how to run 548
introduction 543
performance metrics reporting 546
setting parameter values 544
specifying source documents 543
XQuery
validating results 909
XSLT
validating results 445
search context
definition 721
queries 721

Stylus Studio X14 User Guide

1529

searching
text 148
using Find to search XML documents 156
using XPath to search for strings 734
SEF
support for in EDI XML Converters 277
select attribute
comparison with match attribute 385
description 384
when there is none 406
selecting lines of code 148
self axis 732
Sense:X
auto-completing tags and fragments 145
Sense:X automatic tag completion
description 13
Sense:X tag completion
XSLT and 428
Service element in WSDL documents 982
short data type properties 307
Signed data type property 295, 302, 303, 307
SOAP requests
modifying 951
parameters for 951
source control
Stylus Studio projects and 109
supported applications 110
SourceSafe
using with Stylus Studio 111
Spell Checker
personal dictionary 154
running 153
settings for 152
using 151
Standard Exchange Format
support for in EDI XML Converters 277

1530

Stylus Studio X14 User Guide

string data type properties 308

string() function 739
string-length() function 737
strings
after 736
before 735
concatenating 737
converting operands to 739
number of characters 737
replacing characters 738
searching for 734
substrings 736
Struzzo

command line utility for running Stylus Studio 128

stylesheets
applied by XSLT processors 385
applying
Stylus Studio 419
contents 382
contents description 426
creating 415
creating new nodes 392
example 379
for XML Schema documentation 644
for XQuery Profiler reports 892
for XSLT Profiler reports 558
formatting results 391
getting started with 33
introduction 379
namespaces 382
obtaining system properties 765
omitting source data 389
root element 382
selecting nodes for processing 387
Stylus Studio
debugging 551

Stylus Studio X14 User Guide

1531

updating
three-pane view 427
XSLT instructions 465
Stylus Studio
associating file types with 93
auto detect feature for Java components 135
benefits 397
building a converter URI using 274
command line for running 128
command line utilities for 128
debugging stylesheets 551
Diff tool 176
Home Edition description 4
managing performance 130
modules that require Java components 133
projects 100
registering custom tools 122
running from the command line 128
using with ClearCase 111, 113
using with SourceSafe 111
using with Visual SourceSafe 111
using with Zeus CVS 116
Web services and 943
XML validation command line utility 129
Stylus Studio Home Edition
description 4
StylusDiff 204
StylusValidator

command line XML validation utility 129

function 736
substring-after() function 736
substring-before() function 735
sum() function 746
Sybase
XQuery support for 852
symbols
substring()

1532

Stylus Studio X14 User Guide

element and attribute

in XQuery Mapper 820
in XSLT Mapper 522
lines linking nodes in XQuery Mapper 827
XLST function blocks
parts of 535
XLST Mapper
parts of 529
XQuery function blocks
parts of 837
XQuery Mapper
source 817
XSLT Mapper
document 519
XSLT mapper
XSLT instructions 529
system IDs for XML Schemas 635
system properties in stylesheets 765
system-property() function 765
T
tables
creating in XML Publisher reports 1119
templates
applying 440
backmapping in 557
built-in 390
contents description 383
creating 439
creating named and matched templates in XSLT Mapper 542
description of default templates 437
displaying match patterns 35
instantiation example 406
introduction 382
match attribute 385
matched templates in XSLT Mapper 542
matching root node 410

Stylus Studio X14 User Guide

1533

more than one match 390

named templates in XSLT Mapper 542
no match 390
removing 440
rules 384
select attribute 385
selecting for instantiation 384
updating 440
viewing 435
working with in XSLT Mapper 541
text
colors used to display 149
text blocks
creating in XML Publisher reports 1124
text files
converting to XML
Custom XML Conversions module 213
text pane
WSDL Editor 971
XML Schema Editor 583
text values
setting for elements and attributes in XQuery Mapper 824
setting for elements and attributes in XSLT Mapper
introduction 538
on the target node 539
using the Mapper canvas 538
text() function 758
text/attribute default template
description 438
example 408
Thousand data type property 304
three-pane view in Stylus Studio
result documents 41
TigerLogic XDMS
connecting to collections 1164
integration with Stylus Studio 1163

1534

Stylus Studio X14 User Guide

processing XQuery with 903

TigerLogicXDMS
creating collections in 1168
time data type properties 309
tool bars
changing appearance of Stylus Studio main tool bar 120
customizing Stylus Studio main tool bar 118
File Explorer tool bar 95
showing and hiding Stylus Studio main tool bar 119
XML Diff Viewer tool bar 190
tools
registering in Stylus Studio 122
TRADACOMS
creating XML Schema from TRADACOMS message types 579
message types supported in Stylus Studio 276
TRADACOMS files
XML Converter properties for 375
translate() function 738
Tree tab
XML Schema Editor 583
True Output As data type property 293
True Value Match List data type property 293
tutorial for queries 707
Types element in WSDL documents 980
U
UDDI registries
searching 947
Web services and 947
Unknown Output As data type property 294
unparsed-entity-uri() function 764
updating stylesheets 427
URIs
custom URI resolvers in XQuery 904
Use Currency Conventions data type property 306
user-defined field names
display in custom XML conversions editor 229

Stylus Studio X14 User Guide

1535

user-defined functions
creating 844
finding all occurrences of 848
finding the function declaration 849
in XQuery Mapper 838
library modules and 844
refactoring existing code as 845
renaming 849
V
validating
XML Schema 585
validating XML
custom validation engines for 1170
from the command line 129
standard validation engines for 1170
video demonstration 137
validation
using code lists to validate EDI 337
validation engines
in XML pipelines 1017
variables
finding all occurrences in XQuery code 848
finding the variable definition in XQuery code 849
renaming in XQuery code 849
variables in queries 765
video demonstrations
custom XML conversions 276, 1102
Custom XML Conversions module 213
diffing XML sources 176
EDI to XML module 315
Web Service Call Composer 943
XML editing and validation 137
XML Editor Grid tab 162
XML Pipeline Editor 999
XML Publisher 1091
XML Schema Diagram Editor 582

1536

Stylus Studio X14 User Guide

XPath Query Editor 695

XQuery Mapper lxix, 781
viewing templates 435
Visual SourceSafe
using with Stylus Studio 111
W
Web pages
creating from XML
three-pane view 401
Web Service Call Composer
video demonstration 943
Web service calls
specifying transport protocols for 961
Web services
creating a Web service call 944
invoking from an XQuery 919, 958
querying 921
saving Web service calls 955
scenarios for Web service calls 960
SOAP requests for 951
testing 953
using in Stylus Studio 943
using Web service calls as XML 955
WSDLs and 947
Web Services Description Language. See WSDL
white space
handling
XPath processor 738
XSL facility 392
toggling display in schema representations 25
wildcards
in queries 716
node names 761
Window for Two-Digit Year data type property 298
wizards
custom document wizards 1176

Stylus Studio X14 User Guide

1537

wrapping lines 147

wscall functions in XQuery Mapper 921
WSDL
Binding element 989
Definition element 979
displaying documentation element text 977
Documentation element 993
Fault element 993
Input element 991
Message element 984
Operation element 988
Output element 992
Part element 985
Port element 983
Port Type element 986
Service element 982
Types element 980
WSDL documents
creating 967
editor for 969
element symbols used in 973
error detection in 977
importing 994
printing 997
saving a diagram as an image 997
symbols used in 973
WSDL Editor
description 969
detecting errors in 977
diagram pane 971
displaying errors in text pane 977
text pane 971
WSDLs
displaying a WSDL document 952
finding WSDL URLs 947
searching UDDI registries for 947

1547

1548

Stylus Studio X14 User Guide

setting a default processor 907

using bookmarks 891
watching local variables 890
watching variables 889
XQuery processors
conflicts in XML pipeline 1045
in XML pipelines 1017
Saxon 902
selecting 902
setting a default processor 907
TigerLogic XDMS 903
XQuery Profiler
description 892
displaying the report 894
enabling 893
performance metrics captured by 893
report created by 892
XQuery scenarios
performance metrics reporting 892
XS3P stylesheet
display settings 646
displaying XML Schema documentation with 644
features 645
modifying 647
XSD
displaying documentation element text 72
xsd:pattern

regular expressions and 600

XSL
additional information sources 396
and XSLT 692
definition 378
example 379
formatting objects 447
getting started with 377
inserting JavaScript in result 396

Stylus Studio X14 User Guide

1549

patterns 393
XSL facility
creating new nodes 392
selecting source nodes 387
specifying XSL patterns 393
white space handling 392
XSL processor
applying stylesheets 385
built-in templates 390
specifying result format 391
URI 382
xsl:apply-imports instruction 467
xsl:apply-templates instruction
comparison with xsl:for-each instruction 395
controlling operation order 388
example 388
more than one match 390
no match 390
no select attribute 406
reference 467
selecting nodes 387
specifying patterns 393
xsl:attribute instruction 468
xsl:attribute-set instruction 469
xsl:call-template instruction 471
xsl:character-map instruction 471
xsl:choose

compared to xsl:if in XSLT Mapper 533

xsl:choose instruction 474
xsl:comment instruction 475
xsl:copy instruction 475
xsl:copy-of instruction 476
xsl:debug instruction 552
xsl:decimal-format instruction 477
xsl:element instruction 478
xsl:fallback instruction 479

1550

Stylus Studio X14 User Guide

instruction
comparison with xsl:apply-templates instruction 395
reference 479
selecting nodes 387
specifying patterns 393
xsl:for-each-group instruction 481
xsl:function instruction 482
xsl:for-each

1555

1556

Stylus Studio X14 User Guide

What Men Dont Want Women To Know - The Secrets, The Lies, The Unspoken Truth - Smith and Doe
90% (20)
What Men Dont Want Women To Know - The Secrets, The Lies, The Unspoken Truth - Smith and Doe
157 pages
Free Cash App Money
60% (20)
Free Cash App Money
6 pages
Attached The New Science of Adult Attach PDF
7% (28)
Attached The New Science of Adult Attach PDF
3 pages
Ultimate Tradeline Guide PDF
46% (13)
Ultimate Tradeline Guide PDF
23 pages
Cell Phone Lock Removal
80% (10)
Cell Phone Lock Removal
32 pages
Latest Sba Method To Get 10K+ Loans (Updated)
83% (6)
Latest Sba Method To Get 10K+ Loans (Updated)
5 pages
Storm Kings Thunder
100% (19)
Storm Kings Thunder
258 pages
Autism Spectrum Ratig Scales
71% (7)
Autism Spectrum Ratig Scales
16 pages
Scores
26% (23)
Scores
12 pages
Hacking Uber For Profite PDF
100% (6)
Hacking Uber For Profite PDF
5 pages
Money Dropper: Drop Money Like It'S Hot: Leaked by Captaincrunch
75% (4)
Money Dropper: Drop Money Like It'S Hot: Leaked by Captaincrunch
10 pages
Gambrel Barn and Shed Plans Construction Blueprints (John Davidson, Specialized Design Systems)
100% (1)
Gambrel Barn and Shed Plans Construction Blueprints (John Davidson, Specialized Design Systems)
85 pages
Learning R Programming
From Everand
Learning R Programming
Kun Ren
5/5 (3)
Python Essentials
From Everand
Python Essentials
Steven F. Lott
5/5 (7)
Window NT Shell Scripting PDF
No ratings yet
Window NT Shell Scripting PDF
386 pages
47 Easy DIY Survival Projects
94% (16)
47 Easy DIY Survival Projects
97 pages
Make Over $500 A Day Now With Secret Crack With Free Money
100% (11)
Make Over $500 A Day Now With Secret Crack With Free Money
13 pages
Rocket Loan Method
90% (10)
Rocket Loan Method
10 pages
Skip Tracing 101
100% (1)
Skip Tracing 101
5 pages
The Ultimate Drop Shipping Cheat Sheet
100% (1)
The Ultimate Drop Shipping Cheat Sheet
18 pages
Hacking I Cloud
83% (6)
Hacking I Cloud
34 pages
Mastering Objectoriented Python
From Everand
Mastering Objectoriented Python
Steven F. Lott
5/5 (2)
Mastering Django: Core
From Everand
Mastering Django: Core
Nigel George
3/5 (1)
Responsive Web Design with HTML5 and CSS3 - Second Edition
From Everand
Responsive Web Design with HTML5 and CSS3 - Second Edition
Ben Frain
4/5 (1)
Force.com Enterprise Architecture
From Everand
Force.com Enterprise Architecture
Andrew Fawcett
4.5/5 (2)
Oracle Application Express 3.2: The Essentials and More
From Everand
Oracle Application Express 3.2: The Essentials and More
Arie Geller
No ratings yet
Learning Django
No ratings yet
Learning Django
228 pages
Free Woodworking Plans Projects
100% (5)
Free Woodworking Plans Projects
440 pages
Habit Stacking
100% (41)
Habit Stacking
73 pages
Mastering TypoScript: TYPO3 Website, Template, and Extension Development
From Everand
Mastering TypoScript: TYPO3 Website, Template, and Extension Development
Daniel Koch
No ratings yet
Oracle SQL Developer 2.1
From Everand
Oracle SQL Developer 2.1
Sue Harper
No ratings yet
Excel 2013 Power Programming with VBA
From Everand
Excel 2013 Power Programming with VBA
John Walkenbach
5/5 (1)
JavaScript Introduction
From Everand
JavaScript Introduction
Lisa Saldivar
No ratings yet
Expert PHP 5 Tools
From Everand
Expert PHP 5 Tools
Dirk Merkel
4/5 (5)
Developing Microsoft Dynamics GP Business Applications
From Everand
Developing Microsoft Dynamics GP Business Applications
Leslie Vail
No ratings yet
Office 2011 for Mac For Dummies
From Everand
Office 2011 for Mac For Dummies
Bob LeVitus
No ratings yet
Microsoft Office 2008 for Mac Bible
From Everand
Microsoft Office 2008 for Mac Bible
Sherry Kinkoph Gunter
No ratings yet
IBM Lotus Domino: Classic Web Application Development Techniques
From Everand
IBM Lotus Domino: Classic Web Application Development Techniques
Richard G. Ellis
No ratings yet
InDesign CS4 Bible
From Everand
InDesign CS4 Bible
Galen Gruman
No ratings yet
Mastering Elasticsearch 5.x - Third Edition
From Everand
Mastering Elasticsearch 5.x - Third Edition
Bharvi Dixit
3/5 (1)
AppleScript
From Everand
AppleScript
Mark Conway Munro
5/5 (1)
Schematron: A language for validating XML
From Everand
Schematron: A language for validating XML
Erik Siegel
No ratings yet
Mastering Joomla! 1.5 Extension and Framework Development: The Professional Guide to Programming Joomla!
From Everand
Mastering Joomla! 1.5 Extension and Framework Development: The Professional Guide to Programming Joomla!
Chuck Lanham
4/5 (3)
Django 1.0 Template Development
From Everand
Django 1.0 Template Development
Scott Newman
No ratings yet
Drupal 7 First Look
From Everand
Drupal 7 First Look
Mark Noble
No ratings yet
Microsoft Visio 2013 Business Process Diagramming and Validation
From Everand
Microsoft Visio 2013 Business Process Diagramming and Validation
David J. Parker
No ratings yet
ElasticSearch Server
From Everand
ElasticSearch Server
Rafal Kuc
No ratings yet
Backbase 4 RIA Development
From Everand
Backbase 4 RIA Development
Ghica van Emde Boas
No ratings yet
The Rust Programming Language, 2nd Edition
From Everand
The Rust Programming Language, 2nd Edition
Steve Klabnik
No ratings yet
Crystal Reports Introduction: Versions 2008-2016
From Everand
Crystal Reports Introduction: Versions 2008-2016
Seth Bonder
No ratings yet
MCSD Certification Toolkit (Exam 70-483): Programming in C#
From Everand
MCSD Certification Toolkit (Exam 70-483): Programming in C#
Rod Stephens
3/5 (2)
Oracle ADF Enterprise Application Development – Made Simple : Second Edition
From Everand
Oracle ADF Enterprise Application Development – Made Simple : Second Edition
Sten E. Vesterli
No ratings yet
Office 2011 for Mac All-in-One For Dummies
From Everand
Office 2011 for Mac All-in-One For Dummies
Geetesh Bajaj
No ratings yet
Microsoft Dynamics CRM 2011 Customization & Configuration (MB2-866) Certification Guide
From Everand
Microsoft Dynamics CRM 2011 Customization & Configuration (MB2-866) Certification Guide
Neil Benson
No ratings yet
SQL Server 2014 Development Essentials
From Everand
SQL Server 2014 Development Essentials
Basit A. Masood-Al-Farooq
4.5/5 (2)
Mastering Bootstrap 5: From Basics to Expert Projects
From Everand
Mastering Bootstrap 5: From Basics to Expert Projects
Kameron Hussain
No ratings yet
Mastering Splunk
From Everand
Mastering Splunk
James Miller
No ratings yet
Mastering Ext JS - Second Edition
From Everand
Mastering Ext JS - Second Edition
Loiane Groner
No ratings yet
Learn Professional Programming in .Net Using C#, Visual Basic, and Asp.Net
From Everand
Learn Professional Programming in .Net Using C#, Visual Basic, and Asp.Net
Adalat Khan
No ratings yet
Functional Python Programming
From Everand
Functional Python Programming
Steven Lott
No ratings yet
SQLite Database Programming for Xamarin: Cross-platform C# database development for iOS and Android using SQLite.XM
From Everand
SQLite Database Programming for Xamarin: Cross-platform C# database development for iOS and Android using SQLite.XM
Anthony Serpico
No ratings yet
Mastering KnockoutJS
From Everand
Mastering KnockoutJS
Timothy Moran
No ratings yet
Odoo 10 Development Essentials
From Everand
Odoo 10 Development Essentials
Daniel Reis
No ratings yet
Processing XML documents with Oracle JDeveloper 11g
From Everand
Processing XML documents with Oracle JDeveloper 11g
Deepak Vohra
No ratings yet
Mastering Swift
From Everand
Mastering Swift
Jon Hoffman
No ratings yet
Mastering phpMyAdmin 3.4 for Effective MySQL Management
From Everand
Mastering phpMyAdmin 3.4 for Effective MySQL Management
Marc Delisle
No ratings yet
SDL Trados Studio – A Practical Guide
From Everand
SDL Trados Studio – A Practical Guide
Andy Walker
5/5 (1)
Microsoft Dynamics GP 2013 Reporting, Second Edition
From Everand
Microsoft Dynamics GP 2013 Reporting, Second Edition
David Duncan
5/5 (2)
Data Analytics & Visualization All-in-One For Dummies
From Everand
Data Analytics & Visualization All-in-One For Dummies
Jack A. Hyman
No ratings yet
Excel 2010 Bible
From Everand
Excel 2010 Bible
John Walkenbach
No ratings yet
ASP.NET 3.5 Social Networking
From Everand
ASP.NET 3.5 Social Networking
Andrew Siemer
No ratings yet
Drupal 8 Theming with Twig: Master Drupal 8's new Twig templating engine to create fun and fast websites with simple steps to help you move from concept to completion
From Everand
Drupal 8 Theming with Twig: Master Drupal 8's new Twig templating engine to create fun and fast websites with simple steps to help you move from concept to completion
Chaz Chumley
3.5/5 (3)
Microsoft Dynamics GP 2010 Reporting
From Everand
Microsoft Dynamics GP 2010 Reporting
Christopher Liley
5/5 (2)
Mastering phpMyAdmin 3.3.x for Effective MySQL Management
From Everand
Mastering phpMyAdmin 3.3.x for Effective MySQL Management
Marc Delisle
No ratings yet
Professional Plone 4 Development
From Everand
Professional Plone 4 Development
Martin Aspeli
3.5/5 (5)
Scrivener For Dummies
From Everand
Scrivener For Dummies
Gwen Hernandez
4/5 (25)
Access 2010 Bible
From Everand
Access 2010 Bible
Michael R. Groh
5/5 (1)
Visual SourceSafe 2005 Software Configuration Management in Practice
From Everand
Visual SourceSafe 2005 Software Configuration Management in Practice
Aleksandar Seovic
No ratings yet
Ivor Horton's Beginning Visual C++ 2013
From Everand
Ivor Horton's Beginning Visual C++ 2013
Ivor Horton
No ratings yet
Learn XQuery 10
No ratings yet
Learn XQuery 10
11 pages
Learning XSLT A Hands On Introduction to XSLT and XPath 1st Edition Michael James Fitzgerald - Instantly access the full ebook content in just a few seconds
100% (1)
Learning XSLT A Hands On Introduction to XSLT and XPath 1st Edition Michael James Fitzgerald - Instantly access the full ebook content in just a few seconds
33 pages
Combinepdf 15
No ratings yet
Combinepdf 15
23 pages
Git Cheatsheet
No ratings yet
Git Cheatsheet
11 pages
PowerShell Transcript - montEMPPC.hcuzU4vi.20220413113738
No ratings yet
PowerShell Transcript - montEMPPC.hcuzU4vi.20220413113738
50 pages
MOdelica HXbase
No ratings yet
MOdelica HXbase
17 pages
Cplusplus Abs Beginer
No ratings yet
Cplusplus Abs Beginer
5 pages
PowerShell Transcript - montEMPPC.yzzv9+Wb.20220328190014
No ratings yet
PowerShell Transcript - montEMPPC.yzzv9+Wb.20220328190014
76 pages
Unit3 PDMS Databases
No ratings yet
Unit3 PDMS Databases
4 pages
COSMOS 3D Integration Administration EnUS en-US
No ratings yet
COSMOS 3D Integration Administration EnUS en-US
160 pages
Frequency Modelling and Solution of FSI in Complex Pipelines Final Nonformatted
No ratings yet
Frequency Modelling and Solution of FSI in Complex Pipelines Final Nonformatted
38 pages
Engineering Guide For Fire Protection and Detection Systems
100% (1)
Engineering Guide For Fire Protection and Detection Systems
151 pages
PIPE5 Finite Element Analysis For Buried Structures
No ratings yet
PIPE5 Finite Element Analysis For Buried Structures
149 pages
Dynamic Analysis of Fluid-Filled Piping System On Flexible Foundation
No ratings yet
Dynamic Analysis of Fluid-Filled Piping System On Flexible Foundation
10 pages
100 Money Apps and Life Hacks
No ratings yet
100 Money Apps and Life Hacks
8 pages
A Photographers Guide To RAW in Photoshop
No ratings yet
A Photographers Guide To RAW in Photoshop
228 pages
100 Fiverr Gigs You Can Sell Right Now PDF
80% (5)
100 Fiverr Gigs You Can Sell Right Now PDF
23 pages
Fastrack To Free Everything
100% (4)
Fastrack To Free Everything
100 pages
Ten Apples Up On Top! Pages 1 - 50 - Flip PDF Download - FlipHTML5
100% (1)
Ten Apples Up On Top! Pages 1 - 50 - Flip PDF Download - FlipHTML5
65 pages
Useful Websites
50% (2)
Useful Websites
18 pages
Adobe Illustrator
No ratings yet
Adobe Illustrator
84 pages
Apps For Musicians
100% (1)
Apps For Musicians
2 pages
Google Drive Quick Reference Guide
75% (4)
Google Drive Quick Reference Guide
4 pages
Discovering Family History
0% (1)
Discovering Family History
56 pages
XML Unit 2 Notes
No ratings yet
XML Unit 2 Notes
24 pages
WDM Practical Vedant
No ratings yet
WDM Practical Vedant
40 pages
Public - XML Compare
No ratings yet
Public - XML Compare
30 pages
Font 1
No ratings yet
Font 1
9 pages
Script para Convidar Todos Do Facebook para Curtir Página.
No ratings yet
Script para Convidar Todos Do Facebook para Curtir Página.
2 pages
Introduction To XML Extensible Markup Language: Carol Wolf Computer Science Department
No ratings yet
Introduction To XML Extensible Markup Language: Carol Wolf Computer Science Department
26 pages
Untitled
100% (1)
Untitled
2 pages
WDM Question Bank For Mid-Sem Exam
100% (1)
WDM Question Bank For Mid-Sem Exam
2 pages
The XML Example Document: View The "Books - XML" File in Your Browser
No ratings yet
The XML Example Document: View The "Books - XML" File in Your Browser
4 pages
Practical 10 Working With Ajax and XML
No ratings yet
Practical 10 Working With Ajax and XML
6 pages
Multi-Tiered Architecture of Data Warehousing and Data Mining
No ratings yet
Multi-Tiered Architecture of Data Warehousing and Data Mining
39 pages
Flowchart Listing
No ratings yet
Flowchart Listing
54 pages
Soap Serialization and Deserialization - Program
No ratings yet
Soap Serialization and Deserialization - Program
3 pages
2024-03-06 15点的log 0
No ratings yet
2024-03-06 15点的log 0
55 pages
Introduction To XML and Its Applications
No ratings yet
Introduction To XML and Its Applications
32 pages
XML Final Skima
No ratings yet
XML Final Skima
33 pages
innerHTML Vs Innertext Vs Textcontent
No ratings yet
innerHTML Vs Innertext Vs Textcontent
4 pages